Simon
facc04aa65
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交 （5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。 一、docs 结构整改（整改 #14） 根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入， 随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录 树并存于 docs/，共 791 文件、双分类体系冲突。 修复动作： - b2 同名异主题文件改名迁移保全 9 个 - C 类 39 个孤立文件按主题正确归类 - A/B1 类 222 个重复文件删除（新结构已有内容副本） - 9 个旧独有空目录删除 - 270 处内部引用按 verified 映射改写 - 整改记录 #14 登记于 04-运维文档/部署运维 结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。 残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。 二、compose 双目录对齐（消除踩坑 A） - docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist 改为 src/frontend-*/dist（h5 / agent / admin / terminal） - docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/ - 效果：本地 docker compose up 不再把根目录 stale dist 挂回， 与线上一致，分叉隐患消除（已 docker compose config 校验通过） 防复发铁律： - 重构须提交；仓库修复须 git stash -u 或先 commit - 新结构须 git add 并提交，避免再次 untracked 复活 - H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
126 lines
7.2 KiB
Markdown
126 lines
7.2 KiB
Markdown
# 企微智能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 图表
|
||
│ ├── 02-技术文档/技术架构/sequence-diagram-代办事项.mermaid
|
||
│ ├── sequence-shake.mermaid
|
||
│ ├── sequence-scoring.mermaid
|
||
│ ├── sequence-polling.mermaid
|
||
│ └── 02-技术文档/技术架构/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 指向你的服务器
|