simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
f2fd4fa0127bb0620886f4c9d2304f46501eedab
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-会话-001-员工结束会话v1.2.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

195 lines
9.1 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.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 必须沿用三件套）
Reference in New Issue View Git Blame Copy Permalink