simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be361fb63783520f5dcfd7cce386ac9b5523d4f
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-用户-007-自助诊断面板优化.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

220 lines
10 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-用户-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 + 宋献 |
Reference in New Issue View Git Blame Copy Permalink