Simon
7.1 KiB
7.1 KiB
企微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() + 短路返回 |
用户下一步操作
-
（已验证）pytest 全量通过：116/116 测试已在开发环境验证通过，本地无需再跑
-
配置企微应用凭证：
- 复制
.env.example为.env - 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey
- 复制
-
Docker Compose 启动（需 PostgreSQL + Redis）：
cd C:\Users\simon\wecom_it_smart_desk docker-compose up -d -
前端开发启动：
# 坐席工作台 cd frontend-agent && npm install && npm run dev # 用户端 H5 cd frontend-h5 && npm install && npm run dev -
企微回调配置：在企微管理后台配置消息回调 URL 指向你的服务器