simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7864ab404bcedfa95e86e9becebbec85311d6afa
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-会话-001-员工结束会话v1.3.md
T
Simon 44e77dcb0e chore(docs): docs/ 目录全面重新编号 + 重组 
**重构前**（旧编号 02-11）：
- docs/02-产品需求/      → 00 产品规划/PRD
- docs/03-技术架构/      → 01-05 子目录散落
- docs/04-原型设计/      → 01-02 产品设计（HTML 原型）
- docs/05-原型设计/      → screens/
- docs/06-测试素材/      → 02-E2E / 03-功能 / 04-版本测试
- docs/07-项目管理/      → 任务说明书/日报/计划
- docs/08-安全审计/      → 审计报告
- docs/09-堡垒运维/      → toolbox / deploy
- docs/10-项目管理/      → 任务说明书（重复）
- docs/11-历史归档/      → deploy-nas-archived

**重构后**（新编号 00-07，语义化）：
- docs/00-产品开发流程与文档管理规范.md
- docs/00-版本迭代总览.md
- docs/01-产品文档/      （PRD/原型/认证/会话/AI 服务/坐席/集成）
- docs/02-技术文档/      （技术方案/架构图/重构记录/前端改造/实现配置）
- docs/03-测试文档/      （E2E/功能用例/版本报告/缺陷单）
- docs/04-运维文档/      （部署运维/运维指南）
- docs/05-运营文档/      （品牌推广/用户手册）
- docs/06-安全审计/      （审计报告）
- docs/07-项目管理/      （任务说明书/日报/计划/看板）

**净收益**：
- 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号）
- 消除 02-产品需求 与 10-项目管理 的编号重叠
- 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录）
- 把运维/安全/项目管理从 0X 散落改为 04/06/07

合计 494 文件 + 78495 行 / - 14076 行
2026-08-03 18:46:55 +08:00

255 lines
14 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.3（整合区方案 A：状态条 + 操作按钮 + 进度胶囊三件套）
> **版本**: v1.0 | **日期**: 2026-07-31
> **关联需求**: REQ-会话-001 v1.3
> **关联 PRD**: PRD-REQ-会话-001-员工结束会话-v1.3 §十一
> **关联技术方案**: 技术方案-REQ-会话-001-员工结束会话-v1.3 §十
> **状态**: 待开始（M8-M14）
---
## 📋 基本信息
| 项目 | 内容 |
|------|------|
| **任务名称** | 员工结束会话 v1.3 改造（整合区方案 A：状态条 + 操作按钮 + 进度胶囊三件套） |
| **任务ID** | REQ-会话-001-v1.3 |
| **优先级** | 🟠P1 |
| **类型** | 功能开发 |
| **状态** | 待开始（M8-M14 未开始；M1-M7 已完成，见 v1.2 任务说明书） |
| **负责人** | 宋献 |
| **创建日期** | 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.3.md` | **§十一 v1.3 整合区增量**（方案 A 已拍板） | 4 维度分散 → 2 段式（整合区+顶部退出）+ 5 决策落地清单 |
| `docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.md` | §3.2 §3.5 §3.7 §3.8 | v1.2 设计哲学 + 6 态按钮 + 4 种引导语 + 顶部按钮 AI 场景互斥规则（v1.3 沿用） |
### 技术方案
| 来源文档 | 相关章节 | 说明 |
|----------|----------|------|
| `docs/02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.3.md` | **§十 v1.3 整合区实施要点**（A-F 6 子节） | 组件拆分 + 文件清单 + 共享知识 + 数据结构 + 任务列表 + 待明确事项 |
| `docs/02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.2.md` | §3.3 §3.4 §3.7 §3.8 | store 新字段 + InputBar/ChatPanel 改动 + 24h 边界 + 双入口防抖（v1.3 沿用） |
### 原型设计
| 来源文档 | 页面 | 说明 |
|----------|------|------|
| `docs/01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.3.html` | **§⑨ 方案 A 整合区设计（v1.3 已拍板）** | 9 场景 mockup + 5 决策落地 + R1-R5 关键交互细节 |
| `docs/01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.2.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 待开始（2026-07-31 拍板）
- [ ] M8：新建 `shiftHours.ts` 工具常量（`SHIFT_HOURS = '9:00-18:00'`）
- [ ] M9：新建 `IntegrationZone.vue` 容器组件（5 元素纵向堆叠）
- [ ] 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 待产出
- [ ] 代码已提交并通过 Code Review（M8-M13）
- [ ] 单元测试新增/修复完成（覆盖整合区 9 场景 + store.shiftHours 单测）
- [ ] 集成测试通过
- [ ] 部署验证通过
- [ ] 文档更新已完成（本任务说明书 v1.3 + 整改记录 #8）
---
## 📊 工作分解（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 待开始阶段（2026-07-31 拍板，整合区方案 A 实施）
| 阶段 | 任务 | 预估工时 | 依赖 | 状态 |
|------|------|----------|------|------|
| **M8** | 新建 `shiftHours.ts` 工具常量（`SHIFT_HOURS = '9:00-18:00'`，v1.4 接 store.shiftHours） | 0.1d | — | ⏳ 待开始 |
| **M9** | 新建 `IntegrationZone.vue` 容器组件（5 元素纵向堆叠 + 浅灰背景 + 状态条三态文案） | 0.5d | — | ⏳ 待开始 |
| **M10** | 新建 `integrationZone.ts` 状态 store | 0.3d | — | ⏳ 待开始 |
| **M11** | 改造 `InputBar.vue` 移除操作按钮 + 移除引导语容器（工具栏更简洁：😊📎[输入框][发送]） | 0.3d | M8 | ⏳ 待开始 |
| **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.5d** | | |
| | **v1.2 + v1.3 合计** | **7.0 天** | | |
---
## 📞 依赖与阻塞
### 前置依赖
| 依赖任务 | 依赖说明 | 状态 |
|----------|----------|------|
| 任务说明书 #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 |
---
## 📎 附件
### v1.3 主线文档
- **产品需求（v1.3）**：[PRD-REQ-会话-001-员工结束会话-v1.3.md](../../01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.3.md) **§十一 v1.3 整合区增量**
- **技术方案（v1.3）**：[技术方案-REQ-会话-001-员工结束会话-v1.3.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.3.md) **§十 v1.3 整合区实施要点**
- **原型图（v1.3）**：[原型-REQ-会话-001-结束会话流程-v1.3.html](../../01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.3.html) **§⑨ 方案 A 整合区设计**
### v1.2 基线文档（已上线，M1-M7 已完成）
- **产品需求（v1.2）**：[PRD-REQ-会话-001-员工结束会话-v1.2.md](../../01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.md)
- **技术方案（v1.2）**：[技术方案-REQ-会话-001-员工结束会话-v1.2.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.2.md)
- **原型图（v1.2）**：[原型-REQ-会话-001-结束会话流程-v1.2.html](../../01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.2.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