simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
35c5580c3d9634b63c22f48ad80f1b9bd55a2ca3
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

10 KiB
Raw Blame History

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