wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-用户-006-智能推荐重构.md

# 任务说明书 - H5 智能推荐重构

> **REQ 编号**: REQ-用户-006
> **版本**: v1.0
> **日期**: 2026-07-28
> **作者**: 宋献 (Simon) + Duckula
> **状态**: 🟡 待开工（PRD v1.0-Frozen + 技术方案 v1.0 已就位，可启动阶段 1）
> **依赖**:
> - **PRD（冻结）**：`docs/01-产品文档/05-用户端H5/PRD-REQ-用户-006-智能推荐重构-v1.0-Frozen.md`
> - **技术方案**：`docs/02-技术文档/技术架构/技术方案-REQ-用户-006-智能推荐重构-v1.0.md`
> - **原型图**：🟡 待写（基于 PRD §4.5 UI 规范）

---

## 一、基本信息

| 项目 | 内容 |
|------|------|
| **任务名称** | H5 智能推荐重构 |
| **关联 PRD** | REQ-用户-006 v1.0-Frozen |
| **关联技术方案** | 技术方案 v1.0 |
| **任务等级** | P0（影响所有员工 H5 端核心体验） |
| **预估工期** | 7 天（含部署 + 灰度） |
| **参与角色** | 工程师（后端 2 天 + 前端 1.5 天）/ QA（1 天）/ 部署（1 天）/ PM（协调 + 灰度观察 1.5 天） |
| **风险等级** | 中（涉及 4 类触发源改造 + 持久化方案） |
| **回滚预案** | 已就绪（详见技术方案 §16.3） |

---

## 二、输入项来源

### 2.1 已就位

- ✅ **PRD v1.0-Frozen**：§4.7 5 个核心决策已审定（① A / ② B / ③ B / ④ B / ⑤ B）
- ✅ **技术方案 v1.0**：19 章节含完整代码示例与架构图
- ✅ **现有代码**：`asset_recommend_service.py` / `assets.yaml` / `h5_ai_task.py` / `RightPanel.vue`

### 2.2 待补充

- 🟡 **原型图 v1.0**：基于 PRD §4.5 UI 规范（无标题 + FIFO + 4 类卡片样式）
- 🟡 **测试用例**：基于技术方案 §17 测试策略（30+10+15 用例规划）

### 2.3 上游依赖

- **Alembic 工具链**：蓝绿环境已就位
- **企微审批 webhook 接收地址**：需提前与运维确认（详见 §5.3）
- **Redis 同源抑制缓存**：复用现有 Redis 实例（已确认）

---

## 三、输出成果

### 3.1 代码交付物（17 项）

| # | 类型 | 路径 | 状态 |
|---|------|------|------|
| 1 | 配置 | `src/backend/app/config/assets.yaml` | 🟡 待改造 |
| 2 | 后端 | `src/backend/app/services/asset_recommend_service.py` | 🟡 待重构 |
| 3 | 后端 | `src/backend/app/services/recommend_progress_service.py` | ⚪ 新增 |
| 4 | 后端 | `src/backend/app/services/topic_detector.py` | ⚪ 新增 |
| 5 | 后端 | `src/backend/app/services/employee_profile_service.py` | 🟡 待扩展 |
| 6 | 后端 | `src/backend/app/tasks/h5_ai_task.py` | 🟡 待改造 |
| 7 | 后端 | `src/backend/app/api/recommend.py` | ⚪ 新增 |
| 8 | 迁移 | `alembic/versions/{revision}_add_recommend_progress.py` | ⚪ 新增 |
| 9 | 迁移 | `alembic/versions/{revision}_add_recommend_event.py` | ⚪ 新增 |
| 10 | 前端 | `src/frontend-h5/src/stores/recommendStore.ts` | ⚪ 新增 |
| 11 | 前端 | `src/frontend-h5/src/components/assistant/DynamicRecommend.vue` | 🟡 待重构 |
| 12 | 前端 | `src/frontend-h5/src/components/assistant/RightPanel.vue` | 🟡 待适配 |
| 13 | 前端 | `src/frontend-h5/src/composables/useRecommendWs.ts` | ⚪ 新增 |
| 14 | 测试 | `src/backend/tests/services/test_asset_recommend_v2.py` | ⚪ 新增 |
| 15 | 测试 | `src/backend/tests/services/test_recommend_progress.py` | ⚪ 新增 |
| 16 | 测试 | `src/backend/tests/services/test_topic_detector.py` | ⚪ 新增 |
| 17 | 测试 | `src/frontend-h5/tests/stores/recommendStore.test.ts` | ⚪ 新增 |

### 3.2 数据库交付物（2 张新表）

- `recommend_progress`（审批进度持久化）
- `recommend_event`（推荐埋点）

### 3.3 部署交付物

- 后端部署包（zip）
- 前端 dist 部署包
- Alembic 迁移 SQL 应急脚本（容器内 alembic 失败时备用）

### 3.4 文档交付物（3 份）

- 原型图 v1.0（🟡 待写）
- 测试用例 v1.0（🟡 待写）
- 部署文档 v1.0（基于技术方案 §16）

---

## 四、验证方式

### 4.1 单元测试

| 模块 | 用例数 | 通过率要求 |
|------|--------|----------|
| asset_recommend_service | 30+ | 100% |
| recommend_progress_service | 10+ | 100% |
| topic_detector | 15+ | 100% |
| recommendStore | 10+ | 100% |

### 4.2 集成测试

- WS 协议全链路（A + B + C + D + T2）
- 多源合并（4 类来源同帧推送）
- 持久化（localStorage 跨会话）

### 4.3 E2E 测试（agent-browser）

| 场景 | 验证点 |
|------|--------|
| 员工发"VPN 申请" | 右侧栏出 VPN 卡 + 审批进度回流 |
| 员工切换话题 | 旧 L1 推荐清空，L2/L3/progress 保留 |
| 关闭浏览器再打开 | localStorage 持久卡片仍在 |
| 冷启动 | 进会话 5s 内右侧栏完全空（PRD §4.7.4 决策 ① A） |
| 画像 API 故障 | C → D 降级，D 仍能展示 |

### 4.4 数据埋点

通过 `recommend_event` 表统计：
- 各 layer 推荐曝光数
- 各 layer 推荐点击数（点击率）
- 自助解决率（点击后 5 分钟内未发新消息）
- 降级触发次数（C → D、D → 空）

### 4.5 灰度验证指标

| 阶段 | 指标 | 不达标处理 |
|------|------|----------|
| 1% 灰度（10 人，1 天） | 无 P0/P1 错误 | 立即回滚 |
| 10% 灰度（100 人，2 天） | 点击率 > 5% | 暂停灰度排查 |
| 50% 灰度（500 人，3 天） | 点击率 > 10% | 暂停灰度排查 |
| 100% 全量 | 点击率 > 15%，自助解决率 > 10% | 长期监控 |

---

## 五、实施步骤（WBS）

### 阶段 0：准备（已完成）✅

| 任务 | 工时 | 状态 |
|------|------|------|
| 0.1 PRD v1.0-Frozen | 0.5h | ✅ 2026-07-28 |
| 0.2 技术方案 v1.0 | 1.5h | ✅ 2026-07-28 |
| 0.3 任务说明书 v1.0（本文档） | 0.5h | ✅ 2026-07-28 |
| 0.4 原型图 v1.0 | 0.5h | 🟡 待启动 |

### 阶段 1：后端基础（2 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **1.1** `assets.yaml` 扩展 | 0.5h | 无 | 中文 role key + 同义词表 + 排除关键词 |
| **1.2** `asset_recommend_service.py` 重构 | 2h | 1.1 | `match_keywords` 加词频权重、`match_profile_triggers` 加缓存画像降级、`get_by_role` 加中文子串匹配、新增 `merge_recommends` 算法 |
| **1.3** `employee_profile_service.py` 扩展 | 1h | 无 | 新增 `_get_cached_profile_from_db` 方法（DB 设备登记表兜底） |
| **1.4** Alembic 迁移（双表） | 1h | 无 | `recommend_progress` + `recommend_event` 表 + 索引 |
| **1.5** 后端单元测试 | 2h | 1.1~1.4 | `test_asset_recommend_v2.py`（30+ 用例） |
| **阶段 1 验收** | 0.5h | 1.5 | pytest 100% 通过 |

**关键决策点**：
- 1.2 中 `merge_recommends` 必须严格遵循 PRD §4.7.3 规则（去重 + 排序 + 上限 3）
- 1.4 Alembic 必须双轨准备（迁移脚本 + init SQL 应急）

### 阶段 2：后端新增（1 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **2.1** `recommend_progress_service.py` 新增 | 2h | 1.4 | `handle_approval_webhook` + `poll_pending_approvals`（60s 轮询） |
| **2.2** `topic_detector.py` 新增 | 1h | 无 | `jaccard_similarity` + `detect_topic_change` |
| **2.3** `recommend.py` REST API 新增 | 1h | 2.1 | GET `/api/recommend/progress/{approval_id}` + POST `/api/webhook/wecom-approval` |
| **2.4** WS type=recommend_update 推送 | 0.5h | 2.1 | 在 `recommend_progress_service` 中集成 `ws_manager.broadcast_to_employees` |
| **2.5** 后端单元测试（新增模块） | 1.5h | 2.1~2.4 | `test_recommend_progress.py`（10+ 用例）+ `test_topic_detector.py`（15+ 用例） |
| **阶段 2 验收** | 0.5h | 2.5 | pytest 100% 通过 |

**关键决策点**：
- 2.1 中 60s 轮询必须异步启动，不能阻塞请求处理
- 2.3 中 webhook 接收需做签名校验（与企微侧联调）

### 阶段 3：后端集成（0.5 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **3.1** `_step_assets` 改造 | 1h | 1.2 + 1.3 | 加 3s 超时 + 完整降级链路（A → B/C/D、B → C/D、C → D、D → 空） |
| **3.2** `_step_persist` 加标识字段 | 0.5h | 无 | `recommend_data` 加 `source` + `trigger_timing` + `layer` 字段 |
| **3.3** 后端集成测试 | 1h | 3.1~3.2 | WS 协议全链路（4 来源 + 5 决策全验证） |
| **阶段 3 验收** | 0.5h | 3.3 | pytest 100% 通过 + 手动 mock 全链路通 |

### 阶段 4：前端状态机（1 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **4.1** `recommendStore.ts` 新增 | 2h | 技术方案 §7.1 | Pinia store（state/cards/actions + localStorage） |
| **4.2** `DynamicRecommend.vue` 重构 | 2h | 4.1 | 无标题 + FIFO + 4 类卡片 + 上限 3 张 |
| **4.3** `RightPanel.vue` 适配 | 1h | 4.1 + 4.2 | 移除"智能推荐"标题，引用 store |
| **4.4** 前端单元测试 | 1h | 4.1~4.3 | `recommendStore.test.ts`（10+ 用例） |
| **阶段 4 验收** | 0.5h | 4.4 | vitest 100% 通过 + 手动冷启动验证空状态 |

**关键决策点**：
- 4.1 中 store 状态机必须严格遵循 PRD §4.7.4 决策 ① A（无则隐）
- 4.2 中 `getCardComponent(card)` 按 source 字段路由到不同子组件

### 阶段 5：前端交互（0.5 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **5.1** WS 接收 `recommend_update` | 0.5h | 4.1 + 阶段 3 | `useRecommendWs.ts` 新增 + 调 `store.updateProgress` |
| **5.2** 话题切换触发清空 | 0.5h | 4.1 | 客户端按 Jaccard 检测（复用 `topic_detector` 算法） |
| **5.3** 跨会话持久化 | 0.5h | 4.1 | 初始化时 `loadFromLocalStorage`，变动时 `persistToLocalStorage` |
| **5.4** 前端集成测试 | 1h | 5.1~5.3 | 端到端 WS + 持久化场景 |

### 阶段 6：E2E 测试 + 验收（1 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **6.1** E2E 测试用例（agent-browser） | 3h | 阶段 5 | 5 个场景（VPN / 切换话题 / 持久化 / 冷启动 / 降级） |
| **6.2** 数据埋点验证 | 1h | 6.1 | `recommend_event` 表写入验证 |
| **6.3** BUG 修复（迭代） | 2h | 6.1~6.2 | BUG 单闭环 |

### 阶段 7：部署 + 灰度（1.5 天）

| 任务 | 工时 | 依赖 | 产物 |
|------|------|------|------|
| **7.1** 后端部署（含 Alembic + Init SQL 双轨） | 1h | 阶段 1~3 | `/opt/wecom-it-desk/app/` 更新 |
| **7.2** 前端部署（dist + nginx reload） | 0.5h | 阶段 4~5 | `/opt/wecom-it-desk/frontend-h5/dist/` 更新 |
| **7.3** 1% 灰度（10 人） | 1 天 | 7.1 + 7.2 | 观察 24h 无 P0/P1 错误 |
| **7.4** 10% 灰度（100 人） | 2 天 | 7.3 | 点击率 > 5% |
| **7.5** 50% 灰度（500 人） | 3 天 | 7.4 | 点击率 > 10% |
| **7.6** 100% 全量 | - | 7.5 | 点击率 > 15% |

### 阶段 8：长期监控（持续）

| 任务 | 频率 | 工具 |
|------|------|------|
| 8.1 关键指标日监控（点击率/自助解决率） | 每日 | `recommend_event` 聚合查询 |
| 8.2 BUG 单闭环 | 持续 | BUG 单系统 |
| 8.3 配置热更新（assets.yaml） | 按需 | `asset_recommend_service.reload()` |

---

## 六、WBS 汇总表

| 阶段 | 工时 | 累计 | 关键产物 |
|------|------|------|---------|
| 阶段 0 | 2.5h | 2.5h | PRD + 技术方案 + 任务说明书 + （待）原型图 |
| 阶段 1 后端基础 | 7h | 9.5h | assets.yaml + asset_recommend 重构 + 双表 |
| 阶段 2 后端新增 | 6.5h | 16h | recommend_progress + topic_detector + 新 API |
| 阶段 3 后端集成 | 3h | 19h | _step_assets + _step_persist 改造 |
| 阶段 4 前端状态机 | 6.5h | 25.5h | recommendStore + DynamicRecommend + RightPanel |
| 阶段 5 前端交互 | 2.5h | 28h | WS 接收 + 话题切换 + 持久化 |
| 阶段 6 E2E + 验收 | 6h | 34h | 5 场景测试 + 埋点 |
| 阶段 7 部署 + 灰度 | 0.5h + 6 天观察 | 34.5h | 4 阶段灰度 |
| 阶段 8 长期监控 | 持续 | - | 指标监控 + BUG 闭环 |

**总工时**：约 34.5 小时（约 4.5 个工作日人工）+ 6 天灰度观察

---

## 七、风险与回滚

### 7.1 风险清单

| 风险 | 等级 | 概率 | 缓解措施 |
|------|------|------|---------|
| R1：Dify 升级后 action 字段结构变化 | 中 | 中 | 2.3 中保留旧字段解析兼容 |
| R2：画像 API 长时间不可用 | 中 | 中 | 1.3 已实现 DB 缓存降级 |
| R3：localStorage 配额超限（5MB） | 低 | 低 | 仅持久 L2/L3/progress，LRU 淘汰 |
| R4：企微 webhook 推送失败 | 中 | 中 | 2.1 已实现 60s 轮询兜底 |
| R5：灰度期间指标不达标 | 中 | 中 | 每阶段不达标暂停排查 |

### 7.2 回滚预案

**触发条件**（任一）：
- P0/P1 错误率 > 5%
- 推荐卡片渲染失败 > 2%
- WS 推送延迟 > 5s

**回滚步骤**（已就绪，详见技术方案 §16.3）：
1. 后端：`docker compose restart backend`（保留 DB 数据）
2. 前端：`docker restart wecom_it_nginx`
3. DB（极端情况）：`alembic downgrade -1`（删除新增双表）
4. 通知：群发"已回滚至 v2.3 现状"通知

**回滚时间预算**：< 30 分钟

---

## 八、关联文档

- **PRD**：`docs/01-产品文档/05-用户端H5/PRD-REQ-用户-006-智能推荐重构-v1.0-Frozen.md`
- **技术方案**：`docs/02-技术文档/技术架构/技术方案-REQ-用户-006-智能推荐重构-v1.0.md`
- **现有代码**：
  - `src/backend/app/services/asset_recommend_service.py`
  - `src/backend/app/config/assets.yaml`
  - `src/backend/app/tasks/h5_ai_task.py`
  - `src/frontend-h5/src/components/assistant/DynamicRecommend.vue`
  - `src/frontend-h5/src/components/assistant/RightPanel.vue`
- **相关 PRD**：
  - `docs/01-产品文档/03-AI服务/PRD-REQ-AI-004-AI回复来源标识-v1.0.md`
- **历史实施计划**：
  - `docs/02-技术文档/实现配置/AI对话链路全栈改造实施计划-v1.0.md`
- **前端设计**：
  - `docs/02-技术文档/前端改造/前端设计-H5右侧栏动态推送-v1.0.md`
  - `docs/02-技术文档/前端改造/设计-H5用户端实现概览-v1.0.md`

---

## 九、变更日志

| 版本 | 日期 | 变更内容 | 作者 |
|------|------|---------|------|
| v1.0 | 2026-07-28 19:24 | 初版：基于 PRD v1.0-Frozen + 技术方案 v1.0，给出 8 阶段 WBS（34.5h + 6 天灰度）+ 17 项代码交付物 + 5 类风险回滚 | Duckula + 宋献 |