wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-会话-001-员工结束会话v1.3.md

任务说明书 - 员工结束会话 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 上线）

• M1：PRD v1.2 评审通过
• M2：store 新字段实现 + 单元测试通过
• M3：InputBar 6 态扩展 + 引导语 + end/reopen 样式实现
• M4：ChatPanel 顶部按钮 v-show + 文案修订
• M5：重新打开按钮 + 24h 边界逻辑
• M6：联调测试 + 视觉回归通过
• 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 上线）

• 代码已提交并通过 Code Review
• 单元测试新增/修复完成（覆盖 9 场景）
• 集成测试通过
• 部署验证通过
• 文档更新已完成（任务说明书 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 §十一 v1.3 整合区增量
• 技术方案（v1.3）：技术方案-REQ-会话-001-员工结束会话-v1.3.md §十 v1.3 整合区实施要点
• 原型图（v1.3）：原型-REQ-会话-001-结束会话流程-v1.3.html §⑨ 方案 A 整合区设计

v1.2 基线文档（已上线，M1-M7 已完成）

• 产品需求（v1.2）：PRD-REQ-会话-001-员工结束会话-v1.2.md
• 技术方案（v1.2）：技术方案-REQ-会话-001-员工结束会话-v1.2.md
• 原型图（v1.2）：原型-REQ-会话-001-结束会话流程-v1.2.html
• 任务说明书（v1.2）：任务说明书-REQ-会话-001-员工结束会话v1.2.md

历史归档

• 历史任务说明书 #128：任务说明书-128-结束会话功能调整.md
• 历史技术方案（已归档）：技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md

关联 BUG

• 关联 BUG：BUG-用户-003（已修复 2026-07-30，v1.2 + v1.3 必须沿用三件套）