# 任务说明书 - 员工结束会话 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](../../01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.archive.md)
- **技术方案**：[技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.2.archive.md)
- **原型图**：[原型-REQ-会话-001-结束会话流程-v1.2.archive.html](../../01-产品文档/02-会话管理/原型-REQ-会话-001-结束会话流程-v1.2.archive.html)
- **历史任务说明书 #128**：[任务说明书-128-结束会话功能调整.md](任务说明书-128-结束会话功能调整.md)
- **历史技术方案（已归档）**：[技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md](../../02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md)
- **关联 BUG**：[BUG-用户-003](../../03-测试文档/05-缺陷单/BUG-用户-H5结束会话失败-003.md)（已修复 2026-07-30，v1.2 必须沿用三件套）