wecom_it_smart_desk/docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.1.archive.md

# 员工结束会话 PRD

> **版本**: v1.1
> **日期**: 2026-07-30
> **REQ编号**: REQ-会话-001
> **优先级**: P1
> **阶段**: 近期
> **状态**: 待评审（v1.1 调整稿）
> **基线版本**: v1.0（2026-07-24）

---

## 一、需求概述

### 1.1 需求背景

**v1.0 背景**（延续）：
1. 用户无法主动结束会话，若要结束错误对话历史（如 AI 回答错误），只能开启新会话
2. 人工咨询场景缺少员工主动结束的入口
3. 满意度评价仅在 AI 判定问题已解决时触发，无法覆盖所有会话场景

**v1.1 新增背景**：
1. **AI 能力演进**：短期 AI 咨询无法取代人工（高频刚需：VPN、密码、紧急断网等），但长期 AI 咨询将逐步取代人工常规工作内容。设计需兼顾"现在好用"和"未来演进"。
2. **按钮维度过载**：v1.0 把"服务可用性"（坐席离线/繁忙）和"会话进程"（呼叫/排队/结束）合并到同一按钮，导致 5 种状态文案切换，老人找错功能。
3. **右栏信息冗余**：右栏底部"排队等待标签" + "答题挑战"占视觉位且非核心路径，桌面端右栏过度堆砌，移动端（<500px）又根本不渲染右栏。
4. **2026-07-27 实现变更**：InputBar 已实际采用 5 态合并按钮（hidden/disabled/active/urgent/waiting），并移除"结束咨询"按钮态，统一由头像右边红色按钮触发满意度评价。PRD 需与实现对齐。

### 1.2 需求目标

| 目标 | 说明 | 状态 |
|------|------|------|
| G1 | 员工可主动结束当前会话 | 延续 v1.0 ✅ |
| G2 | 结束会话时强制收集满意度评价 | 延续 v1.0 ✅ |
| G3 | 操作按钮承载"会话进程"（呼叫-排队） | v1.1 调整 ✏️ |
| G4 | 服务可用性（坐席是否在线）在显眼位置可见 | v1.1 新增 🆕 |
| G5 | 排队进度反馈靠近底部、不污染对话流 | v1.1 新增 🆕 |
| G6 | 右栏聚焦核心：设备诊断 + 智能推荐 | v1.1 新增 🆕 |

---

## 二、用户故事

| # | 角色 | 用户故事 | 优先级 |
|---|------|----------|--------|
| US-1 | 员工 | 作为员工，我希望在会话结束时能主动关闭会话，以便开始新会话获取正确回答 | P0 |
| US-2 | 员工 | 作为员工，我希望结束会话时能评价本次服务，以便反馈服务质量 | P0 |
| US-3 | 员工 | 作为员工，我希望一眼看到坐席是否在线，以便判断"AI 答不出时能否转人工" | P1 🆕 |
| US-4 | 员工 | 作为员工，我希望排队时能看到进度（前面几个人、还要多久），以便降低焦虑 | P1 🆕 |

---

## 三、功能详情

### 3.1 设计哲学：维度分离

**核心思想**：把 5 个状态按性质拆成两个独立维度，每个维度用最合适的 UI 形式呈现。

| 维度 | 性质 | UI 形式 | 位置 |
|---|---|---|---|
| **A. 服务可用性** | 系统状态（坐席/排班决定） | 标题栏徽章 | 顶部，永远可见 |
| **B. 会话进程** | 用户动作（员工点击决定） | 操作按钮 5 态切换 | 输入栏上方 |
| **C. 排队进度** | 实时反馈（WS 推送） | 底部消息胶囊 | 输入框上方，锚定底部 |

**为什么这样拆**：
- 服务可用性是"系统告诉员工能不能叫到人" → 不该占用操作按钮位
- 会话进程是"员工告诉系统想干什么" → 操作按钮正确
- 排队进度是"系统实时反馈" → 既不能丢（员工焦虑），又不能污染对话流（影响 AI 上下文）

### 3.2 操作按钮状态机（v1.1 与实现对齐）

**位置**：输入栏控件区第一层（独占一行），与发送按钮上下相邻

**5 态定义**（与 InputBar.vue:194-243 实现完全一致）：

| 状态 | 触发条件 | 按钮文案 | 按钮图标 | 样式 | 可点击 |
|------|---------|---------|---------|------|--------|
| **hidden** | 无会话 / 会话已关闭 | （不显示） | — | — | — |
| **disabled** | 坐席离线（!store.agentOnline） | 人工坐席 | 🔒 | 灰色禁用 | ❌ |
| **waiting** | 排队中（conv.status === 'waiting'） | 排队等待 | ⏳ | 橙色描边 | ✅（点击取消） |
| **active** | AI 回复 ≥ 3 次 / 无紧急词 | 人工坐席 | 🎧 | 绿色描边 | ✅ |
| **urgent** | 检测到紧急关键词 | 人工坐席 | 🚨 | 红色脉冲 | ✅ |

**2026-07-27 变更说明**：
- 移除 v1.0 PRD 中的"结束咨询"按钮态
- 服务中（坐席已接入）不再通过按钮触发结束，统一由头像右边红色按钮（`chat-panel__exit-btn`）触发
- 这样按钮语义更聚焦：**只承担"呼叫"和"取消排队"两个动作**

**优先级顺序**（代码行 214）：
```
hidden > waiting > active/urgent > disabled
```

### 3.3 服务可用性指示（v1.1 新增 / G4）

**位置**：标题栏左上角，与"IT 智能服务"标题相邻

**当前实现**（ChatPanel.vue:21-28）：
```
[IT] 智能IT服务 · 🟢 坐席在线
[IT] 智能IT服务 · ⚫ 坐席离线
```

**v1.1 增强要求**：
- 永远显示，不随页面滚动消失
- 颜色区分：在线 = 绿色圆点（`chat-panel__status--online`），离线 = 灰色圆点（`chat-panel__status--offline`）
- 后续 v1.2 可扩展为"在线 / 繁忙 / 离线"三态（增加预计等待时长）

### 3.4 排队进度消息胶囊（v1.1 新增 / G5）

**核心思想**：参考"会话已关闭"系统消息（conversation.ts:1800-1814 的 `getResolveMessageText`）的视觉样式，但**视觉锚定到对话区底部**（输入框上方），不随对话流向上滚动消失。

**位置**：
```
┌──────────────────────────────┐
│   (主对话流消息列表)         │ ← 正常消息流
│                              │
│                              │
│                              │
├──────────────────────────────┤
│  ⏳ 排队中 · 前面 3 人 · 1:32 │ ← 排队进度胶囊（sticky bottom）
├──────────────────────────────┤
│  😊 📎 [输入框]   🎤 [发送]  │ ← 输入栏
└──────────────────────────────┘
```

**状态映射**：

| 排队状态 | 胶囊文案 | 颜色 |
|---------|---------|------|
| 未排队 | （不显示胶囊） | — |
| 排队中 | `⏳ 排队中 · 前面 N 人 · 预计 MM:SS` | 橙色 |
| 已接入 | `🟢 已接入 · 客服小王` | 绿色，3 秒后淡出 |

**更新机制**：
- 仅在**关键节点**触发胶囊内容更新，不每次位置变化都重渲染
- 关键节点：进入排队、每跳 3 位（如 5 → 2 → 1）、接听
- 普通位置变化由胶囊内的数字自动平滑过渡（CSS transition）

**与对话流的关系**：
- ❌ **不作为消息插入对话历史**（避免污染 AI 上下文与推荐系统）
- ✅ 作为独立 UI 元素渲染，DOM 位置在 `chat-panel__messages` 与 `InputBar` 之间
- ✅ 类似 "会话已关闭"消息的视觉样式，但**位置上移到对话流底部区域**

### 3.5 右栏简化（v1.1 新增 / G6）

**删除**：
- 右栏底部整段 `right-panel__queue-section`（含标题栏、QueueWaiting 组件、答题挑战）
- 连带的 `__divider` 分隔线
- WebSocket 中 `queue_position_update` 事件回调（改由底部胶囊消费）
- `api/queue` + `api/quiz` 两个 API 模块
- `useConversationStore` 中 `queuePositionData` / `cancelQueue` / `handleQueuePositionUpdate`
- `ChatPanel.vue` 中 `handleCancelQueue` 流程（改为按钮直接 emit 到 store）

**保留**（桌面端右栏最终结构）：
```
┌─ 右栏 ─────────────────────┐
│ ▼ 设备信息（默认折叠）       │ 保留
│ ▼ 自助诊断（异常徽章）       │ 保留
├─────────────────────────────┤
│ ⚡ 智能推荐卡片              │ 保留
├─────────────────────────────┤
│                             │
│ （空，剩余滚动空间）          │
│                             │
└─────────────────────────────┘
```

**移动端**：<500px 默认不渲染右栏，无变化。

### 3.6 结束会话流程（延续 v1.0，对齐 2026-07-27 变更）

**触发方式**：点击标题栏右侧红色退出按钮（`chat-panel__exit-btn`，SVG 退出图标）

**流程**：
```
点击"结束会话"红色按钮
    ↓
弹出确认对话框："退出后会话记录会清空，当前咨询进度将丢失"
    ↓ 确认
调用后端 employeeClose API → 会话状态变为 resolved
    ↓
前端同步 store 状态为 resolved（防止 WS 延迟）
    ↓
弹出满意度评价组件（EvaluationDialog）
    ↓
用户提交评价（必填）
    ↓
评价提交成功 → 关闭窗口 / 跳转登录页
```

**技术要点**：
- 必须同步更新前端 store（防 BUG-用户-003 重现，参见 ChatPanel.vue:438-444 的修复）
- axios 拦截器先弹 `res.message`，ChatPanel catch 兜底再显示一次（双重错误信息）
- 三层降级关闭窗口：WeixinJSBridge → window.close() → 跳转 /h5/login

---

## 四、非目标

| # | 明确不做 |
|---|----------|
| N1 | 不修改人工呼叫的后端逻辑（仅前端 UI 与状态管理调整） |
| N2 | 不区分 AI 会话与人工会话的结束流程 |
| N3 | 不支持跳过评价直接关闭（必须评价） |
| N4 | **不做 AI 意图识别"叫人工"功能**（v1.2 路线图，本期不实现） |
| N5 | **不做答题挑战 / 插队机制**（v1.1 移除，保留代码可未来恢复） |
| N6 | **不做"在线/繁忙/离线"三态服务可用性**（v1.2 路线图，本期仅在线/离线二态） |

---

## 五、验收指标

| # | 指标 | 目标值 | 验收方式 |
|---|------|--------|---------|
| AC1 | 员工可主动结束会话 | 100% | 点击"结束会话"红色按钮可触发关闭流程 |
| AC2 | 评价提交率 | =100% | 关闭会话前必须提交评价 |
| AC3 | 操作按钮状态切换正确 | 5 种状态正确切换 | 人工呼叫全流程测试 |
| AC4 | 服务可用性永远可见 | 标题栏徽章在所有页面状态可见 | 滚动 + 弹窗场景测试 |
| AC5 | 排队进度胶囊准确显示 | 排队时显示位置/时间，接听后淡出 | WS 推送全链路测试 |
| AC6 | 右栏底部 queue section 完全移除 | 桌面端右栏只含 2 大区块 | 构建产物 + 视觉回归 |
| AC7 | 不污染对话流 | 排队进度不进入 store.messages | store 检查 + AI 推荐效果对比 |

---

## 六、关联文档

| 文档 | 说明 |
|------|------|
| `前端组件-InputBar.vue` | 操作按钮 5 态实现（hidden/disabled/active/urgent/waiting） |
| `前端组件-ChatPanel.vue` | 标题栏坐席状态徽章 + 结束会话流程 |
| `前端组件-ResolveFeedback.vue` / `EvaluationDialog.vue` | 满意度评价组件 |
| `前端组件-RightPanel.vue` | 右栏（v1.1 移除 queue section） |
| `前端组件-QueueWaiting.vue` | 右栏排队组件（v1.1 标记弃用，保留文件） |
| `API-h5.py` | 关闭会话 API |
| `PRD-REQ-集成-002-邀请功能` | 会话管理系列功能 |
| `原型-REQ-会话-001-结束会话流程-v1.1.html` | v1.1 原型图（重绘） |

---

## 七、里程碑

| 阶段 | 任务 | 预计时间 |
|------|------|---------|
| M1 | PRD v1.1 评审 | 0.5 天 |
| M2 | 移除右栏 queue section | 0.5 天 |
| M3 | 实现底部进度消息胶囊 | 1 天 |
| M4 | 操作按钮文案与样式微调 | 0.5 天 |
| M5 | 联调测试 + 回归 | 1 天 |
| M6 | 上线 | 0.5 天 |
| **合计** | | **4 天** |

---

## 八、风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| R1：底部胶囊位置冲突 | 可能与排查步骤（TroubleshootFlow）、参与者缩略头像条（ParticipantStrip）重叠 | 胶囊仅在排队中显示，其他 UI 元素按现有优先级层叠 |
| R2：标题栏徽章挤占空间 | 移动端窄屏下"坐席在线"可能被截断 | 响应式：<360px 改为图标 only |
| R3：API 清理影响其他模块 | api/queue 和 api/quiz 可能被其他文件引用 | 搜索全项目引用，确认无人调用后再删 |
| R4：胶囊与"会话已关闭"消息同时出现 | 排队中会话关闭时，胶囊和系统消息并存 | 关闭会话时立即清除胶囊，避免视觉冲突 |
| R5：WS 推送频率影响胶囊渲染 | 每次位置变化都推 → 胶囊频繁重渲染 | 已在 3.4 节加限制，仅关键节点更新内容 |

**依赖**：
- D1：WebSocket `queue_position_update` 事件已实现（useH5WebSocket.ts:460）
- D2：`store.agentOnline` 字段已存在（用于服务可用性指示）
- D3：EvaluationDialog 组件已实现

---

## 九、变更记录（v1.0 → v1.1）

| 变更项 | v1.0 | v1.1 | 原因 |
|--------|------|------|------|
| 按钮状态数 | 3 态（人工咨询/排队等待/结束咨询） | 5 态（hidden/disabled/active/urgent/waiting） | 与 InputBar.vue 实际实现对齐 + 2026-07-27 移除"结束咨询"按钮态 |
| 服务可用性 UI | 未单独呈现 | 标题栏徽章（在线/离线） | v1.1 G4 新增要求 |
| 排队进度位置 | 右栏底部 QueueWaiting 卡片 | 底部消息胶囊（输入框上方） | v1.1 G5：移动端不可见右栏、桌面端右栏过度堆砌 |
| 答题挑战 | 右栏内嵌（含插队机制） | 完全移除 | v1.1 N5：非核心路径、游戏化双刃剑 |
| 结束会话入口 | 操作按钮"结束咨询"态 | 头像右边红色按钮 | 2026-07-27 已变更，对齐实现 |
| 右栏结构 | 4 大区块（设备/诊断/推荐/排队） | 2 大区块（设备+诊断 / 推荐） | v1.1 G6：聚焦核心 |
| API 清理 | 保留 queue + quiz API | 移除 api/queue + api/quiz | 配套代码清理 |

---

## 十、关联缺陷

| 缺陷编号 | 标题 | 状态 | 优先级 |
|----------|------|------|--------|
| [BUG-用户-003](../../03-测试文档/05-缺陷单/BUG-用户-H5结束会话失败-003.md) | H5员工端"结束会话失败,请稍后重试" | 已修复（2026-07-30） | P2-Medium |