Simon
a8da4da0db
REQ-会话-001 员工结束会话: - PRD/原型 v1.0/v1.1/v1.2 归档为 .archive，现行收敛至单一 v1.3 - 技术方案 v1.2 归档，v1.3 为现行版本(位于 docs/02-技术文档/) - PRD v1.3 §六 关联文档表指向 v1.3 原型与技术方案实际路径 - 三份任务说明书 + BUG-003 + TC-用户-008 引用同步至 .archive/v1.3 REQ-用户-005 头像菜单退出: - PRD/原型/技术方案文件名 v1.0 -> v1.1，追平内容版本(铁律2) - 三件套 + 任务说明书 + TC 互引版本对齐，相关 PRD 指向会话-001 v1.3 其他: - 修复 4 处 UTF-8 乱码(U+FFFD) - 新增 TR-会话-001-结束会话-v1.3.2 端到端测试报告(单测 75/75 + 生产构建通过) - 整改记录 #9 写入 00-文档规范化整改记录.md 遗留: PRD v1.3「状态条永久显示」与代码 v1.3.5「状态条已删除」存在分歧，待产品拍板
9.1 KiB
9.1 KiB
任务说明书 - 员工结束会话 v1.2（按钮 6 态 + 引导语 + 顶部按钮 AI 场景互斥）
版本: v1.0 | 日期: 2026-07-30 关联需求: REQ-会话-001 v1.2 状态: 待开始
📋 基本信息
| 项目 | 内容 |
|---|---|
| 任务名称 | 员工结束会话 v1.2 改造 |
| 任务ID | REQ-会话-001-v1.2 |
| 优先级 | 🟠P1 |
| 类型 | 功能开发 |
| 状态 | 待开始 |
| 负责人 | 宋献 |
| 创建日期 | 2026-07-30 |
| 计划完成日期 | 2026-08-04（M1+M7 共 0.5+0.5 = 1 天评审/上线工时） |
| 关联任务 | 任务说明书 #128（v1.0 结束会话功能调整，2026-07-27 已完成） |
📥 输入项来源
产品需求
| 来源文档 | 相关章节 | 说明 |
|---|---|---|
docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.archive.md |
§3.2 §3.5 §3.7 §3.8 | v1.2 设计哲学 + 6 态按钮 + 4 种引导语 + 顶部按钮 AI 场景互斥规则 |
技术方案
| 来源文档 | 相关章节 | 说明 |
|---|---|---|
docs/02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md |
§3.3 §3.4 §3.7 §3.8 | store 新字段 + InputBar/ChatPanel 改动 + 24h 边界 + 双入口防抖 |
原型设计
| 来源文档 | 页面 | 说明 |
|---|---|---|
docs/01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.2.archive.html |
§② §③ §④ | 6 态按钮 + 4 种引导语 + 顶部按钮可见性 mockup |
需了解的现有代码（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 渲染完成 |
✅ 完成标准
验收条件
- M1：PRD v1.2 评审通过
- M2：store 新字段实现 + 单元测试通过
- M3：InputBar 6 态扩展 + 引导语 + end/reopen 样式实现
- M4：ChatPanel 顶部按钮 v-show + 文案修订
- M5：重新打开按钮 + 24h 边界逻辑
- M6：联调测试 + 视觉回归通过
- M7：上线后监控无异常（按钮点击转化率与历史持平，无 1001 错误）
产出确认
- 代码已提交并通过 Code Review
- 单元测试新增/修复完成（覆盖 9 场景）
- 集成测试通过
- 部署验证通过
- 文档更新已完成（本任务说明书 + 整改记录 #7）
📊 工作分解（7 阶段实施计划）
来源：PRD v1.2 §七 里程碑，技术方案 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 天 |
📞 依赖与阻塞
前置依赖
| 依赖任务 | 依赖说明 | 状态 |
|---|---|---|
| 任务说明书 #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 规范要求补建任务说明书 |
📎 附件
- 产品需求：PRD-REQ-会话-001-员工结束会话-v1.2.archive.md
- 技术方案：技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md
- 原型图：原型-REQ-会话-001-结束会话流程-v1.2.archive.html
- 历史任务说明书 #128：任务说明书-128-结束会话功能调整.md
- 历史技术方案（已归档）：技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md
- 关联 BUG：BUG-用户-003（已修复 2026-07-30，v1.2 必须沿用三件套）