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