Simon
364e688382
主要改动: backend 业务: - feat(error-codes): 统一错误码表 E1011/E1012 拆码 - E1011 AUTH_PASSWORD_WRONG: 本地密码错误 - E1012 AUTH_FIRST_LOGIN_PASSWORD_REQUIRED: 首次登录请先设置密码 - E1015 AUTH_OLD_PASSWORD_REQUIRED: 改密需要旧密码 - E1016 AUTH_OLD_PASSWORD_WRONG: 旧密码错误 - fix(agents): P0 降级放行时,如坐席已注册但未设密码,正确 raise 1012 (修复前会撞 1011 本地密码错误,与场景不符) - feat(approval): 审批模块 (T审批/A审批) - feat(config): approval_template_resource / approval_template_device 配置 - feat(main): /ready, /metrics, /version 端点(K8s 友好) backend 测试: - test(agents): 新增 test_agents.py — 3 个 Fix-4 降级登录测试 - 错误密码拒绝 - 缺密码拒绝 - 正确密码通过 pytest tests/test_agents.py → 3/3 通过 - test(conftest): 模块级 mock + slowapi 限流重置 + UTF-8 patch 解决 Windows pytest GBK 读 .env 失败 + 降级路径无法测试 仓库治理: - chore(gitignore): 排除 .workbuddy/memory/(workbuddy 本地记忆) - chore(docs): 重命名两份 IT 文档(前缀加智能区分版本) 部署与文档: - docs: RELEASE_NOTES_v0.5.0-beta.md / dashboard.html / 需求-发版预览页面 - docs: 部署、架构、PRD、安全、评审报告等同步 v0.5.0-beta - deploy-server: 打包脚本、nginx、docker-compose 版本号 bump 前端 (frontend-h5 / frontend-agent / frontend-admin / frontend-portal): - index.html / package.json 版本号与构建号 bump 自动验收(RELEASE_NOTES L100-104): - [x] pytest tests/test_agents.py -v → 3 passed - [x] grep Bs7ucT backend frontend-h5 frontend-agent → 无输出 - [x] grep AppException(101[123]) backend → 仅 1 处(登录场景 1012) - [ ] npm run build (frontend-h5 / frontend-agent) → 合并后跑 后续: 合并 feature/t-1-t4-merge → main,tag v0.5.0-beta
126 lines
7.1 KiB
Markdown
126 lines
7.1 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 图表
|
||
│ ├── 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 指向你的服务器
|