Files

T

Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交）

本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/

2026-08-07 22:31:32 +08:00

14 KiB

Raw Blame History

任务说明书 - 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）：

后端：docker compose restart backend（保留 DB 数据）
前端：docker restart wecom_it_nginx
DB（极端情况）：alembic downgrade -1（删除新增双表）
通知：群发"已回滚至 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 + 宋献

14 KiB Raw Blame History Unescape Escape

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

一、基本信息

二、输入项来源

2.1 已就位

2.2 待补充

2.3 上游依赖

三、输出成果

3.1 代码交付物（17 项）

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

3.3 部署交付物

3.4 文档交付物（3 份）

四、验证方式

4.1 单元测试

4.2 集成测试

4.3 E2E 测试（agent-browser）

4.4 数据埋点

4.5 灰度验证指标

五、实施步骤（WBS）

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

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

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

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

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

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

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

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

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

六、WBS 汇总表

七、风险与回滚

7.1 风险清单

7.2 回滚预案

八、关联文档

九、变更日志

14 KiB

Raw Blame History