wecom_it_smart_desk/docs/路线图/阶段2-3-任务.md

# 5 阶段路线图 — 阶段 2-3 任务拆解

**生成日期**: 2026-06-14
**生成人**: Claude
**状态**: 待 workbuddy 接入执行(workbuddy-claude user 创好后启动)
**关联**: PRD.md §5 五阶段演进路径

---

## 阶段 1 完成度盘点(对照 PRD.md §5.1)

| 阶段 1 项 | 状态 | 备注 |
|---|---|---|
| 员工端 H5 WebView | ✅ 完成 | `frontend-h5/` |
| OAuth2 静默授权 + 身份识别 | ✅ 完成 | `backend/app/api/h5.py` |
| 坐席工作台 MVP | ✅ 完成 | `frontend-agent/` |
| 三栏工作台 | ✅ 完成 | 会话列表 / 对话区 / AI 助手 |
| 6 分区会话列表 | ✅ 完成 | 待接单/我的/协作/其他坐席/AI处理/已结单 |
| 快速回复 7 大类 | ✅ 完成 | 28 子类 180 模板 |
| 转人工触发 | ✅ 完成 | 关键字检测 → 推 H5 链接 |
| WebSocket 实时推送 | ✅ 完成 | P0 鉴权修复后 |
| 应急模式 | ✅ 完成 | 系统故障时手动开 |
| Alembic 迁移 | 🟡 部分 | 008 (agent password) + 009 (message status) 已加,初始 001 缺 |

**剩余扫尾**:
- [ ] 初始 alembic 迁移(把当前 schema 导出成 001 基准,后续 migrations 增量)
- [ ] pytest 基础配置(README 已知问题 #2)
- [ ] P1-1 优化(named volume → host bind mount,任务 #25)
- [ ] P0 二次评审 5 遗留(浏览器 WS API / nginx access_log / 类型 bug / 降级放行 / 缺依赖)

---

## 阶段 2: H5 员工端完整体验 + 双通道消息推送

**目标**: 员工 H5 端从 MVP 升级到完整体验,加 摇人 / 评分 / 排队,推送到企微应用消息

**对应 PRD.md**: §5.2 阶段二,§痛点1(分散渠道)

### 2.1 任务清单(8 项)

| # | 任务 | 优先级 | 文件位置 | 阻塞 |
|---|---|---|---|---|
| 2-1.1 | 摇人按钮(H5 输入框左侧,7 种 SVG 动画) | 🟡 重要 | `frontend-h5/src/components/KnockButton.vue` | 无 |
| 2-1.2 | 满意度评价(会话结束 → 弹 5 星 + 文字反馈) | 🟡 重要 | `frontend-h5/src/components/ConversationRating.vue` | 无 |
| 2-1.3 | 排队系统(多员工同时咨询,显示"前面 N 位") | 🟡 重要 | `backend/app/api/conversations.py` + `frontend-h5/src/views/QueueStatus.vue` | 无 |
| 2-1.4 | 快速回复 7 大类 28 子类 180 模板(已有,需补完) | 🟢 常规 | `backend/app/models/quick_reply.py` | 无 |
| 2-1.5 | 知识库基础(FAQ 手动维护,坐席/员工可查) | 🟡 重要 | `backend/app/api/knowledge.py` (新) | 无 |
| 2-1.6 | 企微应用消息推送(双通道:企微应用消息 + WebSocket) | 🟡 重要 | `backend/app/services/wecom_push.py` | WECOM 应用 secret |
| 2-1.7 | 消息已读回执(员工读完 → 推 message_status) | 🟡 重要 | `backend/app/api/messages.py:mark_read` | 已有 ws_manager.broadcast |
| 2-1.8 | 会话转接(坐席 A → 坐席 B,带交接说明) | 🟢 常规 | `backend/app/api/conversations.py:transfer` | 无 |

### 2.2 验收标准

- [ ] 员工在 H5 看到会话输入框左侧"摇人"按钮,点击 → 7 种动画之一 + 企微应用消息推送
- [ ] 会话结束 → 员工看到 5 星评价 + 文字反馈框 → 提交 → 落库
- [ ] 多员工并发咨询 → 排队显示"您前面有 N 位" + 预计等待时间
- [ ] 坐席/员工可查 FAQ,输入关键字 → 命中模板
- [ ] 员工 1 分钟内未读 → 推企微应用消息"您有一条新消息"
- [ ] 员工点开消息 → mark_read 调 → ws_manager 广播 → 坐席端"已读"标识

### 2.3 与 P0/P1 修复的关联

- 2-1.6 推送用到 P0 已修的 WS 鉴权
- 2-1.7 已读回执用到 P1-4 已实现的 `broadcast_message_status`
- 2-1.5 知识库要等阶段 4 闭环,先做基础 CRUD

### 2.4 预估工时

| 任务 | 预估人天 | 难度 |
|---|---|---|
| 2-1.1 摇人 | 2 | 低(Vue 组件 + 已有 SVG 库) |
| 2-1.2 满意度 | 1.5 | 低(弹窗 + 后端落库) |
| 2-1.3 排队 | 3 | 中(后端排队算法 + 前端轮询) |
| 2-1.4 快速回复补完 | 2 | 低(数据导入 + CRUD) |
| 2-1.5 知识库基础 | 5 | 中(模型 + 检索 + UI) |
| 2-1.6 企微应用消息 | 3 | 中(企微 API + 降级) |
| 2-1.7 已读回执 | 1 | 低(接 P1-4) |
| 2-1.8 会话转接 | 2 | 低(已有 transfer 端点) |
| **合计** | **19.5** | |

---

## 阶段 3: 坐席工作台 AI Wingman

**目标**: 给坐席端加 AI 辅助(草稿回复 / 自动摘要 / 知识推荐 / 排查步骤)
**对应 PRD.md**: §5.2 阶段三,§痛点2(坐席重复劳动)

### 3.1 任务清单(6 项)

| # | 任务 | 优先级 | 文件位置 | 阻塞 |
|---|---|---|---|---|
| 3-1.1 | AI 草稿回复(坐席输入 → AI 给回复草稿 → 坐席改/发) | 🟡 重要 | `backend/app/api/ai_wingman.py` (新) | Dify 集成 |
| 3-1.2 | 自动摘要(会话结束 → AI 生成 200 字摘要) | 🟡 重要 | `backend/app/services/summarizer.py` (新) | Dify 集成 |
| 3-1.3 | 知识推荐(对话中识别关键字 → 推 FAQ / 排查步骤) | 🟡 重要 | `backend/app/api/knowledge.py:recommend` | 2-1.5 知识库 |
| 3-1.4 | 排查步骤生成(员工描述问题 → AI 给 step-by-step) | 🟡 重要 | `backend/app/api/ai_wingman.py:troubleshoot` | Dify 集成 |
| 3-1.5 | 会话标注(坐席标"AI 推荐有用/无用") | 🟢 常规 | `backend/app/models/annotation.py` (新) | 无 |
| 3-1.6 | 坐席端 AI 助手面板(右侧栏,实时显示 AI 草稿) | 🟡 重要 | `frontend-agent/src/components/AIWingmanPanel.vue` | 3-1.1~4 后端 |

### 3.2 验收标准

- [ ] 坐席输入框打字 → 右侧 AI 面板显示 3 条草稿回复(实时)
- [ ] 坐席点"采用" → 草稿填入输入框 → 可改后发送
- [ ] 会话结束 → 自动生成 200 字摘要存库
- [ ] 对话中员工说"VPN 连不上" → AI 推 5 条排查步骤
- [ ] 坐席标注"有用/无用" → 落库 → 用于阶段 4 知识库迭代

### 3.3 Dify 集成前置

- 阶段 3 强依赖 Dify 工作流(已有 `docs/现有系统交接文档内容.txt` 描述)
- workbuddy W-4 任务 = Dify API 集成预研(POC),阶段 3 启动前完成
- 风险: 企微 AI 机器人已在用 Dify,要确认是否新开 app / 共用

### 3.4 预估工时

| 任务 | 预估人天 | 难度 |
|---|---|---|
| 3-1.1 草稿回复 | 5 | 高(Dify 流式 + 实时推送) |
| 3-1.2 自动摘要 | 3 | 中(异步任务 + 触发时机) |
| 3-1.3 知识推荐 | 3 | 中(向量检索 + 评分) |
| 3-1.4 排查步骤 | 4 | 中(Dify prompt 工程) |
| 3-1.5 会话标注 | 2 | 低(模型 + UI) |
| 3-1.6 右侧栏 | 3 | 中(实时更新 + 草稿交互) |
| **合计** | **20** | |

---

## 阶段 2-3 总工时 + 关键路径

```
阶段 2 累计: 19.5 人天
阶段 3 累计: 20 人天
合计: 39.5 人天
```

**关键路径**:
1. Dify 集成预研(W-4)→ 阶段 3 启动前置
2. 知识库基础(2-1.5)→ 阶段 3 知识推荐(3-1.3)前置
3. 摇人 / 评分 / 排队(2-1.1~3)可并行

---

## 启动条件(给 workbuddy)

workbuddy-claude user account 创好后,把这份文档读进 `.workbuddy/memory/`,按以下顺序接任务:

1. **先收尾 P1-1 优化 + 5 P0 遗留 + 初始 alembic**(#25 + 5 遗留 + 001 基准)
2. **阶段 2.1** → 2-1.1 摇人(Vue 组件简单,热身)
3. **阶段 2.2~3** → 满意度 / 排队
4. **阶段 2.5~6** → 知识库基础 + 企微应用消息(企微 secret 需用户给)
5. **Dify 集成预研**(W-4)→ 阶段 3 启动
6. **阶段 3 全部**

每完成一项 → 提交 commit → 推 Gitea(走 pre-commit-check.sh 4 件套)→ Claude 评审 → 合 main

---

## 风险与依赖

| 风险 | 等级 | 缓解 |
|---|---|---|
| Dify API 限流 | 🟡 | 加 Redis 缓存 + 异步队列 |
| 企微应用消息配额 | 🟡 | 双通道降级(WS 优先) |
| 知识库检索召回率 | 🟡 | 阶段 4 闭环后优化 |
| workbuddy token 不稳定 | 🟠 | 用户创 workbuddy-claude user 解决 |
| 阶段 2 推 main 冲突 | 🟡 | 强制走 PR + 评审 |