wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-用户-007-自助诊断面板优化.md

任务说明书 - H5 自助诊断面板优化

REQ 编号: REQ-用户-007 版本: v1.0 日期: 2026-07-29 作者: 宋献 (Simon) + Duckula 状态: 🟡 待开工（PRD v1.0-Frozen + 技术方案 v1.0 已就位，可启动） 依赖:

• PRD（冻结）：docs/01-产品文档/05-用户端H5/PRD-REQ-用户-007-自助诊断面板优化-v1.0.md
• 技术方案：docs/02-技术文档/技术架构/技术方案-REQ-用户-007-自助诊断面板优化-v1.0.md
• 原型图：docs/01-产品文档/05-用户端H5/原型-REQ-用户-007-自助诊断面板优化-v1.0.html（已升级 v2.3）
• 测试用例：docs/03-测试文档/03-功能测试用例/TC-REQ-用户-007-自助诊断面板优化.md

---

一、基本信息

项目	内容
任务名称	H5 自助诊断面板优化（异常徽章 + 6 Tab 横向 + 移动端 toggle + queue 合并）
关联 PRD	REQ-用户-007 v1.0-Frozen
关联技术方案	技术方案 v1.0
任务等级	P1（优化类，影响员工日常体验）
预估工期	1.5 天（含部署 + 验证）
参与角色	前端工程师（1.5 天）/ QA（0.5 天）/ 部署（0.5 天）
风险等级	低（仅前端 UI 改造，无后端/数据层变更）
回滚预案	已就绪（前端 dist 替换即可）

二、输入项来源

2.1 已就位

• ✅ PRD v1.0-Frozen：7 项决策已锁定（决策 ① Tab 精简 / ② 分级徽章 / ③ 接入中 A / ④ Tab 切换天然 / ⑤ 移动端 toggle A / ⑥ queue 合并 / ⑦ M1 双角标）
• ✅ 技术方案 v1.0：3 文件 + 1 补充文件改动，11 章节含完整代码示例
• ✅ 原型图：v2.3 升级已完成，决策已全部展示
• ✅ 测试用例：待启动（基于技术方案 §8 验收标准）
• ✅ 现有代码：4 个前端文件已 Read 核验

2.2 上游依赖

• 无 ALEMbic 迁移需求
• 无后端 API 变更
• 无新增 npm 依赖
• 部署通道：jumpserver-V2（已就绪）

三、输出成果

3.1 代码交付物（4 项）

#	文件	改动类型	状态
1	src/frontend-h5/src/components/assistant/SelfDiagnosis.vue	补充（新增 totalBadge computed + 模板）	🟡 待改造
2	src/frontend-h5/src/components/assistant/QueueWaiting.vue	扩展（新增 showPosition prop）	🟡 待改造
3	src/frontend-h5/src/components/assistant/RightPanel.vue	改造（queue-header-v3 内联三件套 + 传 :show-position="false"）	🟡 待改造
4	src/frontend-h5/src/views/ChatView.vue	改造（移动端 toggle 按钮 + isMobilePanelOpen state）	🟡 待改造

3.2 文档交付物（5 份）

#	文档	状态
1	PRD v1.0-Frozen	✅ 已建
2	技术方案 v1.0	✅ 已建
3	任务说明书 v1.0（本文档）	🟡 当前
4	测试用例 v1.0	🟡 待建
5	原型图 v2.3（已升级，重命名待办）	✅ 已升级

3.3 部署交付物

• 前端 dist 部署包（npm run build → ships to /opt/wecom-it-desk/frontend-h5/dist/）
• docker restart wecom_it_nginx（让 bind mount 刷新）

四、验证方式

4.1 单元测试

模块	用例数	通过率要求
SelfDiagnosis computed (totalBadge, totalBadgeByLevel, showCelebrate)	6+	100%
QueueWaiting props (showPosition true/false/undefined)	3+	100%

4.2 集成测试（手动 + agent-browser）

• 桌面端（≥500px）：双栏正常，自助诊断/智能推荐/排队全部正常，异常徽章显示 5W·0F
• 移动端（<500px）默认：显示左对话，顶部可见 💬 对话 / 🩺 信息 切换按钮
• 移动端切换：点击 🩺 显示右栏（手风琴+智能推荐+排队），点击 💬 切回左对话
• 移动端状态保留：切换后左对话滚动位置 + 输入文本保留
• queue 标题栏：显示 ⏳ 排队等待 #5 前面4人 LV.3 120分 [答题挑战]，queue-content 内不重复显示位置卡片
• Tab 切换：切到"账号" Tab 只显示账号相关项；切到"设备" Tab 只显示设备相关项
• 异常+接入混合：未来"安全" Tab 出现 1 异常 + 2 接入时显示 安全 1•2
• 0 异常：模拟清除所有异常，触发"✓ 今日安全"达标动画 3 秒后渐隐

4.3 数据埋点

无需新增埋点（沿用现有 recommend_event 表）。

4.4 灰度验证

本需求 P1 级别，直接全量发布（因为风险低且不影响核心流程）。

五、实施步骤（WBS）

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

任务	工时	状态
0.1 PRD v1.0-Frozen	0.5h	✅ 2026-07-29
0.2 技术方案 v1.0	0.5h	✅ 2026-07-29
0.3 任务说明书 v1.0（本文档）	0.3h	✅ 2026-07-29
0.4 原型图 v2.3 升级	0.5h	✅ 2026-07-29
0.5 测试用例 v1.0	0.3h	🟡 待启动

阶段 1：前端改造（0.5 天）

任务	工时	依赖	产物
1.1 SelfDiagnosis.vue 新增 totalBadge computed	0.5h	无	totalBadge, totalBadgeByLevel, showCelebrate
1.2 SelfDiagnosis.vue 模板改造（标题栏 + 总徽章）	0.5h	1.1	<span class="header__total-badge"> 渲染
1.3 QueueWaiting.vue 新增 showPosition prop	0.2h	无	props 定义 + v-if 渲染
1.4 RightPanel.vue queue-header-v3 内联三件套	0.5h	1.3	标题栏 qh-position-inline / qh-lv-inline / qh-points-inline
1.5 RightPanel.vue 传 :show-position="false"	0.1h	1.4	QueueWaiting 隐藏 position-card
1.6 ChatView.vue 移动端 toggle 按钮	0.5h	无	顶部双按钮 + isMobilePanelOpen state
1.7 ChatView.vue showRightPanel 改造	0.2h	1.6	桌面端 true / 移动端由 toggle 控制
1.8 全局 CSS 补充（动画 keyframes）	0.2h	1.1	celebratePulse 2.4s 循环
阶段 1 验收	0.3h	1.1~1.8	npm run build 成功 + dist 包含新 hash

关键决策点：

• 1.4 中 queue-header 内联三件套需 flex-wrap: wrap 应对窄屏
• 1.6 中 toggle 按钮要 v-if=isMobile（桌面端不渲染）
• 1.7 中 showRightPanel 必须配合 v-show（不卸载 DOM）保留状态

阶段 2：本地构建（0.5h）

任务	工时	依赖	产物
2.1 ASCII 路径下 npm run build	0.5h	阶段 1	dist/ 包含 4 个新文件 + 新 hash

阶段 3：部署（0.5h）

任务	工时	依赖	产物
3.1 压缩 dist 为 zip	0.1h	2.1	frontend-h5-dist-h5v007-YYYYMMDD.zip
3.2 jumpserver-V2 上传 + 解压	0.2h	3.1	/opt/wecom-it-desk/frontend-h5/dist/ 更新
3.3 docker restart wecom_it_nginx	0.1h	3.2	bind mount 刷新新文件
3.4 验证首页 200 OK	0.1h	3.3	curl /itdesk/ 返回 200

阶段 4：E2E 验证（1h）

任务	工时	依赖	产物
4.1 桌面端 e2e（agent-browser）	0.3h	阶段 3	异常徽章 + 6 Tab 行为 + queue 合并验证
4.2 移动端 e2e（模拟 <500px）	0.3h	阶段 3	toggle 切换 + 左对话状态保留验证
4.3 边界场景验证	0.2h	4.1+4.2	异常+接入混合、0 异常达标动画
4.4 BUG 修复（迭代）	0.5h	4.1~4.3	BUG 单闭环

阶段 5：收尾（0.5h）

任务	工时	依赖	产物
5.1 设计文档 v2.3 章节追加	0.2h	阶段 4	设计-H5用户端实现概览-v1.0.md 追加
5.2 原型图重命名	0.1h	阶段 4	v2.0.html → REQ-用户-007-...v1.0.html
5.3 MEMORY.md 变更日志同步	0.1h	阶段 4	长期记忆沉淀
5.4 通知 / 文档同步	0.1h	5.1~5.3	飞书/企微通知 + 看板更新

六、WBS 汇总表

阶段	工时	累计	关键产物
阶段 0	2.1h	2.1h	PRD + 技术方案 + 任务说明书 + 原型图 v2.3
阶段 1 前端改造	3h	5.1h	4 文件改动
阶段 2 构建	0.5h	5.6h	dist 构建产物
阶段 3 部署	0.5h	6.1h	前端 dist 部署到生产
阶段 4 E2E	1.3h	7.4h	桌面端 + 移动端 + 边界场景验证
阶段 5 收尾	0.5h	7.9h	设计文档 + 重命名 + 看板更新

总工时：约 8 小时（约 1 个工作日）

七、风险与回滚

7.1 风险清单

风险	等级	概率	缓解措施
R1：移动端 toggle 切换导致左对话状态丢失	中	中	v-show 切换（不卸载 DOM）+ 保留输入文本
R2：异常徽章实时刷新失败（WS 断连）	低	低	保留最后一次已知状态
R3：queue 标题栏紧凑导致小屏挤压	低	中	flex-wrap: wrap 应对
R4：0 异常达标动画吸引注意力过度	低	低	3 秒后渐隐
R5：dark mode 下徽章对比度不足	低	低	已在技术方案 §5.3 验证

7.2 回滚预案

触发条件（任一）：

• 桌面端 / 移动端任意核心功能（对话/诊断/排队）渲染失败
• 异常徽章未显示或显示错误数据
• 移动端 toggle 切换死循环

回滚步骤（已就绪）：

1. 前端：docker restart wecom_it_nginx（用上一版 dist）
2. 验证：curl /itdesk/ 返回 200 + 浏览器手动确认核心功能

回滚时间预算：< 10 分钟

八、关联文档

• PRD：docs/01-产品文档/05-用户端H5/PRD-REQ-用户-007-自助诊断面板优化-v1.0.md
• 技术方案：docs/02-技术文档/技术架构/技术方案-REQ-用户-007-自助诊断面板优化-v1.0.md
• 原型图：docs/01-产品文档/05-用户端H5/原型-REQ-用户-007-自助诊断面板优化-v1.0.html
• 测试用例：docs/03-测试文档/03-功能测试用例/TC-REQ-用户-007-自助诊断面板优化.md
• 现有代码：
  • src/frontend-h5/src/components/assistant/SelfDiagnosis.vue
  • src/frontend-h5/src/components/assistant/QueueWaiting.vue
  • src/frontend-h5/src/components/assistant/RightPanel.vue
  • src/frontend-h5/src/views/ChatView.vue
• 设计文档：docs/02-技术文档/前端改造/设计-H5用户端实现概览-v1.0.md

九、变更日志

版本	日期	变更内容	作者
v1.0	2026-07-29 12:40	初版：基于 PRD v1.0-Frozen + 技术方案 v1.0，给出 5 阶段 WBS（8h 总工时）+ 4 项代码交付物 + 5 类风险回滚	Duckula + 宋献