simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e196d5a3e3f96c402c337e888b49e8610cb80828
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-用户-006-智能推荐重构.md
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

313 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 任务说明书 - 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 + 宋献 |
Reference in New Issue View Git Blame Copy Permalink