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 + 宋献