simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 整理项目结构，清理归档文件，更新部署配置

Browse Source
This commit is contained in:
Simon
2026-07-04 21:01:39 +08:00
parent 8bd4ab0366
commit 64ff1bf7d5
508 changed files with 43575 additions and 14129 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/01-项目总览/00-索引-20260704.md
+172
View File
@@ -0,0 +1,172 @@
# 文档索引
> **版本**: v2.0 | **日期**: 2026-07-04 | **维护人**: 助理
> **说明**: 本索引提供 docs/ 目录下所有文档的快速导航
---
## 📚 文档目录结构
```
docs/
├── 01-项目总览/ ← 核心文档（必读）
├── 02-产品需求/ ← PRD、功能需求
├── 03-技术架构/ ← 架构设计、ADR、图表
├── 04-原型设计/ ← UI/UX原型
├── 05-用户手册/ ← 用户指南
├── 06-测试质量/ ← 测试文档
├── 07-代码评审/ ← Code Review
├── 08-安全审计/ ← 安全、集成分析
├── 09-部署运维/ ← 部署、运维、故障排查
├── 10-项目管理/ ← SOP、项目管理
└── 11-历史归档/ ← 历史归档
```
---
## 📋 核心文档（必读）
| 文档 | 路径 | 说明 |
|------|------|------|
| 项目总览与部署手册 | `01-项目总览/01-项目总览与部署手册-20260704.md` | 项目背景、架构、三阶段演进 |
| 智能IT服务系统运维手册 | `01-项目总览/01-智能IT服务系统运维手册-20260704.md` | 部署、运维、故障处理 |
| 项目知识库 | `01-项目总览/01-项目知识库-20260704.md` | 全量知识库汇总 |
| 资源申请清单 | `01-项目总览/01-资源申请清单-20260704.md` | IT 资源申请记录 |
---
## 📂 各目录文档清单
### 01-项目总览/
| 文档 | 说明 |
|------|------|
| `00-索引-20260704.md` | 本索引文档 |
| `01-项目总览与部署手册-20260704.md` | v2.2，项目完整概览 |
| `01-智能IT服务系统运维手册-20260704.md` | v1.0，统一运维手册 |
| `01-资源申请清单-20260704.md` | IT 资源申请记录 |
| `01-项目知识库-20260704.md` | 项目全量知识库 |
| `01-IT智能服务台_项目汇报-20260704.html` | 项目汇报演示 |
| `02-项目迁移文档-20260606.md` | 项目迁移文档 |
| `03-项目全面评估报告-20260625.md` | 项目全面评估报告 |
### 02-产品需求/
| 文档 | 说明 |
|------|------|
| `02-产品需求文档PRD-v1.2-20260704.md` | 主 PRD 文档（v1.2，2026-07-04更新） |
| `product-产品/v0.7.2-backlog-candidate-2026-06-24.md` | 需求候选池 |
### 03-技术架构/
| 目录/文档 | 说明 |
|------|------|
| `00-系统架构设计文档-v1.0.md` | 系统架构设计（v1.0） |
| `01-ADRs-架构决策/` | 4 | 架构决策记录 |
| `02-技术方案/` | 5 | 技术方案文档 |
| `03-技术分析/` | 3 | 技术分析报告 |
| `04-数据库设计/` | 1 | 数据库设计 |
| `05-架构图/` | 9 | Mermaid 图表 |
### 04-原型设计/
| 子目录 | 文档数 | 说明 |
|--------|--------|------|
| `prototypes-原型图/` | 12 | 活跃原型图 |
| `prototypes-原型图/archive/` | 17 | 历史版本 |
### 05-用户手册/
> 待添加用户手册
### 06-测试质量/
| 文档 | 说明 |
|------|------|
| `03-调试验证指南-20260613.md` | 调试验证指南 |
| `testing-测试/E2E-CHECKLIST-v0.7.0.md` | E2E 验收清单 |
| `testing-测试/TESTING_CALL_AGENT.md` | 呼叫坐席测试 |
| `testing-测试/QA_COMPREHENSIVE_REPORT.md` | QA 综合报告 |
### 07-代码评审/
| 文档 | 说明 |
|------|------|
| `评审报告-代码评审/workbuddy-2026-06-14-P0安全.md` | P0 安全评审 |
| `评审报告-代码评审/workbuddy-2026-06-14-消息优化.md` | 消息优化评审 |
| `评审报告-代码评审/workbuddy-2026-06-14-消息优化-P1二次评审.md` | 消息优化二次评审 |
| `评审报告-代码评审/workbuddy-2026-06-14-Gitea重建.md` | Gitea 重建评审 |
| `评审报告-代码评审/workbuddy-2026-06-14-预检验证.md` | 预检验证评审 |
| `评审报告-代码评审/workbuddy-2026-06-15-T组A组.md` | T组A组评审 |
| `评审报告-代码评审/REVIEW_B_T10-消息可靠性增强.md` | B-T10 消息可靠性评审 |
### 08-安全审计/
| 子目录 | 文档数 | 说明 |
|--------|--------|------|
| `审计报告-安全审计/` | 3 | 安全审计报告 |
| `集成分析-外部系统/` | 3 | 外部系统集成分析 |
### 09-部署运维/
| 文档 | 说明 |
|------|------|
| `deploy/03-RELEASE-NOTES-v0.7.1-20260623.md` | v0.7.1 发布说明 |
| `deploy/04-部署修复记录-20260613.md` | 部署修复记录 |
| `deploy/05-版本更新说明-v1.1.0-20260614.md` | 版本更新说明 v1.1.0 |
| `deploy/06-OTP二次验证实现.md` | OTP 二次验证实现 |
| `deploy/07-扫码登录OTP部署指南-v0.7.0.md` | 扫码登录OTP部署指南 |
| `deploy/08-NAS部署指南-预生产.md` | NAS部署指南(预生产) |
| `deploy/09-NAS部署指南-群晖Cloudflare.md` | NAS部署指南(群晖) |
| `deploy/10-一键部署操作包-v0.7.0.md` | 一键部署操作包 |
| `deploy/` | 7 | 部署文档 |
| `troubleshooting-故障排查/` | 1 | 故障排查 |
| `guides-用户指南/` | 1 | 用户指南 |
### 10-项目管理/
| 编号 | 文档 | 说明 |
|------|------|------|
| 01 | `01-任务总索引.md` | 任务管理文档体系总览 |
| 02 | `02-风险跟踪表.md` | 风险登记册（22项） |
| 03 | `03-项目任务状态报告.md` | 历史全量任务（152个） |
| 04 | `04-项目开发任务调整建议.md` | 任务调整建议 |
| 05 | `05-项目状态看板/01-项目状态看板.md` | 驾驶舱仪表盘 |
| SOPs | `SOPs-标准流程/` | 4项标准操作流程 |
### 11-历史归档/
> 历史归档文档，包含 `-archived-日期` 后缀
---
## 🔗 快速链接
| 场景 | 推荐文档 |
|------|---------|
| 新人入职 | `01-项目总览/01-项目总览与部署手册-20260704.md` |
| 部署上线 | `01-项目总览/01-智能IT服务系统运维手册-20260704.md` |
| 故障排查 | `09-部署运维/troubleshooting-故障排查/` |
| 代码评审 | `07-代码评审/评审报告-代码评审/` |
| 安全合规 | `08-安全审计/` |
| 运维操作 | `10-项目管理/SOPs-标准流程/` |
---
## 📝 文档更新规则
| 更新类型 | 同步要求 |
|---------|---------|
| 新增文档 | 添加到对应目录 + 本索引 |
| 删除文档 | 从本索引移除 |
| 移动文档 | 更新本索引路径 |
| 重大变更 | 同步更新 `CHANGELOG.md` |
---
## 📅 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| v2.0 | 2026-07-04 | 目录结构重组，完成重命名 |
| v1.0 | 2026-07-04 | 初始版本，索引创建 |
docs/01-项目总览/01-IT智能服务台_项目汇报-20260704.html
+1039
View File
File diff suppressed because it is too large Load Diff
docs/01-项目总览/01-智能IT服务系统运维手册-20260704.md
+495
View File
@@ -0,0 +1,495 @@
# 智能IT服务系统运维手册
> **版本**: v1.0 | **日期**: 2026-07-04 | **维护人**: 助理（小米）
> **目标读者**: 运维工程师 / IT支持组
> **📖 关联文档**:
> - [README.md](../README.md) — 项目快速入门
> - [01-项目总览与部署手册.md](./01-项目总览与部署手册.md) — 完整架构设计
> - [CHANGELOG.md](../CHANGELOG.md) — 版本变更概览
> - [docs/archive/](./archive/) — 历史版本详情
---
## 目录
1. [系统概述](#一系统概述)
2. [环境信息](#二环境信息)
3. [部署操作](#三部署操作)
4. [日常运维](#四日常运维)
5. [故障排查](#五故障排查)
6. [回滚方案](#六回滚方案)
7. [备份恢复](#七备份恢复)
8. [应急响应](#八应急响应)
---
## 一、系统概述
### 1.1 系统架构
```
浏览器 ──→ itsupport.servyou.com.cn:443
│
▼
┌─── nginx (容器) ───────────────┐
│ │
│ /itdesk/* → H5 员工端 SPA │
│ /itagent/* → 坐席工作台 SPA │
│ /itadmin/* → 管理后台 SPA │
│ /itportal/* → Portal 选择页 │
│ /api/* → backend:8000 │
│ /ws/* → backend:8000 (WS)│
│ │
└──────────────┬───────────────────┘
│ 本机 Docker 网络
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ backend │ │ postgres │ │ redis │
│ :8000 │ │ :5432 │ │ :6379 │
└──────────┘ └──────────┘ └──────────┘
```
### 1.2 组件清单
| 服务 | 镜像 | 端口 | 说明 |
|------|------|------|------|
| nginx | nginx:alpine | 443→80 (对外) | 反向代理 + SSL |
| backend | 自构建 | 8000 (内部) | FastAPI 后端 |
| postgres | postgres:16 | 5432 (内部) | 数据库 |
| redis | redis:7 | 6379 (内部) | 缓存 + Session |
### 1.3 访问端点
| 端点 | 说明 |
|------|------|
| `https://itsupport.servyou.com.cn/itdesk/` | H5 员工端 |
| `https://itsupport.servyou.com.cn/itagent/` | 坐席工作台 |
| `https://itsupport.servyou.com.cn/itadmin/` | 管理后台 |
| `https://itsupport.servyou.com.cn/itportal/` | Portal 角色选择 |
| `https://itsupport.servyou.com.cn/api/docs` | API Swagger 文档 |
---
## 二、环境信息
### 2.1 服务器信息
| 环境 | IP | 域名 | 用途 |
|------|-----|------|------|
| 生产 | 10.90.5.110 (内网) | itsupport.servyou.com.cn | 正式环境 |
| 运维入口 | 10.212.189.210:2222 | - | 堡垒机 SSH |
### 2.2 关键配置
| 配置项 | 值 |
|--------|-----|
| 企微 CorpID | `ww...` (见 .env) |
| 企微 AgentID | `1000xxx` |
| 数据库 | PostgreSQL 16 |
| 缓存 | Redis 7 |
| 域名证书 | `*.servyou.com.cn` (GeoTrust/DigiCert) |
### 2.3 部署路径
```
/opt/wecom-it-desk/
├── docker-compose.yml
├── .env # 环境变量（不提交 Git）
├── backend/ # 后端代码
├── frontend-h5/dist/ # H5 前端构建产物
├── frontend-agent/dist/ # 坐席前端构建产物
├── frontend-admin/dist/ # 管理后台构建产物
├── frontend-portal/dist/ # Portal 构建产物
├── nginx/ # Nginx 配置
└── logs/ # 日志目录
```
---
## 三、部署操作
### 3.1 部署流程概览
```
1. 打包代码 → 2. 上传服务器 → 3. 配置环境变量 → 4. 启动容器 → 5. 验证
```
### 3.2 打包命令（本地）
```bash
# 在项目根目录执行
cd D:\资料\03-项目开发\wecom_it_smart_desk
# 使用部署脚本打包
powershell -File deploy-server\build-package.ps1
# 或手动打包
tar czf deploy.tar.gz \
backend/ frontend-h5/dist/ frontend-agent/dist/ \
frontend-admin/dist/ frontend-portal/dist/ \
nginx/ docker-compose.yml .env.production scripts/
```
### 3.3 上传到服务器
> **注意**: 公司服务器只能通过堡垒机上传，无法直接从本地 scp
1. **通过堡垒机上传到 `/tmp/`**：
- 使用 SFTP 或 Web 界面上传到堡垒机
2. **SSH 登录服务器**：
```bash
# 堡垒机: sxn@10.212.189.210:2222
ssh sxn@10.90.5.110 # 跳转目标服务器
```
3. **移动到目标目录**：
```bash
mv /tmp/deploy.tar.gz /opt/wecom-it-desk/
cd /opt/wecom-it-desk/
tar xzf deploy.tar.gz
```
### 3.4 配置环境变量
```bash
# 创建环境配置
cp .env.production .env
vim .env # 编辑真实配置
# 必填项：
# - WECOM_CORP_ID
# - WECOM_AGENT_ID
# - WECOM_SECRET
# - WECOM_TOKEN
# - WECOM_ENCODING_AES_KEY
# - POSTGRES_PASSWORD
# - REDIS_PASSWORD
```
### 3.5 启动服务
```bash
# 启动所有容器
docker compose up -d --build
# 或分步启动
docker compose up -d postgres redis # 先启动基础服务
docker compose up -d backend # 再启动后端
docker compose up -d nginx # 最后启动前端
```
### 3.6 验证部署
```bash
# 1. 检查容器状态
docker compose ps
# 预期：4 个容器全部 Up/healthy
# 2. 健康检查
curl -ksI https://itsupport.servyou.com.cn/api/health
# 3. 各端点验证
curl -ksI https://itsupport.servyou.com.cn/itdesk/
curl -ksI https://itsupport.servyou.com.cn/itagent/
curl -ksI https://itsupport.servyou.com.cn/itadmin/
curl -ksI https://itsupport.servyou.com.cn/itportal/
```
---
## 四、日常运维
### 4.1 日常检查
```bash
# 每日必做检查
docker compose ps # 容器状态
docker compose logs --tail=50 backend # 后端日志
docker compose logs --tail=50 nginx # 前端日志
df -h # 磁盘空间
```
### 4.2 常用操作
| 操作 | 命令 |
|------|------|
| 重启后端 | `docker compose restart backend` |
| 重启 nginx | `docker compose restart nginx` |
| 查看实时日志 | `docker compose logs -f backend` |
| 进入后端容器 | `docker compose exec backend bash` |
| 查看容器资源 | `docker stats` |
### 4.3 监控指标
| 指标 | 阈值 | 说明 |
|------|------|------|
| CPU 使用率 | < 80% | 主机层面 |
| 内存使用率 | < 80% | 主机层面 |
| 磁盘使用率 | < 70% | 主机层面 |
| 容器状态 | 全部 Up | docker compose ps |
| API 响应时间 | P95 < 500ms | 业务层面 |
### 4.4 日志位置
| 服务 | 日志命令 |
|------|----------|
| 后端 | `docker compose logs backend` |
| Nginx | `docker compose logs nginx` |
| PostgreSQL | `docker compose logs postgres` |
| Redis | `docker compose logs redis` |
---
## 五、故障排查
### 5.1 快速诊断流程
```
1. 检查容器状态 → 2. 检查端口连通 → 3. 检查日志 → 4. 定位根因
```
### 5.2 常见问题
#### 问题 1: 访问返回 500 错误
```bash
# 1. 检查容器状态
docker compose ps
# 2. 检查后端日志
docker compose logs --tail=100 backend
# 3. 检查 nginx 日志
docker compose logs --tail=100 nginx
# 4. 检查前端 dist 是否存在
ls /opt/wecom-it-desk/frontend-h5/dist/
docker compose exec nginx ls /usr/share/nginx/html/itdesk/
```
#### 问题 2: API 返回连接错误
```bash
# 1. 检查后端是否启动
docker compose ps backend
# 2. 检查后端健康端点
curl http://localhost:8000/health
# 3. 检查数据库连接
docker compose exec backend python -c "from app.database import get_db; print('OK')"
```
#### 问题 3: WebSocket 连接失败
```bash
# 1. 检查 nginx WebSocket 配置
docker compose exec nginx cat /etc/nginx/nginx.conf | grep -A10 ws
# 2. 检查 WS 端点
curl -I http://localhost:8000/ws/test
# 3. 检查 Redis（WS 依赖）
docker compose exec redis redis-cli ping
```
#### 问题 4: 企微工作台打开页面显示"加载失败"或无限加载（2026-07-04）
**现象**：员工通过企业微信-工作台-IT支持服务访问，显示加载失败或一直转圈
**排查步骤**：
```bash
# 1. 检查容器状态
docker ps
# 2. 检查 nginx 是否正确加载配置
docker exec wecom_it_nginx nginx -t
# 3. 检查前端页面访问
curl -I http://localhost/itdesk/
# 4. 检查 API 代理
curl -I http://localhost/api/h5/health
# 5. 查看后端日志（查找 NameError）
docker logs --tail=50 wecom_it_backend | grep -i error
```
**根因 1**：nginx 容器未正确挂载 nginx.conf 配置文件
- 表现：API 请求返回 404，nginx 错误日志显示 `open() "/usr/share/nginx/html/api/xxx" failed`
- 解决：重建 nginx 容器，确保正确挂载配置
```bash
# 重建 nginx 容器
docker rm -f wecom_it_nginx
docker run -d --name wecom_it_nginx \
--network wecom-it-desk_it-desk-internal \
-p 80:80 -p 443:443 \
-v /opt/wecom-it-desk/html:/usr/share/nginx/html:ro \
-v /opt/wecom-it-desk/nginx/nginx.conf:/etc/nginx/nginx.conf:ro \
-v /opt/wecom-it-desk/nginx/ssl:/etc/nginx/ssl:rw \
--restart unless-stopped nginx:1.27-alpine
# 重新加载配置
docker exec wecom_it_nginx nginx -s reload
```
**根因 2**：后端 h5.py 代码存在 NameError
- 表现：后端日志显示 `NameError: name '_require_wework_ua' is not defined`
- 原因：生产服务器代码未同步最新版本
- 解决：复制最新代码并重启后端
```bash
# 复制最新代码
docker cp /opt/wecom-it-desk/backend/app/api/h5.py wecom_it_backend:/app/app/api/h5.py
# 重启后端
docker restart wecom_it_backend
```
### 5.3 完整诊断脚本
详细诊断脚本见：`docs/deploy/服务器端跑诊断.md`
```bash
# 一键诊断
bash /opt/wecom-it-desk/diagnose-500.sh
```
---
## 六、回滚方案
### 6.1 快速回滚
```bash
# 停止当前版本
docker compose down
# 恢复上一个版本（需提前备份）
# 方法1: 从 Git 拉取上一个 commit
git checkout {上一个commit-hash}
# 重新构建部署
# 方法2: 保留上一个版本的部署包
cd /opt/wecom-it-desk-backup
tar xzf deploy-v0.x.x.tar.gz
docker compose up -d
```
### 6.2 回滚检查清单
- [ ] 确认上一个版本可用
- [ ] 通知相关人员
- [ ] 记录当前版本问题
- [ ] 执行回滚
- [ ] 验证回滚后功能正常
- [ ] 发送回滚通知
---
## 七、备份恢复
### 7.1 备份策略
| 备份对象 | 方法 | 频率 | 保留 |
|---------|------|------|------|
| PostgreSQL | pg_dump | 每日凌晨 | 7 天 |
| Redis | redis-cli SAVE | 每日凌晨 | 7 天 |
| 配置文件 | tar 归档 | 每次部署 | 4 个版本 |
| 日志文件 | logrotate | 每周 | 4 周 |
### 7.2 备份命令
```bash
# 备份数据库
docker compose exec postgres pg_dump -U postgres wecom_it > /tmp/backup_$(date +%Y%m%d).sql
# 备份 Redis
docker compose exec redis redis-cli SAVE
cp /var/lib/docker/volumes/wecom-it-desk_redis_data/_data/dump.rdb /tmp/redis_$(date +%Y%m%d).rdb
# 备份配置
tar czf /tmp/config_$(date +%Y%m%d).tar.gz /opt/wecom-it-desk/.env /opt/wecom-it-desk/nginx/
```
### 7.3 恢复命令
```bash
# 恢复数据库
docker compose exec -T postgres psql -U postgres wecom_it < backup_20260701.sql
# 恢复 Redis
docker compose exec -T redis redis-cli FLUSHALL
# 停止服务后复制 dump.rdb 到数据目录
```
---
## 八、应急响应
### 8.1 事件分级
| 等级 | 场景 | 响应时间 |
|------|------|----------|
| 🔴 P0 | 鉴权漏洞 / 数据泄露 / 服务全停 | 5 min |
| 🟠 P1 | 功能故障 / 单服务降级 | 30 min |
| 🟡 P2 | 性能问题 / UI 异常 | 4 h |
| 🟢 P3 | 体验优化 | 1 周 |
### 8.2 P0 应急流程
#### 立即止血
```bash
# 1. 关闭外网访问
sudo iptables -A INPUT -p tcp --dport 443 -j DROP
# 2. 停可疑服务
docker compose stop backend
# 3. 保留现场（不删文件）
docker compose logs backend > /tmp/incident-backend.log
docker compose logs nginx > /tmp/incident-nginx.log
```
#### 通知
- 微信/电话通知项目负责人
- 邮件通知：`wecom-it-desk-incident@servyou-it.com`
### 8.3 应急联系
| 角色 | 联系人 |
|------|--------|
| 项目负责人 | 宋献 |
| 运维 | IT 支持组 |
| 企微技术支持 | 企微客服 |
---
## 附录
### 版本历史
| 版本 | 日期 | 更新内容 |
|------|------|----------|
| v1.0 | 2026-07-04 | 初始版本，整合部署/运维/故障排查文档 |
### 相关文档
| 文档 | 说明 |
|------|------|
| `docs/01-项目总览与部署手册.md` | 完整项目背景与架构设计 |
| `docs/RELEASE_NOTES_v0.7.1.md` | 版本发布说明 |
| `docs/SOPs/SOP-004-应急响应.md` | 详细应急响应流程 |
| `docs/deploy/快速诊断-500-错误.md` | 500 错误排查指南 |
| `docs/IT服务台部署修复记录-2026-06-13.md` | 历史修复记录 |
---
> **维护说明**: 本文档由助理（小米）维护，随每次发布更新。
> 如有更新，请同步更新本文档的版本号和日期。
docs/01-项目总览/01-资源申请清单-20260704.md
+314
View File
@@ -0,0 +1,314 @@
# 智能IT支持服务台 — 资源申请清单
> **📌 使用说明（工作流程）**
>
> 本文档是 智能IT支持服务台 所有资源申请需求的**统一汇总入口**，适用于：
> - 服务器/域名/网络等资源申请
> - 外部系统 API 对接申请（联软、火绒、aTrust、北森 eHR 等）
> - 任何需要向其他团队（运维/安全/网络）申请权限或资源的任务
>
> **工作流程**：
> 1. 新需求直接添加到本文档对应章节（无对应章节则新建）
> 2. **不单独发送企微消息、邮件或工单** — 所有需求集中在此文档跟踪
> 3. 申请完成后在文档中更新状态（✅/🔄/❌）
>
> **负责人**：宋献（IT支持组，负责终端安全，火绒/联软超管）
---
## 一、背景
智能IT支持服务台（IT Smart Desk）包含两个部署环境，需向运维申请服务器、域名及反向代理资源：
| 环境 | 用途 | 部署位置 | 访问方式 |
|------|------|---------|---------|
| **预生产** | 内网功能验证 | G端服务器 `10.80.0.129` | 公司内网域名 |
| **生产** | 企微端实际使用 | 公司内网服务器 `10.90.5.110` | WAF/域名直连 |
---
## 二、服务器资源
### 2.1 预生产环境 — G端服务器
| 项目 | 信息 |
|------|------|
| **服务器 IP** | `10.80.0.129` |
| **用途** | 预生产验证（内网测试） |
| **服务端口** | `18080`（Docker Nginx 容器暴露端口） |
| **部署方式** | Docker Compose 4容器（postgres + redis + backend + nginx） |
| **部署路径** | `/home/admin/itdesk/` |
| **现有域名** | `it-dataquery.dc.servyou-it.com`（与数据查询平台共用） |
| **状态** | ✅ 已部署运行 |
### 2.2 生产环境 — 公司内网服务器
| 项目 | 信息 |
|------|------|
| **服务器 IP** | `10.90.5.110` |
| **用途** | 生产环境（企微端实际使用） |
| **部署方式** | Docker Compose 4容器（nginx + backend + postgres + redis） |
| **部署路径** | `/opt/wecom-it-desk` |
| **外网访问** | WAF/域名直连 |
| **状态** | ✅ 已上线运行 |
---
## 三、域名资源
| 域名 | 环境 | 用途 | 类型 | 状态 |
|------|------|------|------|------|
| `it-dataquery.dc.servyou-it.com` | 预生产 | G端服务器反代入口（共用现有域名） | 公司内网域名 | ✅ 已有 |
| `itdesk.amanzac.com` | ~~生产（已下线）~~ | ~~NAS Cloudflare Tunnel 入口~~ | ~~已下线~~ | ❌ 已下线 |
| `itsupport.servyou.com.cn` | 生产（正式） | 公司内网服务器入口 | WAF/域名 | ✅ 已上线 |
> **说明**：
> - 预生产环境复用数据查询平台现有域名，新增 `/itdesk/`、`/itagent/`、`/api/`、`/ws/` 路径即可
> - ~~阶段一测试使用 Cloudflare Tunnel + `itdesk.amanzac.com`，已配置可用~~（已下线）
> - 生产环境已切换至 `itsupport.servyou.com.cn`（公司备案域名）
---
## 四、反向代理路由规则
### 4.1 预生产 — G端 Nginx 反代
在现有 `it-dataquery.dc.servyou-it.com` 的 Nginx 配置中，**新增以下 4 条 `location` 规则**，代理到 `10.80.0.129:18080`：
| 路径前缀 | 用途 | 目标 |
|----------|------|------|
| `/itdesk/` | H5 员工端（企微内置浏览器访问） | `http://10.80.0.129:18080/itdesk/` |
| `/itagent/` | 坐席工作台（PC 浏览器访问） | `http://10.80.0.129:18080/itagent/` |
| `/api/` | 后端 API 接口 | `http://10.80.0.129:18080/api/` |
| `/ws/` | WebSocket 长连接（预留） | `http://10.80.0.129:18080/ws/` |
> **⚠️ 重要**：`/` 根路径保持不变，继续代理到现有数据查询平台。
#### 建议 Nginx 配置片段
```nginx
# ==================== 智能IT支持服务台 — 预生产 ====================
# 后端 API
location /api/ {
proxy_pass http://10.80.0.129:18080/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# 企微回调超时设置
proxy_read_timeout 60s;
proxy_connect_timeout 10s;
}
# WebSocket（坐席端实时通知）
location /ws/ {
proxy_pass http://10.80.0.129:18080/ws/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3600s;
}
# H5 员工端
location /itdesk/ {
proxy_pass http://10.80.0.129:18080/itdesk/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
# 坐席工作台
location /itagent/ {
proxy_pass http://10.80.0.129:18080/itagent/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
```
### 4.2 生产环境 — Nginx（Docker 内部）
生产环境的 Nginx 已内置于 Docker Compose，**无需运维额外配置**。路由规则如下：
| 路径前缀 | 用途 | 目标 |
|----------|------|------|
| `/itdesk/` | H5 员工端 | 容器内静态文件 `/usr/share/nginx/html/itdesk/` |
| `/itagent/` | 坐席工作台 | 容器内静态文件 `/usr/share/nginx/html/itagent/` |
| `/api/` | 后端 API | `http://backend:8000/` |
| `/ws/` | WebSocket | `http://backend:8000`（upgrade） |
> 详细配置见 `nginx/nginx.conf`
---
## 五、网络连通性要求
### 5.1 预生产环境
| 源（发起方） | 目标 | 端口 | 协议 | 用途 |
|-------------|------|------|------|------|
| 数据平台 Nginx 主机 | `10.80.0.129` | `18080` | TCP/HTTP | 反向代理流量 |
| `10.80.0.129` | 企微 API `qyapi.weixin.qq.com` | `443` | TCP/HTTPS | 企微 Token/AccessToken/消息推送 |
| `10.80.0.129` | Dify AI 服务 `yw-dify.dc.servyou-it.com` | `443`（或内网端口） | TCP/HTTPS | AI 对话调用 |
#### 防火墙规则
```
# 入站规则（数据平台主机 → 10.80.0.129）
源: 数据平台主机IP → 目标: 10.80.0.129:18080 TCP 允许
# 出站规则（10.80.0.129 → 外部）
目标: qyapi.weixin.qq.com:443 TCP 允许 # 企微 API
目标: yw-dify.dc.servyou-it.com:443 TCP 允许 # Dify AI
```
### 5.2 生产环境
| 源（发起方） | 目标 | 端口 | 协议 | 用途 |
|-------------|------|------|------|------|
| 服务器 `10.90.5.110` | 企微 API `qyapi.weixin.qq.com` | `443` | TCP/HTTPS（出站） | 企微回调/消息推送 |
| 服务器 `10.90.5.110` | Dify AI 服务 | `443` | TCP/HTTPS（出站） | AI 对话调用（预留） |
| 办公网络 | 服务器 `10.90.5.110` | `18080` | TCP/HTTP | 内网调试访问（可选） |
> **说明**：生产环境通过 WAF/域名直连访问，无需 Tunnel。
---
## 六、SSL / HTTPS
| 环境 | 方案 | 状态 |
|------|------|------|
| 预生产 | 复用 `it-dataquery.dc.servyou-it.com` 现有证书 | ✅ 无需额外申请 |
| 生产 | 公司统一 SSL 证书（*.servyou.com.cn） | ✅ 已配置 |
---
## 七、验证方式
### 7.1 预生产环境
| 验证地址 | 预期结果 |
|----------|----------|
| `https://it-dataquery.dc.servyou-it.com/itdesk/` | 显示 H5 员工端页面 |
| `https://it-dataquery.dc.servyou-it.com/itagent/` | 显示坐席工作台页面 |
| `https://it-dataquery.dc.servyou-it.com/api/test-ping` | 返回 `{"code":0,"data":"pong"}` |
| `https://it-dataquery.dc.servyou-it.com/` | 保持原样，跳转到数据查询平台 |
### 7.2 生产环境
| 验证地址 | 预期结果 |
|----------|----------|
| `https://itsupport.servyou.com.cn/itdesk/` | 显示 H5 员工端页面 |
| `https://itsupport.servyou.com.cn/itagent/` | 显示坐席工作台页面 |
| `https://itsupport.servyou.com.cn/api/health` | 返回 `{"status":"healthy"}` |
| `http://10.90.5.110:18080/itdesk/` | 内网直连访问（调试用） |
---
## 九、外部系统 API 对接
### 9.1 联软 LV7000 — 终端管理系统
> 申请日期：2026-06-11 ｜ 负责人：宋献（联软超管） ｜ 优先级：P0（核心映射数据源）
#### 项目背景
智能IT支持服务台核心目标之一是**打通员工↔终端的映射链路**。联软LV7000拥有最准确的员工账号→终端设备映射数据（`strusername`字段），是终端信息集成的**核心数据源**。
#### API 账户（超管自建）
| 项目 | 说明 |
|------|------|
| **所需权限** | 终端设备查询（P0）、用户信息查询（P0）、准入状态查询（P1）、终端操作（P1） |
| **认证模式** | 全启：IP白名单 + 账号密码 + 一次性Token（纵深防御） |
| **所需信息** | 联软超管后台创建 `ApiAccount` + `ApiPassword`，确认内网访问地址（BaseURL） |
| **操作人** | 宋献（联软LV7000超管权限） |
#### 需要开通的 API 端点
**P0 — 核心查询（必须）**
| # | API 端点 | 用途 | 调用频率预估 |
|---|---------|------|------------|
| 1 | `/terminal?act=queryDevByParams` | 按员工账号/IP/MAC查询终端 | 每次会话 ~1次 |
| 2 | `/devallinfoshowwithpaging?act=getDevAllInfo` | 终端详细硬件+软件信息 | 每次会话 ~1次 |
| 3 | `/querydeptuser?act=getUserInfoByAccount` | 按账号查用户信息 | 缓存刷新，低频 |
| 4 | `/querydeptuser?act=getAllOrgInfo` | 组织架构全量同步 | 每日1次 |
**P1 — 操作与状态（建议）**
| # | API 端点 | 用途 | 调用频率预估 |
|---|---------|------|------------|
| 5 | `/access/onlineUser?act=existOnlineUser` | 查询终端在线状态 | 每次会话 ~1次 |
| 6 | `/terminal?act=noticeAgentMsg` | 向终端推送弹窗消息 | 按需，低频 |
| 7 | `/terminal?act=remoteWakeUp` | 远程唤醒终端 | 按需，极低频 |
| 8 | `/software?act=querysoftwarebydev` | 查询终端安装软件 | 缓存刷新，低频 |
| 9 | `/terminalaudit?act=queryClientPatchAuditInfo` | 补丁安装审计 | 缓存刷新，低频 |
> P1中的 `forcedOffline`（强制下线）为高危操作，初期**不申请**，待安全评审后再开通。
#### IP 白名单配置
需将以下服务器IP加入联软白名单：
| 环境 | 服务器 IP | 用途 |
|------|---------|------|
| 预生产 | `10.80.0.129` | 开发调试 + 功能测试 |
| 正式环境 | （待确认） | 生产部署 |
> 正式环境服务器IP待部署时确认后补报。
#### 网络可达性
需确认从以下节点可访问联软系统端口 **30098**：
- `10.80.0.129`（预生产服务器）
- 开发机（公司内网）
#### 需确认信息
| # | 确认事项 | 用途 |
|---|---------|------|
| 1 | 联软LV7000当前版本号 | 确认API文档是否匹配（参考版本：202210SP v1.1） |
| 2 | `strusername` 字段是否为公司的域账号/企微账号 | 确认员工→终端映射的匹配键 |
| 3 | 联软管理的终端数量 | 评估查询性能和缓存策略 |
| 4 | 公司终端安全助手安装率 | 评估映射覆盖率 |
| 5 | 联软系统内网访问地址 | API调用BaseURL |
| 6 | Token有效时长 | 确认缓存刷新策略（文档默认30分钟） |
| 7 | 是否有调用频率限制 | 防止触发限流 |
#### 安全承诺
1. API账户密码仅存储在环境变量中，**绝不**写入代码或版本库
2. Token仅存储在应用内存中，不落盘
3. 高危操作（强制下线等）需二次确认 + 审计日志，仅admin角色可执行
4. 员工敏感信息（邮箱/电话）前端不展示，后端按需过滤
5. 所有API调用记录审计日志，可追溯
#### 对接时间线
| 阶段 | 内容 | 预计时间 |
|------|------|---------|
| 自建 | 超管后台创建API账户 + 配置权限 | 本周 |
| 配置 | IP白名单 + 网络验证 | 账户创建后1天 |
| 验证 | Postman接口测试 | 配置完成后1天 |
| 开发 | 后端集成模块开发 | ~2周 |
| 联调 | 前后端联调 + 测试 | ~1周 |
---
## 十、联系信息
- **申请人**：宋献，IT支持组（税友集团），负责终端安全
- **火绒/联软对接人**：宋献（超管权限，自行创建API账户，受安全团队管理）
- **项目**：智能IT支持服务台（IT Smart Desk）
- **紧急程度**：预生产反代配置建议 1-2 个工作日内完成；生产环境已部署运行
- **组织架构说明**：
- IT支持组 = 终端安全负责团队（非独立"终端安全团队"）
- 火绒企业版、联软LV7000 均以IT支持组名义申请/配置
- 跨团队资源申请（服务器/域名等）通过本文档统一跟踪
docs/01-项目总览/01-项目总览与部署手册-20260704.md
+731
View File
@@ -0,0 +1,731 @@
# 企微智能IT支持服务台 — 项目总览与部署手册
> **版本**: v2.2 | **日期**: 2026-07-04 | **编制**: 宋献（IT支持组组长）
> **目标读者**: **管理者 / 架构师 / 运维** — 了解项目全貌、架构决策、部署与运维操作
> **📖 与 README.md 的关系**: 本文是 [README.md](../README.md) 的**详细版本**，侧重完整的架构设计和部署运维。README 适合新人快速入门，本文适合深入了解。
> **⚠️ 运维手册更新**: 部署与运维操作已整合到独立文档 [智能IT服务系统运维手册](./智能IT服务系统运维手册.md)，该文档由助理（小米）维护，随每次发布更新。本文档保留架构设计与背景信息。
---
## 目录
1. [项目概述](#一项目概述)
2. [系统架构](#二系统架构)
3. [三步演进路径](#三三步演进路径)
4. [现有系统复用评估](#四现有系统复用评估)
5. [正式环境部署方案](#五正式环境部署方案)
6. [部署操作手册](#六部署操作手册)
7. [运维管理](#七运维管理)
8. [开发交付状态](#八开发交付状态)
9. [附录](#九附录)
---
## 一、项目概述
### 1.1 背景与痛点
公司约 **6000 人**，全国设分子机构，使用企业微信作为内部 IM。当前 IT 服务存在三大痛点：
| 痛点 | 现状 | 影响 |
|------|------|------|
| 员工绕过 AI 直接找人工 | 可通过关键词直通人工坐席，首次后永久记忆 | AI 筛选率极低，人工成本高 |
| AI 转人工需另开窗口 | 跳转到企微"员工服务"模块，与 AI 对话割裂 | 体验差，员工困惑 |
| 无法跨主体共享 | 企微"员工服务"不支持互联企业应用共享 | 跨企业服务不可达 |
### 1.2 核心方案
**自研 IT 服务坐席系统**，替代企微内置的"员工服务"模块：
- 基于企微自建应用消息 API，所有消息由自己的服务器接管
- 分三步渐进式构建：M1 消息接管 → M2 AI 接入 → M3 知识库闭环
- 当前处于 **M1（消息接管 + 极简坐席）开发完成，部署配置中**
### 1.3 核心设计理念
传统"串行排队"改为**"并行协作"**——AI 全程在线，人工随时介入：
| 角色 | 工作方式 |
|------|---------|
| AI | 全程在线，所有对话可见 |
| 坐席 | 随时介入，AI 始终在旁辅助 |
| 员工 | 同一窗口，AI 和人工无缝切换 |
---
## 二、系统架构
### 2.1 部署架构总览（预生产环境）
> **当前阶段**：预生产环境。智能咨询系统与 IT 数据查询平台**分别部署在不同主机**，通过 Nginx 路径路由共用域名 `it-dataquery.dc.servyou-it.com`。正式环境将迁移到 K8s 集群。
```
浏览器 ──→ it-dataquery.dc.servyou-it.com:80
│
▼
┌─── nginx (本系统主机) ───────────────┐
│ │
│ /itdesk/* → H5 员工端 SPA │
│ /itagent/* → 坐席工作台 SPA │
│ /api/* → backend:8000 (FastAPI) │
│ /ws/* → backend:8000 (WS) │
│ /* → 数据平台主机（远程IP） │ ← 跨主机代理
│ │
└──────────────┬───────────────────────┘
│ 本机 Docker 网络
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ backend │ │ postgres │ │ redis │
│ :8000 │ │ :5432 │ │ :6379 │
└──────────┘ └──────────┘ └──────────┘
```
| 对比项 | 预生产（当前） | 正式环境（未来） |
|--------|-------------|---------------|
| 部署方式 | Docker Compose（单主机） | K8s 集群（高可用） |
| 与数据平台关系 | 不同主机，Nginx 远程代理 | 独立 K8s 集群 |
| 域名 | 共用 `it-dataquery.dc.servyou-it.com` | 独立域名或 K8s Ingress |
### 2.2 技术栈
| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 反向代理 | Nginx | 统一入口、路径路由、WebSocket 代理 |
| 后端框架 | FastAPI (Python 3.12) | 异步、自动 OpenAPI 文档、类型安全 |
| 数据库 | PostgreSQL 16 | 会话/消息/坐席/配置 持久化（9 张表） |
| 缓存 | Redis 7 | access_token 缓存（TTL 7200s）、JWT 会话 |
| ORM | SQLAlchemy 2.0 (async) | 异步 session、声明式模型 |
| 数据库迁移 | Alembic | 所有表结构变更通过迁移脚本管理 |
| 坐席前端 | Vue3 + ElementPlus + Pinia | 企业级组件库，三栏工作台 |
| 员工 H5 | Vue3 + Vant4 + Pinia | 移动端组件库，企微 WebView 兼容 |
| 容器化 | Docker + Docker Compose | 4 容器一键启停 |
### 2.3 数据库核心表（9 张）
| 表名 | 用途 | 关键字段 |
|------|------|---------|
| `conversations` | 会话主表 | employee_id, status, urgency_score(1-5), tags(JSON), is_vip, participants(JSON) |
| `messages` | 消息记录 | sender_type(employee/agent/ai/system), content, msg_type |
| `agents` | 坐席信息 | user_id, status(online/offline/busy), current_load |
| `quick_reply_templates` | 快速回复模板 | category, title, content(支持 {变量}) |
| `system_configs` | 系统配置 | config_key, config_value（关键词/阈值/话术等） |
| `funny_phrases` | 趣味话术 | scene(6 种场景), content, tone, is_active |
| `approval_links` | 审批流程链接 | category(IT/HR/行政/财务), title, url |
| `software_downloads` | 软件下载入口 | category, name, version, platform, download_url |
| `agent_notes` | 坐席备注 | conversation_id, agent_id, content |
### 2.4 API 接口分组
| 分组 | 路径前缀 | 核心接口 |
|------|---------|---------|
| 企微回调 | `/api/wecom/callback` | GET 验证 URL、POST 接收消息 |
| 会话管理 | `/api/conversations` | 列表/详情/状态/置顶/代办/接单/邀请/退出/移除参与者 |
| 消息管理 | `/api/conversations/{id}/messages` | 消息列表/发送 |
| 坐席管理 | `/api/agents` | 列表/登录/状态切换 |
| H5 用户端 | `/api/h5/*` | 会话/摇人/审批链接/软件下载/OAuth |
| WebSocket | `/ws/{agent_id}` | 实时推送（坐席端） |
统一响应格式：`{ "code": 0, "data": {}, "message": "success" }`
### 2.5 消息收发全链路
```
员工发消息 → 企微回调解密 → 消息路由 → 评分标记 → 入库 → 坐席 WS 推送 → 坐席回复 → 企微主动推送 → 员工同一窗口收到
```
**坐席端通信**：已升级为 WebSocket 实时推送（2026-06-03），替代原计划的短轮询：
- 心跳保活：前端每 30s 发 ping，后端回 pong
- 断线重连：指数退避（1s→2s→4s→...→30s 上限）
- 降级策略：WS 断连时自动降级为 3s 轮询
### 2.6 会话排序与评分规则
**排序**: 紧急 → 举手 → 需介入 → 活跃 → AI处理中 → 已结单（同级按时间倒序）
**紧急度评分**: `基础分(关键词) + 情绪加成 + VIP加成 + 重复追问加成`，范围 1-5
**标记系统**:
| 标记 | 图标 | 触发条件 |
|------|------|---------|
| VIP | 红色 | 企微通讯录规则匹配 |
| 举手 | 黄色 | 员工说关键词或点击摇人按钮 |
| 需介入 | 橙红 | 同一问题追问 >3 轮 |
| 情绪 | 红色 | 关键词匹配（急/崩溃/投诉等） |
---
## 三、三步演进路径
| 里程碑 | 周期 | 核心交付 | 状态 |
|--------|------|---------|------|
| **M1** 消息接管 + 极简坐席 | 6-8 周 | 企微 API 链路验证 · 坐席三栏工作台 · 员工 H5 双栏 · 邀请功能（多人会话协作） | ✅ 代码完成，部署中 |
| **M2** AI 机器人接入 | M1 后 4-6 周 | 千问/Dify/RAGFlow 接入 · AI 前置筛选 · 排队系统 | 📋 计划中 |
| **M3** 知识库闭环迭代 | M2 后 4-6 周 | 坐席标注系统 · 千问自动分析 · 知识库自优化 | 📋 计划中 |
### M1 当前进度（2026-06-03）
| 模块 | 状态 |
|------|------|
| PRD + 架构设计 | ✅ 完成 |
| 后端代码（45+ 文件，7 API 组） | ✅ 完成 |
| 坐席前端（三栏工作台 + WebSocket） | ✅ 完成 |
| 员工 H5（双栏 + 摇人按钮 + 呼叫坐席） | ✅ 完成 |
| 邀请功能（多人会话协作 — PRD §21） | 📋 计划中（M1 范围） |
| 前端功能联调验证 | ✅ 完成（2026-06-03） |
| 测试用例（116 条 pytest） | ✅ 完成 |
| Alembic 数据库迁移 | ✅ 完成 |
| 前端构建产物（dist/） | ✅ 完成 |
| 远程服务器部署 | 🔧 待 SSH 账号 |
### M2 核心改动
只改路由层逻辑，其余不动：
```
M1: 新会话 → 坐席队列
M2: 新会话 → AI 先回答 → AI判断/用户触发 → 坐席队列
```
新增：千问对话模型、RAGFlow 知识库检索、Dify 编排平台、排队系统。目标：AI 首答率 ≥ 80%。
### M3 知识库迭代闭环
```
坐席日常标注 ──→ 千问分析 ──→ 自动处理 ──→ 知识库增强
(正确/错误) (缺文档/过时) │
↑ │
└──────────── 持续循环 ─────────────────────┘
```
---
## 四、现有系统复用评估
### 4.1 核心复用（直接影响新系统架构）
| # | 资源 | 复用方式 | 新系统对应 |
|---|------|---------|-----------|
| 1 | Dify Workflow | 直接复用，M2 阶段接入 AI 回复 | 坐席助手 AI 面板 + 自动回复 |
| 2 | dify2openai 桥接 | 直接复用 API | 后端调用 AI 的入口 |
| 3 | RAGFlow 知识库 | 直接复用，M3 阶段混合标注迭代 | 知识库管理 + 标注闭环 |
| 4 | Qwen3-30B 大模型 | 直接复用 | AI 对话底层模型 |
| 5 | bge-m3 向量模型 | RAGFlow 内置，直接复用 | 知识库检索向量化 |
| 6 | Dify 数据库（只读） | 读取 messages 表，同步历史数据 | 历史会话数据迁移 + 统计 |
| 7 | 企微自建应用 | 直接复用应用凭证 | 消息收发的企微入口 |
### 4.2 基础设施复用（零耦合）
| 资源 | 复用方式 | 耦合度 |
|------|---------|--------|
| 企微自建应用凭证 | 配置文件引用（只读） | 零耦合 |
| Dify Workflow API | HTTP 调用 | 外部依赖 |
| RAGFlow 知识库 | HTTP 调用 | 外部依赖 |
| Qwen3-30B 大模型 | HTTP 调用 | 外部依赖 |
| SSL 证书文件 | Nginx 挂载只读 | 零耦合 |
### 4.3 关键结论
> 代码层面复用率约 15%（主要是业务逻辑和 SQL 查询），基础设施和 AI 能力复用率约 70%。
> 新系统用 **FastAPI + SQLAlchemy 2.0**，不沿用旧 Django 代码。底层业务逻辑可参考移植。
---
## 五、正式环境部署方案
### 5.1 核心决策原则
基于四个约束条件：
| # | 约束 | 推导原则 |
|---|------|---------|
| 1 | 对现有正式环境架构影响最小 | **物理隔离 > 逻辑隔离** |
| 2 | 避免变更影响现有服务 | **独立 Nginx 入口** |
| 3 | 减少服务依赖 | **最小化外部依赖** |
| 4 | 避免责任不清 | **独立数据库 + 独立 Redis** |
> **一句话**：新系统作为**独立服务单元**部署，与现有智能 IT 数据平台（Django）在物理资源层面完全解耦，仅通过 HTTP API 调用共享 AI 能力。
### 5.2 关键隔离策略
| 隔离层面 | 方案 | 效果 |
|---------|------|------|
| 服务器级 | 独立 VM，不共用宿主机 | 挂了不影响旧系统 |
| 网络级 | Docker 内部网络，PG/Redis 不暴露宿主机端口 | 外部无法直连数据库 |
| 存储级 | 独立命名卷，不共用 Volume | 数据完全隔离 |
| 域名级 | 路径路由（共用域名） + 独立 Nginx 容器 | `/itdesk/`、`/itagent/`、`/api/` 归属本系统 |
| 认证级 | JWT + 独立 Redis | 账户体系独立 |
| 依赖级 | 仅 HTTP 调用外部 AI 服务 | 外部服务故障只影响 M2 功能 |
### 5.3 与现有系统的解耦修正
原复用评估中的部分共享方案已修正为独立部署：
| 原建议 | 修正方案 | 理由 |
|--------|---------|------|
| 同机部署于 10.80.0.86 | 独立服务器/VM（或同机端口分离+独立 compose） | 避免端口冲突、资源争抢 |
| Redis 复用同实例 | 独立 Redis 容器 | FLUSHDB 误操作、内存 OOM 互相影响 |
| 使用旧系统 Nginx | 独立 Nginx 容器 | 变更反代配置不影响旧系统路由 |
| 复用旧 PG 实例 | 独立 PostgreSQL 容器 | 数据库是责任边界核心 |
### 5.4 Docker Compose 服务清单
| 服务 | 镜像 | 端口 | 健康检查 |
|------|------|------|---------|
| postgres | postgres:16 | 5432（内部） | pg_isready |
| redis | redis:7 | 6379（内部） | redis-cli ping |
| backend | 自构建 Dockerfile | 8000（内部） | GET /health |
| nginx | nginx:alpine | 18080:80（对外） | GET /health |
Docker 网络：`it-desk-internal`（内部，连接 backend/postgres/redis）
### 5.5 资源需求
| 资源 | 配置 | 说明 |
|------|------|------|
| 服务器 | 4C8G + 100GB SSD（最低）/ 8C16G + 200GB SSD（推荐） | Docker Engine 环境 |
| 域名 | `it-dataquery.dc.servyou-it.com`（已就绪，共用） | 路径路由 `/itdesk/` `/itagent/` `/api/` |
| 企微自建应用 | 1 个（已创建） | CorpID/AgentID/Secret/Token/EncodingAESKey |
| 防火墙 | 办公网→服务器:80/443, 企微→服务器:443 | 出站: 企微 API/ Dify/ RAGFlow/ Qwen |
### 5.6 风险矩阵
| 风险 | 概率 | 影响 | 缓解措施 |
|------|------|------|---------|
| 新服务器申请被拒/延迟 | 中 | 部署延期 | 退化方案：旧服务器端口分离+独立 compose |
| SSL 证书到期 | 低 | HTTPS 不可用 | 复用现有通配符证书 |
| 企微应用配置变更 | 低 | 双系统消息中断 | 建立变更通知机制 |
| Dify/RAGFlow 不可用 | 中 | M2 AI 功能不可用 | 降级：纯坐席模式仍正常工作 |
| Docker 宿主机故障 | 低 | 新系统全宕 | Compose 配置即代码，重建快 |
---
## 六、部署操作手册
> **预生产部署**：本系统与数据平台部署在**不同主机**，通过 Nginx 路径路由共用域名。数据平台请求通过远程 IP 反代（非 Docker 网络）。正式环境将迁移到 K8s。
### 6.1 前置条件
- 服务器已安装 Docker Engine 24+ + Docker Compose v2
- IT 数据查询平台已部署运行
- 有 SSH 登录权限
### 6.2 配置数据平台反代地址
预生产环境中，数据平台部署在**独立主机**。部署前需修改 `nginx/nginx.conf` 中的数据平台上游地址：
```nginx
# nginx/nginx.conf — 将 DATAQUERY_HOST 替换为数据平台主机的实际 IP
upstream dataquery {
server 10.80.0.86:80; # ← 替换为数据平台实际 IP:端口
}
```
> **为什么不创建 Docker 共享网络？** 预生产两台主机不在同一 Docker Engine，无法使用 `docker network create` 互联。正式环境迁移 K8s 后由 Ingress/Service 处理路由。
### 6.3 上传部署包
在本地（Windows）执行打包上传：
```bash
# 方式 A：使用 deploy.sh 打包
bash scripts/deploy.sh --pack
scp it-smart-desk-*.tar.gz user@server:/opt/
# 方式 B：手动打包
tar czf deploy.tar.gz \
backend/ frontend-h5/dist/ frontend-agent/dist/ \
nginx/ docker-compose.yml .env.production scripts/
scp deploy.tar.gz user@server:/opt/it-smart-desk/
```
### 6.4 服务器配置与启动
```bash
ssh user@server
cd /opt/it-smart-desk
tar xzf it-smart-desk-*.tar.gz
# 创建环境配置
cp .env.production .env
vim .env # 填入真实企微凭证
```
`.env` 必填项：
| 配置项 | 说明 | 获取位置 |
|--------|------|---------|
| `WECOM_CORP_ID` | 企业 ID | 企微管理后台 > 我的企业 |
| `WECOM_AGENT_ID` | 应用 AgentId | 企微管理后台 > 应用管理 |
| `WECOM_SECRET` | 应用 Secret | 企微管理后台 > 应用管理 |
| `WECOM_TOKEN` | 回调 Token | 企微管理后台 > 接收消息 |
| `WECOM_ENCODING_AES_KEY` | 回调 AES 密钥 | 企微管理后台 > 接收消息 |
| `POSTGRES_PASSWORD` | 数据库密码 | 自定义强密码 |
| `CORS_ORIGINS` | `http://it-dataquery.dc.servyou-it.com` | CORS 白名单 |
启动：
```bash
bash scripts/deploy.sh
# 自动执行：检查前置条件 → 构建后端镜像 → 启动所有容器 → 运行数据库迁移
```
### 6.5 验证部署
```bash
# 检查容器状态
docker compose ps
# 预期：4 个容器全部 Up/healthy
# 健康检查
curl http://localhost:18080/api/health
# 浏览器验证
# http://it-dataquery.dc.servyou-it.com/itdesk/ → H5 员工咨询页面
# http://it-dataquery.dc.servyou-it.com/itagent/ → 坐席工作台登录页
# http://it-dataquery.dc.servyou-it.com/ → IT 数据查询平台（不变）
# http://it-dataquery.dc.servyou-it.com/api/docs → FastAPI Swagger 文档
```
### 6.6 常见问题
**nginx 启动失败，报 `host not found in upstream "dataquery"`**
→ `nginx/nginx.conf` 中 `DATAQUERY_HOST` 未替换为数据平台的实际 IP。确保已在部署前完成替换。
**nginx 启动但数据平台页面 502**
→ 本系统主机无法访问数据平台主机 IP。检查防火墙策略是否放行两台主机间的 80 端口。
**访问 `/itdesk/` 返回 404**
→ 检查前端 dist 是否正确挂载：`docker exec wecom_it_nginx ls -la /usr/share/nginx/html/itdesk/`
**API 返回 CORS 错误**
→ 检查 `.env` 中 `CORS_ORIGINS` 是否包含 `http://it-dataquery.dc.servyou-it.com`
**数据库迁移失败**
→ PostgreSQL 可能未就绪，等 30 秒后执行：`docker compose restart backend`
### 6.7 更新部署
```bash
# 仅更新前端
bash scripts/deploy.sh --build
docker compose restart nginx
# 仅更新后端
docker compose build backend
docker compose up -d backend
# 全量更新
bash scripts/deploy.sh --down
bash scripts/deploy.sh
```
### 6.8 回滚
```bash
docker compose down # 停止新系统所有容器
# 旧系统不受任何影响（独立资源）
```
---
## 七、运维管理
### 7.1 责任矩阵
| 运维操作 | 影响范围 | 备注 |
|---------|---------|------|
| 重启 PostgreSQL | 仅新系统 | 独立实例 |
| 重启 Redis | 仅新系统 | 独立实例 |
| 修改 Nginx 配置 | 仅新系统路由 | 独立容器 |
| 更新后端/前端代码 | 仅新系统 | 独立容器 |
| 企微应用配置变更 | **双系统** | ⚠️ 唯一共享点，需通知双方 |
### 7.2 监控指标
```yaml
主机层面:
- CPU 使用率 < 80%
- 内存使用率 < 80%
- 磁盘使用率 < 70%
容器层面:
- docker compose ps 全部 "Up" 状态
- Nginx 健康检查: GET /health → 200
- Backend 健康检查: GET /health → 200
业务层面（后续接入）:
- 企微消息回调成功率 > 99%
- API 响应时间 P95 < 500ms
```
### 7.3 备份策略
| 备份对象 | 方法 | 频率 | 保留 |
|---------|------|------|------|
| PostgreSQL 数据 | `pg_dump` + 卷快照 | 每日凌晨 | 7 天 |
| Redis 数据 | `SAVE` + 复制 dump.rdb | 每日凌晨 | 7 天 |
| Docker 卷 | `tar czf` 归档 | 每周 | 4 周 |
### 7.4 关键对接参数（M2 阶段）
| 参数 | 值 | 用途 |
|------|-----|------|
| dify2openai API | `http://yw-dify.dc.servyou-it.com/dify2openai/v1/chat/completions` | AI 对话 |
| RAGFlow | `http://10.80.0.85:8080` | 知识库管理 |
| Qwen3-30B | `http://10.80.0.49:5000/api/llm/servyou/v1/chat/completions` | 大模型 |
| Dify DB（生产只读） | `10.80.128.40:5432` DB=dify User=difyro | 历史数据同步 |
| 数据平台 | `http://it-dataquery.dc.servyou-it.com` (10.80.0.86) | 部署服务器 |
### 7.5 应急预案可选技术项
> **评估日期**: 2026-06-03 | **来源**: 企微原生1对1方案（PRD §3.2 方式五）可行性评估
#### 7.5.1 备用方案概述
当 H5 WebView 方案（当前主方案）出现以下情况时，可切换至**企微原生1对1方案**作为降级/备用：
| 应急场景 | 当前方案症状 | 备用方案动作 |
|---------|------------|------------|
| H5 前端服务不可用 | Nginx 静态文件丢失/构建产物损坏 | 员工直接在企微与应用1对1聊天，走 `/message/send` 回复 |
| H5 页面性能问题 | WebView 加载慢/白屏/兼容性问题 | 放弃 H5 入口，改用企微原生聊天窗口交互 |
| OAuth2 鉴权异常 | 静默授权失败，H5 无法获取员工身份 | 原生方案无需 OAuth2，回调自带 UserID |
| 跨平台接入需求 | 需接入钉钉/飞书/浏览器用户 | **不适合切换**——原生方案无法跨平台，此时应修复 H5 |
| 外部专家协作 | 坐席需要拉入第三方专家协助 | 启用 `/appchat/create` 创建临时群聊 |
#### 7.5.2 备用方案技术架构
```
┌─────────────────────────────────────────────────────┐
│ 员工端（企微原生1对1聊天窗口） │
│ │
│ 员工 ←─消息─→ 自建应用（IT智能助手） │
│ │ │
│ ├─ AI回复 → /message/send → 同一窗口 │
│ ├─ 坐席回复 → /message/send → 同一窗口 │
│ └─ 外援 → /appchat/create → 新群聊窗口 │
│ │
│ 坐席工作台（保留，不变） │
│ ├─ WebSocket 接收员工消息 │
│ ├─ 坐席回复 → 后端 → /message/send → 员工窗口 │
│ └─ 外援指令 → 后端 → /appchat/create → 新群聊 │
│ │
└─────────────────────────────────────────────────────┘
```
**核心能力**：项目**已经具备**备用方案所需的全部后端代码：
- `wecom_callback.py`：接收企微回调 ✅
- `message_router._try_ai_reply()` → `wecom_service.send_text_message()`：AI回复走 `/message/send` ✅
- `scoring_service.detect_hand_raise()`：关键词举手检测 ✅
- `wecom_service.send_text_message()`：应用消息推送 ✅
**仅需新增**：
- 交互卡片消息发送（`msgtype="template_card"`）— 用于"转人工"按钮、满意度评分
- AppChat API 封装（`/cgi-bin/appchat/*`）— 用于外援群聊场景
- AI/人工身份区分前缀（如 `🤖 AI回复：` / `👨‍💻 人工坐席（张三）：`）
#### 7.5.3 切换流程
**从 H5 方案切换到原生1对1方案**：
| 步骤 | 操作 | 负责人 | 预计耗时 |
|------|------|--------|---------|
| 1 | 确认企微回调 URL 已配置且可达（H5 方案已配置则无需改动） | 运维 | 0 min |
| 2 | 确认 `message_router._try_ai_reply()` 走 `/message/send`（已实现） | 开发 | 0 min |
| 3 | 通知员工：直接在企微与应用聊天即可，不再进入 H5 | 运维 | 5 min |
| 4 | （可选）关闭 H5 入口：Nginx 配置注释 `/itdesk/` 路由 | 运维 | 2 min |
| 5 | （可选）启用交互卡片：部署 template_card 消息发送代码 | 开发 | 1-2 天 |
> **关键点**：步骤1-3 **零代码改动**即可完成基本切换，因为核心回调+消息推送链路已在运行。
**从原生1对1方案切回 H5 方案**：
| 步骤 | 操作 | 负责人 |
|------|------|--------|
| 1 | 恢复 Nginx `/itdesk/` 路由（如已注释） | 运维 |
| 2 | 确认 H5 构建产物存在且可访问 | 运维 |
| 3 | 通知员工：点击应用 → 进入 H5 咨询页面 | 运维 |
#### 7.5.4 企微 API 限制与容量评估
| API | 限制 | 当前业务量（月均 188 次 AI 会话/天） | 风险 |
|-----|------|--------------------------------|------|
| `/message/send` | ≤账号上限×200人次/天，同一人≤30次/分 | 预估 < 500 人次/天 | ✅ 充裕 |
| `/appchat/create` | ≤1000群/天 | 外援场景低频（预估 < 10群/天） | ✅ 充裕 |
| `/appchat/send` | ≤2万人次/分，同一人≤200条/分 | 群内消息量极小 | ✅ 充裕 |
| 回调消息 | 无硬限制 | 企微服务器推送到回调 URL | ✅ 无风险 |
#### 7.5.5 备用方案局限性与适用边界
| 局限 | 说明 | 影响 |
|------|------|------|
| **无法跨主体企微** | 企微原生1对1仅限同一企微主体内员工 | 无法服务供应商/外包人员 |
| **无法跨平台** | 原生方案绑定企微，无法嵌入钉钉/飞书/浏览器 | H5 扩展场景不可用 |
| **AI/人工区分不直观** | 都以应用身份推送，需内容前缀区分 | 体验不如 H5 的丰富身份标识 |
| **交互卡片需开发** | "转人工"按钮、满意度评分需 template_card 消息类型 | 降级期可用关键词替代（"转人工"） |
| **群聊外援需审批** | appchat API 要求可见范围=根部门 | 需企微管理员配合 |
> **决策建议**：当 H5 不可用且影响范围仅限企微主体内员工时，**立即切换**原生1对1方案（零代码改动）；当需要跨平台/跨主体服务时，**优先修复 H5**，不切换原生方案。
---
---
## 八、开发交付状态
### TL;DR
企微智能IT支持服务台第一步（消息接管 + 极简坐席台）全部代码已完成并通过测试，共 **110+ 文件**，**116/116 测试全部通过**，覆盖后端 API、坐席工作台、用户端 H5 三个子系统。
### 交付状态
| 阶段 | 状态 | 产出 |
|------|------|------|
| PRD | ✅ 完成 | `PRD.md` — 31 需求（P0/P1/P2），7 用户故事 |
| 架构设计 | ✅ 完成 | `docs/ARCHITECTURE.md` — 9 表 DDL，7 API 组，4 时序图，5 任务分解 |
| T01 项目脚手架 | ✅ 完成 | 57 文件 — docker-compose, nginx, .env, 后端/前端骨架 |
| T02 后端核心服务 | ✅ 完成 | 16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由 |
| T03 坐席工作台 | ✅ 完成 | 25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab) |
| T04 用户端H5 | ✅ 完成 | 12 文件 — 聊天面板, 摇人按钮, AI助手, 审批链接, 软件下载 |
| QA 测试用例 | ✅ 完成 | 8 文件, 116 测试用例（原 93 + 新增 23） |
| Bug 修复 | ✅ 完成 | 7 个 Bug 修复（详见下方） |
| PostgreSQL/SQLite兼容 | ✅ 完成 | 9 个模型文件全部兼容 SQLite |
| database.py 懒加载 | ✅ 完成 | 避免测试导入时连接 PostgreSQL |
| WecomCrypto 懒加载 | ✅ 完成 | 避免默认 AES Key 导入报错 |
| **pytest 全量验证** | **✅ 116/116 通过** | 1.71 秒完成，0 失败 |
### 关键文件
```
wecom_it_smart_desk/
├── README.md # 项目主文档（GitHub 首页）
├── docker-compose.yml # Docker Compose 容器编排
├── .env # 环境变量（数据库密码等，不提交 Git）
├── backend/ # FastAPI 后端服务
│ ├── app/
│ │ ├── main.py # FastAPI 应用入口
│ │ ├── config.py # 配置管理（从 .env 读取）
│ │ ├── database.py # 懒加载数据库引擎
│ │ ├── models/ # 11 个 ORM 模型（兼容 PostgreSQL/SQLite）
│ │ ├── schemas/ # Pydantic Schema（请求/响应校验）
│ │ ├── utils/
│ │ │ └── wecom_crypto.py # 企微消息加解密（AES-CBC-256）
│ │ ├── services/
│ │ │ ├── wecom_service.py # 企微回调处理
│ │ │ ├── message_router.py # 消息路由 + 评分 + 举手检测
│ │ │ ├── scoring_service.py # 紧急度评分引擎
│ │ │ ├── session_service.py # 会话生命周期管理
│ │ │ └── funny_phrase_service.py # 摇人趣味话术生成
│ │ └── api/ # 8 个 API 路由模块
│ └── tests/ # 116+ 个测试用例
├── frontend-agent/ # 坐席工作台（Vue 3 + Element Plus）
│ └── src/
│ ├── views/ # LoginView + WorkspaceView
│ ├── components/
│ │ ├── TopBar/ # 顶部栏（主题切换 + 用户信息）
│ │ ├── conversation/ # 会话列表 + 会话条目
│ │ ├── chat/ # 聊天区 + 消息气泡 + 输入框
│ │ ├── assistant/ # AI 推荐内联组件
│ │ ├── troubleshooting/ # 排查步骤栏（FlowchartNode）
│ │ ├── quickreply/ # 快速回复面板（三层导航）
│ │ └── todo/ # 待办面板 + 任务详情视图
│ ├── stores/ # Pinia Store（conversation/agent/quickReply/theme/todo）
│ └── api/ # API 调用模块
├── frontend-h5/ # 员工端 H5（Vue 3 + Vant）
│ └── src/
│ ├── views/ # ChatView
│ └── components/ # ChatPanel + 摇人按钮 + AI助手
├── nginx/ # Nginx 反向代理配置
│ └── nginx.conf
├── scripts/ # 部署和运维脚本
│ ├── start_backend.bat # Windows 快速启动后端（相对路径）
│ └── restart_backend.ps1 # Windows 重启后端（自动查找 PG/Redis/Python）
└── docs/ # 项目文档（全部文档统一存放）
├── PRD.md # 产品需求文档 v1.0
├── PRD-v53-incremental.md # v5.3 增量需求
├── ARCHITECTURE.md # 系统架构设计（合并版）
├── 01-项目总览与部署手册.md # 管理者视角部署手册
├── 开发交付概览.md # 开发交付状态总览
├── 智能IT支持服务台-项目迁移文档.md # 工作区迁移记录
├── testing/ # 测试报告目录
│ └── QA_COMPREHENSIVE_REPORT.md # 综合 QA 报告
├── diagrams/ # Mermaid 图表
│ ├── sequence-diagram.mermaid
│ ├── sequence-shake.mermaid
│ ├── sequence-scoring.mermaid
│ ├── sequence-polling.mermaid
│ └── class-diagram.mermaid
└── prototypes/ # 原型文件
├── agent-workspace-v5_3.html # 当前锁定版本（v5.3）
├── qr_data_full.json # 快速回复数据（180条）
└── archive/ # 历史原型归档
```
### Bug 修复清单（7 个）
| # | 文件 | 问题 | 修复 |
|---|------|------|------|
| 1 | `message_router.py` | `calculate_urgency()` 是 async 但未 `await` | 添加 `await` |
| 2 | `app/main.py` | 中文引号 `""` 嵌入 Python 双引号字符串，SyntaxError | 转义引号 |
| 3 | `wecom_callback.py` | `WecomCrypto` 模块级初始化，默认 AES Key 不合法导致 `binascii.Error` | 改为懒加载单例 `_get_wecom_crypto()` |
| 4 | `tests/conftest.py` | `aioredis.from_url` mock 路径错误 | 修正为 `redis.asyncio.from_url` |
| 5 | `tests/conftest.py` | `create_test_conversation()` 缺少 `is_pinned`/`is_todo` 参数 | 添加可选参数 |
| 6 | `session_service.py` | `conversation_id` UUID 对象 vs String(36) 列类型不匹配 | 先转字符串再查询 |
| 7 | `scoring_service.py` | 关键词大小写不敏感缺失 + `_check_vip` 缺短路 | `.lower()` + 短路返回 |
### 用户下一步操作
1. **（已验证）pytest 全量通过**：116/116 测试已在开发环境验证通过，本地无需再跑
2. **配置企微应用凭证**：
- 复制 `.env.example` 为 `.env`
- 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey
3. **Docker Compose 启动**（需 PostgreSQL + Redis）：
```powershell
cd C:\Users\simon\wecom_it_smart_desk
docker-compose up -d
```
4. **前端开发启动**：
```powershell
# 坐席工作台
cd frontend-agent && npm install && npm run dev
# 用户端 H5
cd frontend-h5 && npm install && npm run dev
```
5. **企微回调配置**：在企微管理后台配置消息回调 URL 指向你的服务器
## 九、附录
### 8.1 需要团队协助的事项
| # | 事项 | 需要谁 | 紧急度 |
|---|------|--------|--------|
| 1 | **服务器 SSH 账号**：用于 Docker 部署 | 运维 | 🔴 高（当前阻塞） |
| 2 | **企微通讯录权限**：确认 API 权限（VIP 功能依赖） | 运维/企微管理员 | 中（M1 可用 mock） |
| 3 | **千问/Dify/RAGFlow 环境**（M2 阶段） | 架构/开发 | 低（M2 前准备） |
### 8.2 项目文件索引
```
wecom_it_smart_desk/
├── README.md # 入口索引
├── PRD.md # 产品需求文档
├── docs/
│ ├── 01-项目总览与部署手册.md # ← 本文档（运维/架构/管理者）
│ ├── 02-技术架构与开发指南.md # 开发者文档
│ └── 03-测试验证文档.md # 测试文档
├── backend/ # FastAPI 后端
├── frontend-agent/ # 坐席工作台前端
├── frontend-h5/ # 员工 H5 前端
├── nginx/nginx.conf # Nginx 反代配置
├── docker-compose.yml # Docker Compose 编排
├── .env.production # 生产环境变量模板
└── scripts/ # 部署/构建脚本
```
---
> 本文档合并自原 `docs/团队沟通文档-架构消息知识库.md`、`docs/正式环境独立部署架构方案.md`、`docs/DEPLOY_NAS.md`。详细技术规格见 `docs/02-技术架构与开发指南.md`。
docs/01-项目总览/01-项目知识库-20260704.md
+52
View File
@@ -0,0 +1,52 @@
# 企微智能 IT 支持服务台 — 项目全量知识库
> **项目代号**:`wecom_it_smart_desk`
> **状态**:v0.5.0-beta 内测(2026-06-15),v0.4.x 仍为生产稳定版
> **目标用户**:公司 6000 员工(企微 IM)
> **核心痛点**:员工绕过 AI 直接找人工 / AI 转人工需另开窗口 / 无法跨主体共享
> **核心方案**:自研 IT 服务坐席系统,基于企微自建应用消息 API
> **演进路径**:M1 消息接管 → M2 AI 接入 → M3 知识库闭环
> **本文档用途**:Claude 全面接管项目后的"项目大脑" — 完整功能/架构/集成/部署/安全/历史决策清单
> **最后更新**:2026-06-15(项目从 WB 移交到 Claude 接管)
---
## 0. 项目移交状态(2026-06-15)
| 项目 | 状态 |
|---|---|
| 项目控制方 | **Claude 全面接管**(原由 Workbuddy CN 推进,2026-06-15 起停用) |
| WB 项目目录 | `D:\资料\03-项目开发\wecom_it_smart_desk`(待用户授权后归档封存) |
| Claude 工作目录 | `D:\资料\03-项目开发\wecom_it_smart_desk-claude`(唯一 active 副本) |
| 代码托管 | Gitea(自托管 NAS 8418 端口),推送前需重新获 token |
| 移交决策原因 | WB 1009 上下文冲突 + token 误吊销 + 大量功能信息丢失 |
| 关联 memory | `project-handover-to-claude` / `gitea-push-permission-revoked-2026-06-15` |
---
## 1. 业务背景
### 1.1 公司规模与用户
- 6000 员工,全国分子机构
- 内部 IM:企业微信(企微)
- 现有痛点:
- 员工绕过 AI 直接找人工,AI 筛选率极低
- AI 转人工需另开窗口,体验割裂
- 企微"员工服务"不支持跨企业应用共享
### 1.2 核心设计理念
- **并行协作**(非传统串行排队):AI 全程在线 + 人工随时介入 + 员工同一窗口无缝切换
- **统一入口**(v0.5):企微工作台 → 唯一 OAuth2 认证点 → 角色检测 → 路由到用户端/坐席端/管理端
- **AI Wingman**(v0.6+):AI 不仅是服务员工的,更是解放坐席的
### 1.3 三步演进路径
| 里程碑 | 周期 | 核心交付 | 状态 |
|---|---|---|---|
| **M1** 消息接管 + 极简坐席 | 6-8 周 | 企微 API 链路 · 三栏工作台 · H5 双栏 · 邀请功能 | ✅ 代码完成,部署中 |
| **M2** AI 机器人接入 | M1 后 4-6 周 | 千问/Dify/RAGFlow · AI 前置筛选 · 排队系统 | 📋 计划中 |
| **M3** 知识库闭环 | M2 后 4-6 周 | 坐席标注系统 · 千问自动分析 · 知识库自优化 | 📋 计划中 |
---
*注：完整内容已移至 docs/ 目录统一管理*
docs/01-项目总览/02-项目迁移文档-20260606.md
+258
View File
@@ -0,0 +1,258 @@
# 智能IT支持服务台 — 项目迁移文档
**生成时间**：2026-06-06
**来源项目**：`C:\Users\simon\wecom_it_smart_desk`
**原型文件**：`C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html`
---
## 一、项目概览
| 项目 | 路径 | 技术栈 |
|------|------|---------|
| 后端 | `C:\Users\simon\wecom_it_smart_desk\backend` | Python 3.12 + FastAPI + SQLAlchemy |
| 前端（坐席工作台） | `C:\Users\simon\wecom_it_smart_desk\frontend-agent` | Vue 3 + TypeScript + Vite + Element Plus + Pinia |
| 原型 HTML | `C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html` | 单文件，v5.3 定版 |
| 服务器 | `10.80.0.129` | Docker Compose (postgres + redis + backend + nginx) |
---
## 二、锁定的设计决策（迁移后必须遵守）
### 2.1 原型规范
- ✅ **原型 v5.3 已锁定**（`agent-workspace-v5_3.html`），调整样式前必须与用户确认
- ✅ 用户偏好**深色科技风 UI**，原型**必须使用中文**
- ✅ 所有修改基于现有面板内调整，**不另开新页面**
- ✅ 聊天区域应缩小，给侧栏更多空间
### 2.2 布局架构（三栏）
```
┌──────────┬────────────────────────┬──────────────┐
│ 左栏 │ 中栏 │ 右栏 │
│ (240px) │ (flex:1 自适应) │ (320px) │
│ │ │ │
│ 会话列表 │ UserInfoBar │ AI 智能推荐 │
│ 搜索框 │ TroubleshootBar │ 快速回复 │
│ 待办事项 │ 消息列表 │ (三层导航) │
│ │ ReplyBox (输入框) │ │
└──────────┴────────────────────────┴──────────────┘
```
### 2.3 关键交互规则
| 功能 | 规则 |
|------|------|
| 排查步骤栏 | 始终可见（不可收起），位于 UserInfoBar 下方、消息列表上方 |
| 全流程图 | 默认收起，通过 `▶` / `▼` 三角图标切换 |
| 用户信息栏展开箭头 | 收起 `▶`（向右）→ 展开 `▼`（向下，CSS `rotate(90deg)`） |
| AI 推荐 | **仅在右边栏**，不在中间栏内联显示 |
| 快速回复 | 三层渐进导航：L1(7列grid) → L2(chip流式) → L3(列表) |
| 主题切换 | 浅色(`:root`) / 深色(`[data-theme="dark"]`) 双主题 |
| 输入框 | `resize: vertical` 手动拖拽 + `autosize` 最大 8 行 + `max-height: 200px` |
---
## 三、原型 v5.3 布局细节（已确认的终版）
> **文件**：`C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html`
### 3.1 中间栏（center-column）DOM 顺序
```html
<div class="center-column">
<div class="chat-view"> <!-- 整个聊天视图容器 -->
<div class="user-info-bar"> <!-- 用户信息栏（含6卡片展开详情） -->
<div class="user-detail-panel"> <!-- 展开详情（默认收起） -->
<div class="troubleshoot-bar" id="tsBar"> <!-- 排查步骤（紧跟用户信息栏） -->
<div class="ts-header"> <!-- 标题行：[🔧 排查步骤] [①→②→③→④→⑤] [▶] -->
<div class="chat-messages"> <!-- 消息列表 -->
<div class="chat-input-area"> <!-- 输入框区域 -->
<textarea autosize maxRows=8 resize=vertical>
</div> <!-- chat-view 闭合标签 -->
<div class="sidebar-right"> <!-- 右边栏（AI推荐 + 快速回复） -->
</div>
```
### 3.2 排查步骤栏（ts-header 单行布局）
```html
<div class="ts-header">
<span class="ts-title">🔧 排查步骤</span>
<el-select>...</el-select> <!-- 模板选择下拉 -->
<div class="ts-path-inline"> <!-- 内联路径步骤 -->
<span class="path-step-inline done">① 确认版本</span>
<span class="path-arrow-inline">→</span>
...
</div>
<span class="ts-flowchart-toggle">▶</span> <!-- 三角切换图标 -->
</div>
```
### 3.3 用户信息栏展开箭头
```css
.user-info-bar.expanded .expand-icon {
transform: rotate(90deg); /* ▶ 旋转后变成 ▼ */
}
```
```html
<span class="expand-icon">▶</span> <!-- 收起时向右，展开时向下 -->
```
---
## 四、Vue 3 项目 — 已修改文件清单
### 4.1 核心视图
| 文件 | 修改内容 |
|------|---------|
| `src/views/Workspace.vue` | `onMounted` 添加 `fetchConversations()` + 自动选第一个会话；`assistantVisible` 默认 `true` |
| `src/components/chat/ChatArea.vue` | 移除 `AiRecommendInline`；`TroubleshootBar` 位置调整到 `UserInfoBar` 下方；移除重复的第一个 `TroubleshootBar` |
### 4.2 聊天组件
| 文件 | 修改内容 |
|------|---------|
| `src/components/chat/UserInfoBar.vue` | 展开箭头 `▶` → `▼`（rotate 90deg），之前方向反了 |
| `src/components/chat/TroubleshootBar.vue` | 路径步骤合并到标题行；展开按钮简化为三角 `▶`/`▼` |
| `src/components/chat/ReplyBox.vue` | `autosize` 上限 4→8 行；`resize: none` → `resize: vertical`；支持手动拖拽 |
| `src/components/chat/AiRecommendInline.vue` | 已从 `ChatArea.vue` 移除引用（AI推荐仅保留右边栏） |
### 4.3 右边栏组件
| 文件 | 修改内容 |
|------|---------|
| `src/components/assistant/AiAssistantPanel.vue` | 右边栏主容器（AI推荐 + 快速回复） |
| `src/components/assistant/QuickReplyPanel.vue` | 三层渐进导航，L1 七类，数据源 `src/data/qrData.ts` |
| `src/components/assistant/RiskAlert.vue` | 风险告警组件 |
| `src/components/assistant/OperationSteps.vue` | 操作步骤组件 |
### 4.4 状态管理（Stores）
| 文件 | 修改内容 |
|------|---------|
| `src/stores/conversation.ts` | `fetchConversations()` DEV 环境 Mock 兜底；自动选中第一个会话 |
| `src/stores/agent.ts` | `initAuth()` 检查 localStorage token |
| `src/stores/todo.ts` | 待办事项 Mock 数据 |
| `src/composables/useWebSocket.ts` | WebSocket 直连后端 `ws://localhost:8000/ws/{agentId}` |
### 4.5 样式
| 文件 | 修改内容 |
|------|---------|
| `src/styles/global.css` | `.reply-box .el-textarea__inner { max-height: 200px; }`；`.message-list-scroll { flex: 1; overflow-y: auto; }` |
### 4.6 数据
| 文件 | 说明 |
|------|------|
| `src/data/qrData.ts` | 快速回复 180 条（7大类 × 28子类），TypeScript 类型化 |
---
## 五、后端关键修改（参考）
> 路径：`C:\Users\simon\wecom_it_smart_desk\backend`
| 文件 | 修改内容 |
|------|---------|
| `app/services/session_service.py` | `get_conversations()` 排序改为 Python 侧（SQLite 不支持 JSONB 操作符） |
| `app/main.py` | 添加 `dify_conversation_id` 列（PostgreSQL） |
| `app/models/todo_item.py` | TodoItem 模型 |
| `app/models/troubleshooting_template.py` | TroubleshootingTemplate 模型 |
---
## 六、已修复的关键 Bug（迁移后注意）
### Bug 1：会话列表不显示 / 页面空白
**根因**：`Workspace.vue` `onMounted` 未调用 `fetchConversations()`，`currentConversation` 始终为 `null`，`ChatArea` 不渲染。
**修复**：`onMounted` 中添加 `await conversationStore.fetchConversations()` + 自动选中第一个会话。
### Bug 2：AI 推荐同时出现在中间栏和右边栏
**根因**：`ChatArea.vue` 中引入了 `<AiRecommendInline />` 组件。
**修复**：移除 `ChatArea.vue` 中的 `AiRecommendInline` 模板、import、ref、`onAiRecommend` 快捷键绑定。
### Bug 3：原型 HTML 右边栏显示在中栏内部
**根因**：`<div class="chat-view">` 缺少 `</div>` 闭合标签，浏览器把 `sidebar-right` 解析为 `center-column` 的子元素。
**修复**：在 `chat-input-area` 关闭后补 `</div>` 闭合 `chat-view`。
### Bug 4：排查步骤栏出现两个（上下重复）
**根因**：`ChatArea.vue` 模板里有两个 `<TroubleshootBar />`（一个在 UserInfoBar 下方，一个在 ReplyBox 下方）。
**修复**：删除 ReplyBox 下方的重复 `<TroubleshootBar />`。
### Bug 5：用户信息栏展开箭头方向反了
**根因**：收起时 `▼`，展开时 `▲`（CSS `rotate(180deg)`）。
**修复**：收起 `▶`，展开 `▼`（CSS `rotate(90deg)`）。
### Bug 6：会话列表 API 500 错误
**根因**：`session_service.py` 用 SQL 侧 `case()` + `tags["hand_raise"].as_boolean()` 排序，SQLite 不支持 JSONB 操作符。
**修复**：排序改为 Python 侧 `_sort_key()` 函数实现。
---
## 七、服务器部署状态
| 项目 | 状态 |
|------|------|
| 服务器地址 | `10.80.0.129` |
| Docker Compose 容器 | `postgres`, `redis`, `backend`, `nginx` |
| nginx | 已修复 301 重定向和 API 双重前缀问题 |
| PostgreSQL | 已添加 `dify_conversation_id` 列 |
| Redis | `it-desk-redis` 容器中运行中 |
---
## 八、知识库
| 项目 | 状态 |
|------|------|
| 数据源 | `IT支持知识库2026-4-24.docx` |
| 快速回复条数 | 180 条（7大类 × 28子类） |
| 前端数据文件 | `frontend-agent/src/data/qrData.ts` |
| 原型数据文件 | `agent-workspace-v5_3.html` 内联（因 file:// CORS 限制） |
---
## 九、迁移 checklist
### 备份这些文件/目录：
```
# 原型
C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html
# 前端项目（整体复制）
C:\Users\simon\wecom_it_smart_desk\frontend-agent\
# 后端项目（整体复制）
C:\Users\simon\wecom_it_smart_desk\backend\
# 项目记忆（WorkBuddy）
C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\.workbuddy\memory\
```
### 新项目中需要重新配置：
- [ ] `.env` 文件（数据库连接、Redis、Dify API Key）
- [ ] `vite.config.ts` 中的 proxy 端口（当前 `5174`）
- [ ] Docker Compose 环境变量
- [ ] 服务器部署配置（`10.80.0.129`）
### 新项目中需要重新执行：
```bash
# 后端
cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
# 初始化数据库
alembic upgrade head # 或 python -m app.db.init_db
# 前端
cd frontend-agent
npm install
npm run dev # → http://localhost:5174/itagent/workspace
```
---
## 十、待完成任务（迁移后继续）
- [ ] 重启 dev server 验证所有修改已生效（当前修改已保存，需 Ctrl+C → npm run dev）
- [ ] 后端 AI 集成（Dify）代码修复（T02 任务）
- [ ] 前端方案评估（T03/T04）
- [ ] 企微回调服务器对接
- [ ] 生产环境部署验证
---
*此文档由 WorkBuddy 自动生成，汇总了 2026-05-21 至 2026-06-06 的所有工作内容。*
docs/01-项目总览/03-项目全面评估报告-20260625.md
+349
View File
@@ -0,0 +1,349 @@
# 企微IT智能服务台 — 项目全面评估报告
> **评估日期**: 2026-06-25
> **评估范围**: 全量代码库（后端 178 个 .py 文件 + 4 个前端 + 部署配置 + 文档体系）
> **项目周期**: 2025-12 至今（约 7 个月）
> **当前版本**: v0.7.1
> **目标用户**: 公司 6000+ 员工
---
## 一、评估总览
| 评估维度 | 评分 | 说明 |
|---------|------|------|
| 架构设计 | ⚠️ 7/10 | 层次清晰，但单体瓶颈已显现 |
| 代码质量 | ⚠️ 6.5/10 | 后端良好，前端可优化空间大 |
| 测试覆盖 | ⚠️ 5/10 | 后端有测试但 64 条失败，前端零测试 |
| 安全性 | ⚠️ 6.5/10 | 多次 P0 修复，但仍有遗留风险 |
| 文档完整性 | ✅ 9/10 | 50+ 份文档，远超同类项目 |
| 部署运维 | ⚠️ 5.5/10 | 手动部署，单点风险，无 CI/CD |
| 项目管理 | ⚠️ 6/10 | 任务跟踪良好但用户是唯一瓶颈 |
| **综合健康度** | **🟡 6.5/10 — 可用但有风险** |
---
## 二、架构评估
### 2.1 优势
1. **清晰的层次分离** — API 层 / Service 层 / Model 层职责分明，28 个 router 文件 + 20 个 service 文件组织合理
2. **合理的抽象设计** — `ExternalSystemAdapter` 抽象层统一外部系统集成接口，支持降级和缓存
3. **WebSocket 双模式** — 实时推送 + 轮询降级，含指数退避重连
4. **统一响应格式** — `{code, data, message}` 统一错误码体系
5. **4 前端独立工程** — 坐席/H5/管理后台/Portal 各司其职
### 2.2 关键问题
| # | 问题 | 严重度 | 影响 |
|---|------|--------|------|
| A1 | **单体后端无拆分** — 20 个 service 全部在一个 Python 进程 | 🟠 中 | 不可独立扩缩，故障影响面大；`message_router.py` 671 行，`session_service.py` 1234 行已经过大 |
| A2 | **无消息队列** — 所有业务同步处理，未引入 RabbitMQ/Kafka/Redis Stream | 🟠 中 | AI 回复耗时会阻塞请求链路；高并发下后端的请求处理能力受限于最慢的同步操作 |
| A3 | **WebSocket 单点** — 一个 ws_manager 进程管理所有连接 | 🔴 高 | 容器重启导致所有连接断开，生产环境已有坑记录；无跨进程 WS 广播方案 |
| A4 | **AI 层未集成** — Dify/RAGFlow 仅基础占位，路由已就绪但未启用 | 🔴 高 | README 自述"AI 自助解决率 70.2%"，但当前新会话直接进人工队列 — 核心能力缺失 |
| A5 | **单数据库实例** — 无读写分离，无连接池监控 | 🟢 低 | 6000 用户并发访问压力下，单 PG 实例是潜在瓶颈 |
### 2.3 改进建议
1. **引入消息队列**：用 Redis Stream（已有 Redis 基础设施）解耦 AI 回复、消息路由等耗时操作
2. **WebSocket 水平扩展**：改用 Redis Pub/Sub 实现跨进程 WS 广播（ws_manager 框架化）
3. **后端模块化**：将 AI 处理、消息路由、外部系统集成拆分为独立微服务或异步 Worker
4. **AI 集成优先**：Dify 凭证已在 docker-compose 中预留，应优先补齐 AI 自动回复能力
---
## 三、代码质量评估
### 3.1 后端
- **28 个 API 文件**, **20 个 service 文件**, **18 个模型文件** — 组织合理
- 文件注解完备（每个 API 文件注释齐全），参数命名规范
- 部分文件过大：`admin_service.py` (1,728 行), `session_service.py` (1,234 行), `message_router.py` (671 行)
### 3.2 前端（4 端）
- 坐席工作台 `Workspace.vue` 复杂度高（三栏动态切换，多个 v-if/v-else-if）
- 前端类型定义与后端存在字段映射问题（已知 `MessageResponse.id` vs `message_id` 的 CRITICAL 映射）
- 缺少前端单元测试和组件测试
- 部分组件缺少 loading/error/empty 三态处理
### 3.3 依赖管理
- `requirements.txt` 版本锁定清晰，含完整注释说明每个依赖的作用
- 已知历史问题：`pydantic==2.7.5` 被 PyPI yank，需锁定 `2.7.4`
- **无前端依赖 lock 文件** — `package-lock.json` 或 `yarn.lock` 未归档
- **无依赖安全审计** — dependabot 配置了 `.gitea/dependabot.yml` 但 Gitea 是否支持不确定
### 3.4 改进建议
1. **大文件拆分**：`admin_service.py` 按模块拆分，`session_service.py` 按生命周期阶段拆分
2. **前端测试**：核心组件（ChatArea/ConversationList）引入 Vitest + Vue Test Utils
3. **前端依赖锁**：`npm run build` 前验证 package-lock.json 存在
4. **类型对齐**：后端 OpenAPI → 前端 TypeScript 代码生成（使用 openapi-typescript 工具）
---
## 四、测试评估
### 4.1 现状
| 测试类型 | 数据 | 状态 |
|---------|------|------|
| 后端 pytest 文件 | 25 个测试文件 | ✅ 存在 |
| 总测试用例 | ~538 条 | ⚠️ |
| 通过 | 470 passed + 4 xfailed | ✅ |
| 失败 | **64 条 pre-existing 失败** | 🔴 |
| 前端测试 | **0** | 🔴 完全缺失 |
| E2E 测试 | 176 行检查清单 | ✅ 文档化但未自动化 |
| 集成测试 | 62 tests collected，Windows 环境卡 conftest | ⚠️ 已知问题 |
### 4.2 关键问题
| # | 问题 | 严重度 |
|---|------|--------|
| T1 | **64 条测试持续失败** — 被标记为 pre-existing，无人修复 | 🔴 高 |
| T2 | **conftest SQLite+StaticPool 在 Windows 卡死** — 本地无法跑全量测试 | 🔴 高 |
| T3 | **前端零测试** — 4 个前端项目没有任何单元/组件/E2E 测试 | 🔴 高 |
| T4 | **无 CI 门禁** — 没有"测试通过才能合入"的流水线 | 🟠 中 |
| T5 | **Mock 依赖强耦合** — conftest 的 patch 路径耦合代码结构 | 🟠 中 |
### 4.3 改进建议
1. **根治 64 条失败** — 每个 sprint 分配 10% 时间专门修复，按模块优先级推进
2. **conftest 重写** — 用 `PostgreSQL testcontainers` 替代 SQLite，彻底解决兼容性问题
3. **前端测试筑基** — 从最核心的消息列表和发送组件开始，逐步扩展到 30% 覆盖率
4. **Git Hooks** — `pre-commit-check.sh` 已存在，但应加入"新增 API 端点必加 Depends"的静态检查
---
## 五、安全评估
### 5.1 已完成的安全工作（值得肯定）
- ✅ 5 个 P0 鉴权漏洞已修复
- ✅ WS token 改走 `Sec-WebSocket-Protocol`
- ✅ 坐席密码 bcrypt 迁移
- ✅ nginx access_log 脱敏
- ✅ MFA/TOTP 二次验证（Google Authenticator 兼容）
- ✅ 高危操作守卫（HighRiskGuard）
- ✅ CSP/HSTS/X-Frame-Options 等安全头
- ✅ 异常信息脱敏
### 5.2 遗留风险
| # | 风险项 | 状态 | 严重度 | 存在时间 |
|---|--------|------|--------|----------|
| S1 | **nginx IP 白名单开 0.0.0.0/0** — 临时方案，攻击面大 | ⚠️ 待处理 | 🔴 高 | 11 天 |
| S2 | **Token 未绑定 IP/设备** — 任何获取 token 者可冒用 | ⚠️ 待处理 | 🟠 高 | 11 天 |
| S3 | **未实现全端速率限制** — 仅登录端点有限制 | ⚠️ 待处理 | 🟠 中 | 11 天 |
| S4 | **Upload 路径在容器本地** — 容器重建后文件丢失 | ⚠️ 待处理 | 🟠 高 | 11 天 |
| S5 | **Gitea 无异地备份** — 仅 NAS 本地 | ⚠️ 待处理 | 🟠 中 | 11 天 |
| S6 | **Nginx client_max_body_size 未按路径细分** | ⚠️ 待处理 | 🟢 低 | 11 天 |
| S7 | **前端硬编码配置** — 配置未通过运行时注入 | ⚠️ 待处理 | 🟢 低 | 11 天 |
### 5.3 改进建议
1. **立即收窄 IP 白名单**：联系网络组确认 WAF/堡垒机/CDN 出口 IP，替换 0.0.0.0/0
2. **Token 绑定增强**：Redis 中存储 token 时绑定用户 IP 段（可选 /24）或浏览器指纹
3. **全端速率限制**：用 slowapi 为所有 API 端点分级限流（登录 10/min，通用 60/min，管理 30/min）
4. **Upload 持久化**：加 docker volume mount 解决重建丢文件问题
5. **Gitea 异地备份**：备份到 NAS 另一存储池 + 定期下载到本地（或公司备份系统）
---
## 六、部署与运维评估
### 6.1 现状
| 维度 | 当前状态 | 目标状态 |
|------|---------|---------|
| 编排方式 | Docker Compose 单机 | K8s 集群（规划中） |
| 部署方式 | 手动打包 → 堡垒机上传 → 解压部署 | CI/CD 自动化 |
| HTTPS | 已配置（443 + 301 跳转） | — |
| 健康检查 | 已配置但有 curl 已知坑 | 稳定可靠 |
| 容器镜像管理 | 本地构建，无 registry | Harbor/阿里云镜像仓库 |
| 数据库备份 | 无自动化备份 | cron 定期备份 |
| 日志管理 | docker logs + json-file driver | 集中式日志（ELK/Loki） |
| 监控 | /health 端点 + dashboard.py | Prometheus + Grafana |
### 6.2 关键问题
| # | 问题 | 严重度 |
|---|------|--------|
| D1 | **手动部署高风险** — 依赖堡垒机手动上传，无回滚按钮 | 🔴 高 |
| D2 | **无容器镜像 Registry** — 每台机器本地构建镜像，版本不可追溯 | 🟠 中 |
| D3 | **单点故障** — 后端/PG/Redis 全部在同一 Docker 主机 | 🔴 高 |
| D4 | **无自动化备份策略** — 数据库无定期 dump，Redis 仅 AOF | 🔴 高 |
| D5 | **Docker Compose env 密码明文风险** — .env 文件存密码 | 🟠 中 |
| D6 | **部署包打包工具 package.py 曾缺少 Portal 和 Admin** — 2026-06-15 已修复 | ✅ 已修 |
### 6.3 改进建议
1. **短期：加固部署流程**
- `scripts/deploy.sh` 增加回滚模式（保留前 3 个版本的部署包）
- 部署前自动备份数据库（`docker compose exec postgres pg_dump`）
- 部署后自动触发健康检查 + 5 分钟观察期
2. **中期：镜像管理与 CI/CD**
- 搭建 Harbor（NAS 上即可）作为私有镜像仓库
- GitHub Actions 或 Gitea Actions 实现自动构建 + push
- 服务器 pull 新镜像实现零停机部署
3. **长期：高可用架构**
- PostgreSQL 主从 + PgPool-II
- Redis Sentinel 集群
- 后端多副本 + Nginx 负载均衡
- 多 Docker 主机（Swarm/K8s）
---
## 七、文档与项目管理评估
### 7.1 文档优势
- ✅ 50+ 份文档覆盖架构/PRD/部署/审计/风险/SOP/ADR
- ✅ README 有分角色阅读指南（新人/开发/运维/测试）
- ✅ 风险跟踪表 22 项（含处理计划和责任人）
- ✅ CHANGELOG 严格按 Keep a Changelog 格式
- ✅ CURRENT-FOCUS.md 作为驾驶舱仪表盘
- ✅ 知识库 KNOWLEDGE.md 23 章 1000+ 行
### 7.2 问题
| # | 问题 | 严重度 |
|---|------|--------|
| P1 | **工作记忆文件过大被截断** — `MEMORY.md` 超过 3000 字符限制 | 🔴 高 |
| P2 | **风险跟踪表 11 天未更新**（上次 2026-06-14） | 🟠 中 |
| P3 | **用户是唯一决策者** — 所有 P2 任务标的"等用户决策"，无自主推进机制 | 🟠 中 |
| P4 | **CURRENT-FOCUS.md 状态混乱** — 同时存在多个不同时间的 P2 等决策表 | 🟠 中 |
| P5 | **无 Sprint 回顾记录** — 无经验教训的结构化沉淀 | 🟢 低 |
### 7.3 改进建议
1. **立即整理 MEMORY.md**：合并重复项，删除过期记录，控制在 3000 字符内
2. **风险跟踪表定期更新**：每周一自动检查，标注处理进度
3. **设立"自动推进"机制**：对重复出现的 P2 项（如镜像仓库、HTTPS），设定 next-review-date 到期自动提醒
4. **文档审计周期**：每两周审查一次关键文档（风险跟踪表 + CURRENT-FOCUS.md）
---
## 八、风险汇总矩阵
| 级别 | 基础架构 | 安全 | 功能交付 | 运维 | 项目管理 |
|------|---------|------|---------|------|---------|
| 🔴 高 | WS 单点 / 单体后端瓶颈 | IP 白名单全开 / Token 无绑定 | AI 集成未完成 | 无备份 / 手动部署高风险 | MEMORY.md 截断 |
| 🟠 中 | 无消息队列 / 单 DB | 速率限制不全 / Upload 丢文件 | 外部系统集成不全(aTrust/eHR) | 无镜像 Registry / 单点故障 | 用户单一瓶颈 / 风险表过期 |
| 🟢 低 | 前端组件未拆分 | 前端硬编码 / Nginx 文件限制 | 满意度评价未开始 | .env 明文密码 | 无 Sprint 回顾 |
### 当前风险热力图
```
高危区（P0，须即刻处理）：
┌─────────────────────────────────────────────┐
│ ■ AI 集成未完成（核心功能缺失） │
│ ■ nginx IP 白名单 0.0.0.0/0（攻击面大） │
│ ■ MEMORY.md 截断（项目记忆丢失风险） │
│ ■ 无自动化数据库备份（数据丢失即永远丢失） │
└─────────────────────────────────────────────┘
中危区（P1，2 周内处理）：
┌─────────────────────────────────────────────┐
│ ■ 64 条测试失败（质量信号失真） │
│ ■ 前端零测试（回归风险不可控） │
│ ■ 上传文件容器重建丢失（数据不持久） │
│ ■ 单体后端超负荷（session_service 1234行） │
└─────────────────────────────────────────────┘
低危区（P2，纳入 Sprint）：
┌─────────────────────────────────────────────┐
│ ■ WebSocket 单点（断连重建体验差） │
│ ■ 无镜像 Registry（版本不可追溯） │
│ ■ 风险跟踪表过期（11 天未更新） │
│ ■ 用户单一决策瓶颈（P2 任务堆积） │
└─────────────────────────────────────────────┘
```
---
## 九、推进计划
### 9.1 Phase 1 — 立即止血（1-3 天）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P0 | **收窄 nginx IP 白名单** — 联系网络组获取 WAF/CDN 出口 IP | S1 | 1 天（等回复） |
| P0 | **清理 MEMORY.md** — 合并去重，控制 3000 字符 | P1 | 1 小时 |
| P0 | **配置数据库自动备份** — 写入 cron，每天凌晨全量 dump | D4 | 2 小时 |
| P1 | **Upload 加 volume mount** — 解决容器重建丢文件 | S4, D6 | 30 分钟 |
| P1 | **修复 conftest SQLite+StaticPool** — 让本地测试可用 | T2 | 2 小时 |
### 9.2 Phase 2 — 核心功能补齐（1-2 周）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P0 | **AI 集成** — Dify 接入（凭证已有，路由就绪，缺工作流对接） | A4 | 3-5 天 |
| P1 | **修复 64 条测试** — 按模块逐个排查修复 | T1 | 3 天 |
| P1 | **前端测试筑基** — ChatArea/ConversationList 核心组件测试 | T3 | 2 天 |
| P1 | **全端速率限制** — slowapi 覆盖所有 API 端点 | S3 | 1 天 |
| P2 | **Token 绑定 IP** — Redis 存储时绑定客户端 IP | S2 | 1 天 |
### 9.3 Phase 3 — 基础设施加固（2-4 周）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P1 | **搭建私有镜像 Registry**（NAS Harbor） | D2 | 2 天 |
| P1 | **Gitea Actions CI/CD** — 自动构建 + push + 部署 | D1, T4 | 3 天 |
| P1 | **大文件服务拆分** — admin_service / session_service 按模块拆分 | A1 | 2 天 |
| P2 | **WebSocket 改用 Redis Pub/Sub** — 支持多进程广播 | A3 | 3 天 |
| P2 | **消息队列引入（Redis Stream）** — AI 回复异步化 | A2 | 3 天 |
### 9.4 Phase 4 — 架构演进（1-2 月）
| 优先级 | 任务 | 关联问题 | 预计耗时 |
|--------|------|---------|---------|
| P1 | **PostgreSQL 主从** — 配置流复制 | A5 | 3 天 |
| P2 | **前端组件全面重构** — 按功能模块拆分"巨石组件" | — | 1 周 |
| P2 | **E2E 自动化** — Playwright/Cypress 端到端测试 | — | 1 周 |
| P3 | **外部系统集成补齐** — aTrust + eHR 对接 | — | 1 周/系统 |
| P3 | **K8s 迁移评估** — 可行性分析 + 资源估算 | — | 3 天 |
### 9.5 时间线总览
```
Week 1 Week 2 Week 3-4 Month 2
┌─────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐
│ Phase 1 │ → │ Phase 2 │ → │ Phase 3 │ → │ Phase 4 │
│ 止血 │ │ 补功能 │ │ 加固 │ │ 演进 │
├─────────┤ ├─────────┤ ├──────────┤ ├──────────────┤
│ IP白名单│ │ AI集成 │ │ 镜像Registry│ │ PG主从 │
│ MEMORY │ │ 修测试 │ │ CI/CD │ │ 前端重构 │
│ 数据库备份 │ │ 前端测试 │ │ 服务拆分 │ │ E2E自动化 │
│ Upload修复│ │ 限流 │ │ WS优化 │ │ 外部系统补齐 │
│ conftest│ │ Token绑定│ │ 消息队列 │ │ K8s评估 │
└─────────┘ └─────────┘ └──────────┘ └──────────────┘
```
---
## 十、总结
### 10.1 值得肯定的成就
- **7 个月从零到 v0.7.1**，4 个前端 + 完整后端，产品功能全面
- **安全意识高** — 多次 P0 安全修复，已实施 MFA、高危守卫、安全头等
- **文档体系远超同类项目** — 50+ 份文档，ADR、SOP、风险跟踪表一应俱全
- **工程规范良好** — CHANGELOG 标准格式、提交约定、分支模型
### 10.2 最需要关注的 3 件事
1. **🔴 AI 集成** — 这是项目的核心价值主张，"AI 驱动"写在项目名称里，不能只有人肉坐席
2. **🔴 测试体系** — 64 条失败 + 前端零测试，质量门禁缺失，这是长期积累的债务
3. **🔴 部署与运维** — 无自动化备份、手动部署、单点故障，一旦出问题恢复时间不可控
### 10.3 一句话评估
> **项目功能完整、文档优秀、安全根基扎实，但核心 AI 能力缺失和测试体系薄弱是当前最大的风险敞口。建议在推进新功能前，集中 1-2 周补齐这两块短板。**
---
*报告由 软件开发团队·主理人 齐活林 编制 | 2026-06-25*
docs/01-项目总览/04-开发交付概览.md
+125
View File
@@ -0,0 +1,125 @@
# 企微智能IT支持服务台 — 第一步开发交付概览
## TL;DR
企微智能IT支持服务台第一步（消息接管 + 极简坐席台）全部代码已完成并通过测试，共 **110+ 文件**，**116/116 测试全部通过**，覆盖后端 API、坐席工作台、用户端 H5 三个子系统。
## 交付状态
| 阶段 | 状态 | 产出 |
|------|------|------|
| PRD | ✅ 完成 | `PRD.md` — 31 需求（P0/P1/P2），7 用户故事 |
| 架构设计 | ✅ 完成 | `docs/ARCHITECTURE.md` — 9 表 DDL，7 API 组，4 时序图，5 任务分解 |
| T01 项目脚手架 | ✅ 完成 | 57 文件 — docker-compose, nginx, .env, 后端/前端骨架 |
| T02 后端核心服务 | ✅ 完成 | 16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由 |
| T03 坐席工作台 | ✅ 完成 | 25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab) |
| T04 用户端H5 | ✅ 完成 | 12 文件 — 聊天面板, 摇人按钮, AI助手, 审批链接, 软件下载 |
| QA 测试用例 | ✅ 完成 | 8 文件, 116 测试用例（原 93 + 新增 23） |
| Bug 修复 | ✅ 完成 | 7 个 Bug 修复（详见下方） |
| PostgreSQL/SQLite兼容 | ✅ 完成 | 9 个模型文件全部兼容 SQLite |
| database.py 懒加载 | ✅ 完成 | 避免测试导入时连接 PostgreSQL |
| WecomCrypto 懒加载 | ✅ 完成 | 避免默认 AES Key 导入报错 |
| **pytest 全量验证** | **✅ 116/116 通过** | 1.71 秒完成，0 失败 |
## 关键文件
```
wecom_it_smart_desk/
├── README.md # 项目主文档（GitHub 首页）
├── docker-compose.yml # Docker Compose 容器编排
├── .env # 环境变量（数据库密码等，不提交 Git）
├── backend/ # FastAPI 后端服务
│ ├── app/
│ │ ├── main.py # FastAPI 应用入口
│ │ ├── config.py # 配置管理（从 .env 读取）
│ │ ├── database.py # 懒加载数据库引擎
│ │ ├── models/ # 11 个 ORM 模型（兼容 PostgreSQL/SQLite）
│ │ ├── schemas/ # Pydantic Schema（请求/响应校验）
│ │ ├── utils/
│ │ │ └── wecom_crypto.py # 企微消息加解密（AES-CBC-256）
│ │ ├── services/
│ │ │ ├── wecom_service.py # 企微回调处理
│ │ │ ├── message_router.py # 消息路由 + 评分 + 举手检测
│ │ │ ├── scoring_service.py # 紧急度评分引擎
│ │ │ ├── session_service.py # 会话生命周期管理
│ │ │ └── funny_phrase_service.py # 摇人趣味话术生成
│ │ └── api/ # 8 个 API 路由模块
│ └── tests/ # 116+ 个测试用例
├── frontend-agent/ # 坐席工作台（Vue 3 + Element Plus）
│ └── src/
│ ├── views/ # LoginView + WorkspaceView
│ ├── components/
│ │ ├── TopBar/ # 顶部栏（主题切换 + 用户信息）
│ │ ├── conversation/ # 会话列表 + 会话条目
│ │ ├── chat/ # 聊天区 + 消息气泡 + 输入框
│ │ ├── assistant/ # AI 推荐内联组件
│ │ ├── troubleshooting/ # 排查步骤栏（FlowchartNode）
│ │ ├── quickreply/ # 快速回复面板（三层导航）
│ │ └── todo/ # 待办面板 + 任务详情视图
│ ├── stores/ # Pinia Store（conversation/agent/quickReply/theme/todo）
│ └── api/ # API 调用模块
├── frontend-h5/ # 员工端 H5（Vue 3 + Vant）
│ └── src/
│ ├── views/ # ChatView
│ └── components/ # ChatPanel + 摇人按钮 + AI助手
├── nginx/ # Nginx 反向代理配置
│ └── nginx.conf
├── scripts/ # 部署和运维脚本
│ ├── start_backend.bat # Windows 快速启动后端（相对路径）
│ └── restart_backend.ps1 # Windows 重启后端（自动查找 PG/Redis/Python）
└── docs/ # 项目文档（全部文档统一存放）
├── PRD.md # 产品需求文档 v1.0
├── PRD-v53-incremental.md # v5.3 增量需求
├── ARCHITECTURE.md # 系统架构设计（合并版）
├── 01-项目总览与部署手册.md # 管理者视角部署手册
├── 开发交付概览.md # 开发交付状态总览
├── 智能IT支持服务台-项目迁移文档.md # 工作区迁移记录
├── testing/ # 测试报告目录
│ └── QA_COMPREHENSIVE_REPORT.md # 综合 QA 报告
├── diagrams/ # Mermaid 图表
│ ├── sequence-diagram.mermaid
│ ├── sequence-shake.mermaid
│ ├── sequence-scoring.mermaid
│ ├── sequence-polling.mermaid
│ └── class-diagram.mermaid
└── prototypes/ # 原型文件
├── agent-workspace-v5_3.html # 当前锁定版本（v5.3）
├── qr_data_full.json # 快速回复数据（180条）
└── archive/ # 历史原型归档
```
## Bug 修复清单（7 个）
| # | 文件 | 问题 | 修复 |
|---|------|------|------|
| 1 | `message_router.py` | `calculate_urgency()` 是 async 但未 `await` | 添加 `await` |
| 2 | `app/main.py` | 中文引号 `""` 嵌入 Python 双引号字符串，SyntaxError | 转义引号 |
| 3 | `wecom_callback.py` | `WecomCrypto` 模块级初始化，默认 AES Key 不合法导致 `binascii.Error` | 改为懒加载单例 `_get_wecom_crypto()` |
| 4 | `tests/conftest.py` | `aioredis.from_url` mock 路径错误 | 修正为 `redis.asyncio.from_url` |
| 5 | `tests/conftest.py` | `create_test_conversation()` 缺少 `is_pinned`/`is_todo` 参数 | 添加可选参数 |
| 6 | `session_service.py` | `conversation_id` UUID 对象 vs String(36) 列类型不匹配 | 先转字符串再查询 |
| 7 | `scoring_service.py` | 关键词大小写不敏感缺失 + `_check_vip` 缺短路 | `.lower()` + 短路返回 |
## 用户下一步操作
1. **（已验证）pytest 全量通过**：116/116 测试已在开发环境验证通过，本地无需再跑
2. **配置企微应用凭证**：
- 复制 `.env.example` 为 `.env`
- 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey
3. **Docker Compose 启动**（需 PostgreSQL + Redis）：
```powershell
cd C:\Users\simon\wecom_it_smart_desk
docker-compose up -d
```
4. **前端开发启动**：
```powershell
# 坐席工作台
cd frontend-agent && npm install && npm run dev
# 用户端 H5
cd frontend-h5 && npm install && npm run dev
```
5. **企微回调配置**：在企微管理后台配置消息回调 URL 指向你的服务器
docs/01-项目总览/05-域名申请邮件.md
+36
View File
@@ -0,0 +1,36 @@
收件人：G端域名审核小组
抄送：周复曙、吕勇、朱付贵
主题：【域名申请】itsupport.servyou.com.cn — 智能IT支持服务台项目外部子域名申请
各位领导，好：
IT支持组正在推进"智能IT支持服务台"项目，借助AI能力提升IT支持的服务质量和效率，现申请外部子域名 itsupport.servyou.com.cn。
项目背景：公司日常IT支持在以下方面仍有提升空间：
1. 员工入口体验 — 转人工需另开窗口，AI与人工服务衔接不够流畅，跨企业服务不可达
2. 坐席效能与知识传承 — 回复质量依赖个人经验，新人成长周期长，经验随人员流动而流失
3. 管理数据化 — 服务质量和满意度缺乏量化数据，难以持续优化
本系统在现有AI引擎（RAGFlow+Dify+千问）基础上补齐人工服务闭环：员工端H5应用实现AI对话无缝转人工，坐席工作台提供AI辅助和快速回复，管理后台实现配置和数据管理。
域名必要性：本项目使用企业微信自建H5应用，对域名有硬性要求：
1. OAuth2.0认证需求 — 企微员工免登认证必须通过HTTPS外部域名的回调地址完成，没有外部域名则认证无法走通，系统无法使用
2. 安全合规要求 — 企微要求自建应用使用HTTPS加密传输且域名需完成ICP备案，使用公司备案域名servyou.com.cn的子域名可满足合规
3. 业务独立性 — 该域名独立于公司其他业务系统域名（如数据平台it-dataquery.dc.servyou-it.com），互不影响
技术方案：部署于公司内网Linux服务器，Docker容器化，全站HTTPS，仅开放必要端口，数据库不暴露公网。阶段一只上线核心功能（AI转人工+基础坐席），后续逐步推进并独立安全评估。
申请信息：
域名：itsupport.servyou.com.cn
类型：servyou.com.cn 二级子域名
用途：企微自建应用H5页面访问及OAuth2.0认证回调
技术要求：需添加DNS A记录指向内网服务器IP（具体IP待确认后提供）
负责人：宋献 / IT支持组
本域名是项目运行的基础性前置资源，项目已完成MVP开发，域名到位即可部署测试。恳请审核批准，如有疑问随时配合解答。谢谢！
宋献
IT支持组
2026年6月11日