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-会话-001-员工结束会话v1.4.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

256 lines
15 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.
# 任务说明书 - 员工结束会话 v1.4（整合区方案 A：操作按钮 + 进度胶囊 + 引导语三元素，状态条已删除）
> **版本**: v1.4 | **日期**: 2026-08-03
> **关联需求**: REQ-会话-001 v1.4
> **关联 PRD**: PRD-REQ-会话-001-员工结束会话-v1.4 §十一
> **关联技术方案**: 技术方案-REQ-会话-001-员工结束会话-v1.4 §十
> **状态**: 待开始（M8-M14，其中 M8 shiftHours 已随 v1.4 状态条删除取消）
---
## 📋 基本信息
| 项目 | 内容 |
|------|------|
| **任务名称** | 员工结束会话 v1.4 改造（整合区方案 A：操作按钮 + 进度胶囊 + 引导语三元素，状态条 v1.4 删除） |
| **任务ID** | REQ-会话-001-v1.4 |
| **优先级** | 🟠P1 |
| **类型** | 功能开发 |
| **状态** | 待开始（M8-M14 未开始；M1-M7 已完成，见 v1.2 任务说明书；M8 shiftHours 因 v1.4 删除状态条已取消） |
| **负责人** | 宋献 |
| **创建日期** | 2026-07-31 |
| **计划完成日期** | 2026-08-06（M8-M14 共 2.5 天开发+测试工时） |
| **基线版本** | v1.2 任务说明书（2026-07-30 已完成 7 阶段 M1-M7 实施上线） |
| **关联任务** | 任务说明书 #128（v1.0 结束会话功能调整，2026-07-27 已完成） |
---
## 📥 输入项来源
### 产品需求
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.4.md` | **§十一 v1.3/v1.4 整合区增量**（方案 A 已拍板；v1.4 反转删除状态条） | 4 维度分散 → 2 段式（整合区+顶部退出）+ 5 决策落地清单；v1.4 整合区降为三元素 |
| `docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.archive.md` | §3.2 §3.5 §3.7 §3.8 | v1.2 设计哲学 + 6 态按钮 + 4 种引导语 + 顶部按钮 AI 场景互斥规则（v1.3 沿用） |
### 技术方案
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `docs/02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.4.md` | **§十 v1.3/v1.4 整合区实施要点**（A-F 6 子节；v1.4 反转删除状态条） | 组件拆分 + 文件清单（v1.4 移除 shiftHours.ts）+ 共享知识 + 数据结构 + 任务列表 + 待明确事项 |
| `docs/02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md` | §3.3 §3.4 §3.7 §3.8 | store 新字段 + InputBar/ChatPanel 改动 + 24h 边界 + 双入口防抖（v1.3 沿用） |
### 原型设计
| 来源文档 | 页面 | 说明 |
|----------|------|------|
| `docs/01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.4.html` | **§⑨ 方案 A 整合区设计（v1.3 已拍板 · v1.4 删除状态条）** | 9 场景 mockup + 6 决策落地（含 v1.4 状态条反转）+ R1-R5 关键交互细节 |
| `docs/01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.2.archive.html` | §② §③ §④ | 6 态按钮 + 4 种引导语 + 顶部按钮可见性 mockup（v1.3 沿用） |
### 需了解的现有代码（v1.2 实施时必读）
| 模块/文件 | 说明 | 需了解的内容 |
|-----------|------|-------------|
| `src/frontend-h5/src/components/chat/InputBar.vue:194-243` | 人工坐席按钮 5 态逻辑 | v1.2 改造为 6 态（移除 hidden / 恢复 end / 新增 reopen）+ 4 种引导语 |
| `src/frontend-h5/src/components/chat/ChatPanel.vue:21-28` | 标题栏坐席状态徽章 | 沿用，v1.2 不变 |
| `src/frontend-h5/src/components/chat/ChatPanel.vue:59-65` | 顶部退出按钮 | v1.2 加 `v-show="store.showHeaderExitBtn"` + tooltip 文案 |
| `src/frontend-h5/src/stores/conversation.ts:1800-1814` | "会话已关闭"消息文本 | 沿用为视觉样式参照 |
| `src/frontend-h5/src/api/closing.ts:119` | reopenConversation API | v1.2 直接复用 |
| `src/frontend-h5/src/composables/useH5WebSocket.ts:460` | queue_position_update WS 事件 | 沿用为排队胶囊数据源 |
### 历史背景
- 2026-07-12：`InputBar.vue` 重构，按钮改为垂直堆叠
- 2026-07-25：BUG-用户-001 修复 — 坐席离线时按钮禁用
- 2026-07-27：BUG-用户-002 修复 — InputBar 移除 "结束咨询" 按钮态，统一由标题栏 chat-panel__exit-btn 触发（v1.0 PRD 与代码不一致起点）
- 2026-07-30：BUG-用户-003 修复 — ChatPanel.vue:403 handleExitWithEvaluation 三件套（防抖 + 同步 store + try/finally 重置），v1.2 必须沿用
---
## 📤 输出成果要求
### 交付物清单
| # | 交付物 | 类型 | 说明 |
|---|--------|------|------|
| 1 | `stores/conversation.ts` 新增 3 字段 | 代码 | `showHeaderExitBtn` + `canReopen` + `reopenCurrentConversation` action |
| 2 | `InputBar.vue` 6 态扩展 | 代码 | 移除 hidden / 恢复 end / 新增 reopen + 4 种引导语渲染 |
| 3 | `ChatPanel.vue` 顶部按钮 v-show | 代码 | 绑定 `store.showHeaderExitBtn` + tooltip/弹窗文案修订 |
| 4 | `InputBar.vue` 新增样式 | 代码 | `.call-agent-btn--end`（红色填充）+ `.call-agent-btn--reopen`（蓝色填充） |
| 5 | 单元测试 | 测试 | 状态机 9 场景 + `showHeaderExitBtn` 9 场景 + `canReopen` 边界 |
### 代码要求
- 遵循项目代码规范（参考现有 InputBar.vue / ChatPanel.vue 注释风格）
- 所有新增代码通过 ESLint 检查
- 单元测试覆盖率 ≥ 80%（参考 PRD §五 验收指标 AC1-AC11）
- **重点**：沿用 BUG-用户-003 修复样本，end 态按钮的 async handler 必须三件套（防抖 + 同步 store + try/finally 重置）
- catch 兜底优先显示后端真实 message
### 文档要求
- 本任务说明书状态在每个阶段完成后更新（待开始 → 进行中 → 已完成）
- 实施完成后追加到 `00-文档规范化整改记录.md`（整改 #7）
---
## 🔧 验证方式
### 功能验证
| 验证项 | 验证方法 | 预期结果 |
|--------|----------|----------|
| 6 态按钮正确切换 | 手动遍历 9 种场景（无会话/AI<3轮/AI≥3轮/紧急/离线/排队/服务中/24h内关闭/>24h关闭） | 每种场景显示对应按钮态和引导语 |
| 顶部按钮仅 AI 场景显示 | 切换 waiting/serving 状态 | 顶部按钮自动隐藏，操作按钮 end 态接管 |
| 重新打开按钮 | 会话关闭后立即点击 | 触发 reopen API，按钮态切回 active |
| 24h 边界 | 修改 `resolved_at` 时间戳或后端 mock | 24h 内显示 reopen，>24h 显示 disabled + "已过期"引导语 |
| 双入口互斥 | 服务中状态点击顶部按钮（应隐藏） | 无响应，提示无此元素 |
| 引导语与按钮态同步 | 快速切换场景 | 引导语文本与按钮态 100% 同步，无错位 |
### 安全验证
| 验证项 | 验证方法 | 预期结果 |
|--------|----------|----------|
| reopen 24h 绕过 | 前端改时间戳 | 后端 reopen API 拒绝，返回错误码 |
| end 态并发点击 | 服务中状态快速双击"结束咨询" | 仅触发一次 close（isExiting 防抖） |
| WS 断连场景 | 关闭 WS 连接 | 按钮态回退合理（不卡死） |
### 性能验证
| 验证项 | 验证方法 | 预期结果 |
|--------|----------|----------|
| 状态切换响应 | 切换 waiting → serving | < 100ms |
| 引导语渲染 | 切到 disabled 态 | < 50ms 渲染完成 |
---
## ✅ 完成标准
### 验收条件
#### v1.2 已完成（2026-07-30 上线）
- [x] M1：PRD v1.2 评审通过
- [x] M2：store 新字段实现 + 单元测试通过
- [x] M3：InputBar 6 态扩展 + 引导语 + end/reopen 样式实现
- [x] M4：ChatPanel 顶部按钮 v-show + 文案修订
- [x] M5：重新打开按钮 + 24h 边界逻辑
- [x] M6：联调测试 + 视觉回归通过
- [x] M7：上线后监控无异常（按钮点击转化率与历史持平，无 1001 错误）
#### v1.3/v1.4 待开始（2026-07-31 拍板 · 2026-08-03 v1.4 反转删除状态条）
- [ ] M8：~~新建 `shiftHours.ts` 工具常量~~ **（v1.4 取消：状态条已删除，不再需要班次硬编码常量；`store.shiftHours` 预留后端班次字段，当前无渲染）**
- [ ] M9：新建 `IntegrationZone.vue` 容器组件（v1.3 规划 5 元素 → **v1.4 降为三元素**：操作按钮 + 进度胶囊 + 引导语，状态条移除）
- [ ] M10：新建 `integrationZone.ts` 状态 store
- [ ] M11：改造 `InputBar.vue` 移除操作按钮 + 移除引导语容器
- [ ] M12：改造 `ChatPanel.vue` 移除坐席徽章 + 集成 IntegrationZone
- [ ] M13：改造 `QueueCapsule.vue` 集成到 IntegrationZone
- [ ] M14：联调测试 + 视觉回归 + 部署 prod（按钮态回归 9 场景 + 整合区 mockup 视觉对比）
### 产出确认
#### v1.2 已完成（2026-07-30 上线）
- [x] 代码已提交并通过 Code Review
- [x] 单元测试新增/修复完成（覆盖 9 场景）
- [x] 集成测试通过
- [x] 部署验证通过
- [x] 文档更新已完成（任务说明书 v1.2 + 整改记录 #7）
#### v1.3/v1.4 待产出
- [ ] 代码已提交并通过 Code Review（M9-M13；M8 因 v1.4 状态条删除取消）
- [ ] 单元测试新增/修复完成（覆盖整合区 9 场景；v1.4 移除 store.shiftHours 单测）
- [ ] 集成测试通过
- [ ] 部署验证通过
- [ ] 文档更新已完成（本任务说明书 v1.4 + 整改记录 #10）
---
## 📊 工作分解（v1.2 M1-M7 已完成 + v1.3 M8-M14 待开始）
> 来源：PRD v1.3 §十一 + 技术方案 v1.3 §十 任务列表
### v1.2 已完成阶段（2026-07-30 上线，详见任务说明书 v1.2）
| 阶段 | 任务 | 预估工时 | 状态 |
|------|------|----------|------|
| **M1** | PRD v1.2 评审 | 0.5 天 | ✅ 已完成 |
| **M2** | store 新增 `showHeaderExitBtn` + `canReopen` + `reopenCurrentConversation` + 单元测试 | 1h | ✅ 已完成 |
| **M3** | InputBar 改造：hidden → disabled + 6 态扩展 + 4 种引导语 + end/reopen 样式 | 1 天 | ✅ 已完成 |
| **M4** | ChatPanel 改造：顶部按钮 v-show 绑定 showHeaderExitBtn + 文案修订 + end-conversation 处理 | 0.5 天 | ✅ 已完成 |
| **M5** | 重新打开按钮 + 24h 边界逻辑 | 0.5 天 | ✅ 已完成 |
| **M6** | 联调测试 + 视觉回归 | 1 天 | ✅ 已完成 |
| **M7** | 上线 | 0.5 天 | ✅ 已完成 |
| | **小计** | **4.5 天** | |
### v1.3/v1.4 待开始阶段（2026-07-31 拍板 · 2026-08-03 v1.4 反转删除状态条）
| 阶段 | 任务 | 预估工时 | 依赖 | 状态 |
|------|------|----------|------|------|
| **M8** | ~~新建 `shiftHours.ts` 工具常量~~ **（v1.4 取消：状态条删除，不再需要班次硬编码常量）** | 0d | — | ❌ 已取消 |
| **M9** | 新建 `IntegrationZone.vue` 容器组件（v1.4 三元素纵向堆叠 + 浅灰背景：**移除状态条三态文案**） | 0.5d | — | ⏳ 待开始 |
| **M10** | 新建 `integrationZone.ts` 状态 store | 0.3d | — | ⏳ 待开始 |
| **M11** | 改造 `InputBar.vue` 移除操作按钮 + 移除引导语容器（工具栏更简洁：😊📎[输入框][发送]） | 0.3d | — | ⏳ 待开始 |
| **M12** | 改造 `ChatPanel.vue` 移除坐席徽章 + 集成 IntegrationZone | 0.5d | M9, M10 | ⏳ 待开始 |
| **M13** | 改造 `QueueCapsule.vue` 集成到 IntegrationZone 内部 | 0.3d | M9 | ⏳ 待开始 |
| **M14** | 联调测试 + 视觉回归 + 部署 prod（按钮态回归 9 场景 + 整合区 mockup 视觉对比） | 0.5d | M11, M12, M13 | ⏳ 待开始 |
| | **小计** | **2.4d** | | |
| | **v1.2 + v1.4 合计** | **6.9 天** | | |
---
## 📞 依赖与阻塞
### 前置依赖
| 依赖任务 | 依赖说明 | 状态 |
|----------|----------|------|
| 任务说明书 #128 | v1.0 结束会话功能调整（已完成 2026-07-27） | ✅ 已完成 |
| 任务说明书-集成-002 | IA 重构（不冲突，但需协调 H5 端资源） | 🟡 进行中 |
| 后端 reopen API 确认 | `conv.resolved_at` 字段返回 | ⏳ 待确认 |
| 后端 close reason 区分 | 顶部退出 vs 操作按钮 end 是否需要不同 reason | ⏳ 待确认 |
### 阻塞因素
| 阻塞项 | 影响范围 | 解决方案 |
|--------|----------|----------|
| 无明显阻塞 | - | - |
---
## 📈 变更记录
| 日期 | 变更内容 | 变更人 | 说明 |
|------|----------|--------|------|
| 2026-07-30 | 创建任务说明书 v1.0 | Duckula (AI) | 覆盖 PRD v1.2 + 技术方案 v1.2 的 7 阶段实施计划；按 product-doc-standard 规范要求补建任务说明书 |
| 2026-07-31 | 创建任务说明书 v1.0（v1.3 整合区方案 A） | Duckula (AI) | 基于 v1.2 任务说明书扩展：保留 M1-M7 已完成阶段，新增 M8-M14 待开始阶段（整合区实施）；基线版本 v1.2 → v1.3；新增引用 PRD v1.3 §十一 + 技术方案 v1.3 §十 + 原型 v1.3 §⑨；预计完成日期 2026-08-06 |
| 2026-08-03 | 升级任务说明书 v1.3 → v1.4 | Duckula (AI) | 闭环整改 #9 遗留分歧：以 v1.3.5 代码为准删除整合区状态条；引用 PRD/技术方案/原型升级为 v1.4；M8 shiftHours 标记取消、M9 降为三元素、M11 依赖改为无；小计 2.5d→2.4d；关联整改记录 #10 |
---
## 📎 附件
### v1.4 主线文档
- **产品需求（v1.4）**：[PRD-REQ-会话-001-员工结束会话-v1.4.md](../../01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.4.md) **§十一 v1.3/v1.4 整合区增量（v1.4 反转删除状态条）**
- **技术方案（v1.4）**：[技术方案-REQ-会话-001-员工结束会话-v1.4.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.4.md) **§十 v1.3/v1.4 整合区实施要点**
- **原型图（v1.4）**：[原型-REQ-会话-001-结束会话流程-v1.4.html](../../01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.4.html) **§⑨ 方案 A 整合区设计（v1.4 删除状态条）**
### v1.2 基线文档（已上线，M1-M7 已完成）
- **产品需求（v1.2）**：[PRD-REQ-会话-001-员工结束会话-v1.2.archive.md](../../01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.archive.md)
- **技术方案（v1.2）**：[技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md)
- **原型图（v1.2）**：[原型-REQ-会话-001-结束会话流程-v1.2.archive.html](../../01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.2.archive.html)
- **任务说明书（v1.2）**：[任务说明书-REQ-会话-001-员工结束会话v1.2.md](任务说明书-REQ-会话-001-员工结束会话v1.2.md)
### 历史归档
- **历史任务说明书 #128**：[任务说明书-128-结束会话功能调整.md](任务说明书-128-结束会话功能调整.md)
- **历史技术方案（已归档）**：[技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md)
### 关联 BUG
- **关联 BUG**：[BUG-用户-003](../../03-测试文档/05-缺陷单/BUG-用户-H5结束会话失败-003.md)（已修复 2026-07-30，v1.2 + v1.3 必须沿用三件套）
Reference in New Issue View Git Blame Copy Permalink