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

# 员工结束会话 PRD

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

---

## 一、需求概述

### 1.1 需求背景

**延续 v1.0/v1.1 背景**：
1. 用户无法主动结束会话，若要结束错误对话历史（如 AI 回答错误），只能开启新会话
2. 人工咨询场景缺少员工主动结束的入口
3. 满意度评价仅在 AI 判定问题已解决时触发，无法覆盖所有会话场景
4. 按钮维度过载，5 种状态文案切换频繁
5. 右栏信息冗余，移动端（<500px）不渲染右栏导致桌面端堆砌的功能"白做"

**v1.2 新增背景**：
1. **顶部退出按钮的真实定位**：经产品澄清，标题栏红色退出按钮**仅服务于 AI 会话的兜底退出**，用于"用户主动告诉系统别再发未回复倒计时"，**不应用于结束人工会话**。人工咨询启动后，顶部按钮应自动隐藏，由操作按钮的"结束咨询"接管。
2. **「无会话」首次进入需要引导**：之前做成 hidden 是工程角度的偷懒，用户体验上应让按钮始终可见 + 引导语引导"先说问题"，避免一打开就催人工。
3. **「重新打开」按钮补全会话收尾体验**：会话已关闭后 24h 内，按钮变成"重新打开"而非 disabled，避免用户卡死无法继续。
4. **end 态按钮回归**：v1.1 移除了"结束咨询"按钮态（统一改用顶部按钮），v1.2 恢复——因为顶部按钮的语义已收窄到 AI 场景，**人工场景的"挂断"动作必须保留在操作按钮上**。

### 1.2 需求目标

| 目标 | 说明 | 状态 |
|------|------|------|
| G1 | 员工可主动结束当前会话（AI 或人工） | 延续 v1.0 ✅ |
| G2 | 结束会话时强制收集满意度评价 | 延续 v1.0 ✅ |
| G3 | 操作按钮承载"会话进程"完整闭环（呼叫-排队-服务-结束-重开） | v1.2 增强 ✏️ |
| G4 | 服务可用性在标题栏显眼可见 | v1.1 沿用 ✅ |
| G5 | 排队进度靠近底部、不污染对话流 | v1.1 沿用 ✅ |
| G6 | 右栏聚焦核心：设备诊断 + 智能推荐 | v1.1 沿用 ✅ |
| G7 | 顶部退出按钮语义收窄到"AI 兜底退出"，人工场景自动隐藏 | v1.2 新增 🆕 |
| G8 | 「无会话」/「<3 轮对话」用引导语代替禁用按钮 | v1.2 新增 🆕 |
| G9 | 「会话已关闭 24h 内」显示"重新打开"按钮 | v1.2 新增 🆕 |

---

## 二、用户故事

| # | 角色 | 用户故事 | 优先级 |
|---|------|----------|--------|
| US-1 | 员工 | 作为员工，我希望在会话结束时能主动关闭会话，以便开始新会话获取正确回答 | P0 |
| US-2 | 员工 | 作为员工，我希望结束会话时能评价本次服务，以便反馈服务质量 | P0 |
| US-3 | 员工 | 作为员工，我希望一眼看到坐席是否在线，以便判断"AI 答不出时能否转人工" | P1 |
| US-4 | 员工 | 作为员工，我希望排队时能看到进度（前面几个人、还要多久），以便降低焦虑 | P1 |
| US-5 | 员工 | 作为员工，我希望 AI 对话中能用顶部按钮明确告诉系统"我走了"，以免被打扰提醒 | P1 🆕 |
| US-6 | 员工 | 作为员工，我希望刚打开应用时知道"先说什么才能叫人"，而不是看到灰按钮困惑 | P2 🆕 |
| US-7 | 员工 | 作为员工，我希望会话关闭后还能在 24h 内重新打开，避免反复开新会话丢失上下文 | P2 🆕 |

---

## 三、功能详情

### 3.1 设计哲学：维度分离 + 场景互斥

**v1.2 核心设计思想**：把 5 种操作按钮状态、引导语、顶部按钮可见性，按"会话场景"重新划分，确保每个 UI 元素的职责单一、场景不重叠。

**三维度划分**（v1.1 沿用 + v1.2 增强）：

| 维度 | 性质 | UI 形式 | v1.2 变化 |
|---|---|---|---|
| **A. 服务可用性** | 系统状态 | 标题栏徽章 🟢/⚫ | 沿用 |
| **B. 会话进程** | 用户动作 | 操作按钮 6 态 + 引导语 | **6 态 + 引导语** |
| **C. 排队进度** | 实时反馈 | 底部消息胶囊 | 沿用 |
| **D. 退出兜底**（v1.2 新增独立维度） | AI 场景专属 | 标题栏红色退出按钮 | **仅 AI 场景显示** |

**为什么"退出兜底"独立成维度**：
- 顶部按钮的语义在 v1.1 模糊（"既能退出 AI 又能结束人工"）
- v1.2 收窄后，它变成"AI 会话兜底退出"的专用入口
- 与操作按钮 end 态**场景互斥**——任何时候只有一个可用，从根本上避免"双入口混淆"

### 3.2 操作按钮 6 态状态机（v1.2 核心变更）

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

**6 态定义**（移除 hidden / 恢复 end / 新增 reopen）：

| 状态值 | 触发条件 | 按钮文案 | 按钮图标 | 按钮样式 | 可点击 |
|--------|---------|---------|---------|---------|--------|
| **disabled**（v1.2 扩展场景） | 无会话 / AI <3 轮 / 坐席离线 / 会话过期 | 人工坐席 | 🔒 | 灰色禁用 | ❌ |
| **active** | AI ≥3 轮 / 无紧急词 | 人工坐席 | 🎧 | 绿色描边 | ✅ |
| **urgent** | 检测到紧急关键词 | 人工坐席 | 🚨 | 红色脉冲 | ✅ |
| **waiting** | 排队中 | 排队等待 | ⏳ | 橙色描边 | ✅（点击取消） |
| **end** 🆕（v1.2 恢复） | 坐席已接入（conv.status === 'serving'） | 结束咨询 | 📴 | 红色填充 | ✅（点击弹满意度评价） |
| **reopen** 🆕（v1.2 新增） | 会话已关闭 + 24h 内 | 重新打开 | 🔄 | 蓝色填充 | ✅（调用 reopen API） |

**v1.2 移除的态**：
- ❌ **hidden** — 不再使用，所有场景都有按钮呈现（避免用户找不到入口）

**优先级顺序**（代码逻辑）：
```
end > reopen > waiting > active/urgent > disabled
```

### 3.3 引导语设计（v1.2 新增 G8）

**位置**：操作按钮正下方的小字（参考现有 `input-bar__guide` 样式，InputBar.vue 行 128-130 已有此结构）

**4 种场景引导语**：

| 场景 | 引导语 | 设计意图 |
|---|---|---|
| **无会话**（刚打开应用） | 💡 先描述一下你遇到的问题，AI 助手会先帮你看看 | 一开始就让用户知道"先说问题" |
| **AI 对话 <3 轮** | 请继续描述您的问题或需求 | 鼓励继续描述，不显示进度数字（避免催促感） |
| **坐席离线** | ⚠️ 坐席当前离线，建议先用 AI 解答；如紧急可刷新重试 | 不完全堵死，给"刷新重试"出口 |
| **会话过期**（>24h） | ⏰ 上一会话已过期，开始新对话吧 | 引导开新会话 |

**设计原则**：
1. **不显示 `{n}/3` 进度数字** — 避免催促感，让用户专注于描述问题
2. **所有引导语都鼓励"先 AI"** — 不给坐席端制造流量压力
3. **离线情况给出口** — 不直接禁用按钮的可达性，留"刷新重试"
4. **过期明确引导"开新对话"** — 避免用户困惑"为什么不能重开"

**引导语和按钮态的对应关系**：

| 按钮态 | 引导语 |
|---|---|
| disabled（无会话） | 先描述一下你遇到的问题... |
| disabled（AI <3 轮） | 请继续描述您的问题或需求 |
| disabled（坐席离线） | 坐席当前离线... |
| disabled（会话过期） | 上一会话已过期... |
| active | （无引导，或可选"AI 答不出再点人工"） |
| urgent / waiting / end / reopen | （无引导，避免冗余） |

### 3.4 服务可用性指示（v1.1 沿用 G4）

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

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

**v1.2 沿用**：永远显示，不随滚动消失。v1.3 可扩展为"在线/繁忙/离线"三态。

### 3.5 顶部退出按钮可见性规则（v1.2 核心新增 G7）

**位置**：标题栏右侧红色退出按钮（`chat-panel__exit-btn`，SVG 退出图标）

**v1.2 关键变更**：**仅 AI 会话场景显示**

| 会话场景 | 顶部按钮可见 | 设计意图 |
|---|---|---|
| 无会话 | ❌ 隐藏 | 用户还没开始，没必要 |
| AI 对话中（disabled / active / urgent） | ✅ 显示 | 兜底退出，告诉系统"别发倒计时" |
| **人工咨询启动后**（waiting） | **❌ 隐藏** | 操作按钮 waiting 接管取消排队 |
| **人工服务中**（serving） | **❌ 隐藏** | 操作按钮 end 接管结束人工 |
| 会话已关闭 | ❌ 隐藏 | 顶部按钮只对"进行中"的会话有意义 |

**为什么这么设计**：
- 顶部按钮的语义被收窄为「AI 会话兜底退出」
- 人工场景的"结束"由操作按钮 end 态专管
- 两个按钮**场景互斥**，任何时候只有一个可用，**从根源避免双入口混乱**
- 用户认知简单："AI 时用顶部，人工时用底部"

**文案强化建议**（技术方案配合）：
- tooltip：「结束会话（不再发送提醒）」
- 确认弹窗：「确定要结束这次咨询吗？将不再发送未回复提醒」

**store 新增字段**（技术方案配合）：
- `store.showHeaderExitBtn: boolean`
- 由会话状态计算得出（见 3.5 表格）

### 3.6 排队进度消息胶囊（v1.1 沿用 G5）

**位置**：主对话流底部（输入框上方），锚定底部不随滚动消失

**4 种状态**（参照 conversation.ts:1800-1814 的"会话已关闭"消息样式）：

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

**关键约束**：
- ❌ **不作为消息插入对话历史**（避免污染 AI 上下文）
- ✅ 仅在关键节点更新（进入排队 / 每跳 3 位 / 接听）

### 3.7 右栏简化（v1.1 沿用 G6）

**删除**（v1.1 已明确）：
- 右栏底部整段 `right-panel__queue-section`（含标题栏、QueueWaiting 组件、答题挑战）
- api/queue、api/quiz、`store.queuePositionData`、`cancelQueue`、`handleQueuePositionUpdate`
- ChatPanel.vue 中 `handleCancelQueue` 流程（改为按钮 emit 到 store）

**v1.2 保留**（桌面端右栏 2 大区块）：
1. 顶部手风琴：设备信息 ↔ 自助诊断（互斥折叠）
2. 中部：智能推荐卡片

移动端（<500px）不渲染右栏，无变化。

### 3.8 结束会话流程（v1.2 修订 G7）

**双入口，按场景分流**：

#### 入口 A：操作按钮 end 态（仅坐席服务中）

```
点击操作按钮"📴 结束咨询"
    ↓
弹出确认框："确定要结束人工咨询吗？"
    ↓ 确认
调用 employeeClose API → 会话状态 resolved
    ↓
弹出满意度评价（EvaluationDialog）
    ↓
提交评价 → 自动关闭窗口
```

#### 入口 B：顶部红色退出按钮（仅 AI 会话）

```
点击顶部红色"退出会话"按钮
    ↓
弹出确认框："确定要结束这次咨询吗？将不再发送未回复提醒"
    ↓ 确认
调用 employeeClose API（标记 close_reason='ai_session_quit'）
    ↓
弹出满意度评价（即使是 AI 服务也收集）
    ↓
提交评价 → 自动关闭窗口
```

**两个入口的防抖/互斥保证**：
- 由 `store.showHeaderExitBtn` 和按钮态计算逻辑保证场景互斥
- 同一按钮组件内 async handler 三件套（防抖 + 同步 store + try/finally 重置）——参见 ChatPanel.vue:403 handleExitWithEvaluation 的修复样本

---

## 四、非目标

| # | 明确不做 |
|---|----------|
| N1 | 不修改人工呼叫的后端逻辑（仅前端 UI 与状态管理调整） |
| N2 | 不区分 AI 会话与人工会话的结束流程（都是 close + evaluation） |
| N3 | 不支持跳过评价直接关闭（必须评价） |
| N4 | 不做 AI 意图识别"叫人工"功能（v1.3 路线图） |
| N5 | 不做答题挑战 / 插队机制（已永久移除） |
| N6 | 不做"在线/繁忙/离线"三态服务可用性（v1.3 路线图） |
| N7 | 不在引导语中显示 `{n}/3` 进度数字（v1.2 拍板不需要，避免催促感） |

---

## 五、验收指标

| # | 指标 | 目标值 | 验收方式 |
|---|------|--------|---------|
| AC1 | 员工可主动结束会话（AI 或人工） | 100% | 双入口分别测试 |
| AC2 | 评价提交率 | =100% | 关闭会话前必须提交评价 |
| AC3 | 操作按钮状态切换正确 | 6 种状态正确切换 | 完整状态机测试 |
| AC4 | 服务可用性永远可见 | 标题栏徽章所有状态可见 | 滚动 + 弹窗场景 |
| AC5 | 排队进度胶囊准确显示 | 排队时显示位置/时间，接听后淡出 | WS 推送全链路 |
| AC6 | 右栏底部 queue section 完全移除 | 桌面端右栏只含 2 大区块 | 构建产物 + 视觉回归 |
| AC7 | 不污染对话流 | 排队进度不进入 store.messages | store 检查 + AI 推荐效果对比 |
| AC8 | 顶部按钮仅 AI 场景显示 🆕 | waiting / serving 时顶部按钮隐藏 | 状态切换测试 |
| AC9 | 引导语按场景正确显示 🆕 | 4 种场景对应正确引导语 | UI 截图比对 |
| AC10 | 重新打开按钮 24h 内可见 🆕 | 会话关闭 + 24h 内显示 🔄 按钮，>24h 不显示 | 时间边界测试 |
| AC11 | 双入口互斥 🆕 | 任何时候顶部按钮和 end 态不同时可用 | 状态机单元测试 |

---

## 六、关联文档

| 文档 | 说明 |
|------|------|
| `前端组件-InputBar.vue` | 操作按钮 6 态实现 + 引导语渲染 |
| `前端组件-ChatPanel.vue` | 标题栏坐席状态徽章 + 顶部退出按钮（v1.2 新增 showHeaderExitBtn） |
| `前端组件-ResolveFeedback.vue` / `EvaluationDialog.vue` | 满意度评价组件 |
| `前端组件-RightPanel.vue` | 右栏（v1.1 已移除 queue section） |
| `前端组件-QueueWaiting.vue` | 右栏排队组件（v1.1 标记弃用） |
| `API-h5.py` | 关闭会话 API + reopen API |
| `stores/conversation.ts` | 新增 `showHeaderExitBtn` 字段 |
| `原型-REQ-会话-001-结束会话流程-v1.2.html` | v1.2 原型图（重绘） |
| `技术方案-REQ-会话-001-员工结束会话-v1.2.md` | v1.2 技术方案（同步更新） |

---

## 七、里程碑

| 阶段 | 任务 | 预计时间 |
|------|------|---------|
| M1 | PRD v1.2 评审 | 0.5 天 |
| M2 | store 新增 `showHeaderExitBtn` 字段 + 状态计算逻辑 | 0.5 天 |
| M3 | InputBar 改造：hidden → disabled + 6 态扩展 + 4 种引导语 | 1 天 |
| M4 | ChatPanel 改造：顶部按钮 v-show 绑定 showHeaderExitBtn | 0.5 天 |
| M5 | 重新打开按钮 + 24h 边界逻辑 | 0.5 天 |
| M6 | 联调测试 + 视觉回归 | 1 天 |
| M7 | 上线 | 0.5 天 |
| **合计** | | **4.5 天** |

---

## 八、风险与依赖

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| R1：end 态 + 顶部按钮双入口导致混乱 | 用户不知道该点哪个 | v1.2 设计为场景互斥，从根上避免 |
| R2：store.showHeaderExitBtn 计算错误 | 顶部按钮在错误场景显示 | 单元测试覆盖所有状态切换路径 |
| R3：24h 边界判断依赖客户端时钟 | 用户改时间可绕过 | 后端 reopen API 做权威校验，前端仅做 UI 提示 |
| R4：end 态按钮文案"结束咨询"被理解为"结束 AI 咨询" | 视觉歧义 | end 态仅在 serving 触发，文案下加微提示或 icon 强化"挂断"语义 |
| R5：引导语和按钮态不同步 | 用户看到引导语但按钮已可点击 | 引导语渲染条件与按钮态计算共享同一 computed |

**依赖**：
- D1：WebSocket `queue_position_update` 事件已实现
- D2：`store.agentOnline` 字段已存在
- D3：EvaluationDialog 组件已实现
- D4：reopen API 已在 `closing.ts:119` 实现

---

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

| 变更项 | v1.1 | v1.2 | 原因 |
|--------|------|------|------|
| 操作按钮状态数 | 5 态（含 hidden） | **6 态（移除 hidden，恢复 end，新增 reopen）** | 隐藏按钮用户体验断裂；end 态回归解决人工场景主动结束需求 |
| 引导语 | 仅 active 态显示 | **4 种场景分阶段引导语** | 用户需要知道"按钮为什么灰"和"如何激活" |
| 顶部按钮可见性 | 所有状态可显示 | **仅 AI 场景显示** | 产品澄清：顶部按钮仅服务 AI 兜底退出，人工场景由操作按钮接管 |
| 「重新打开」按钮 | 无 | **新增（蓝色）** | 会话关闭 24h 内可继续，避免用户卡死 |
| `{n}/3 进度提示` | 有 | **移除** | 用户拍板避免催促感 |
| 顶部按钮文案 | 无 tooltip | **加 tooltip + 确认弹窗** | 强化"不再发送提醒"语义 |
| 状态机互斥保证 | 无 | **showHeaderExitBtn 计算逻辑** | 顶部按钮和 end 态场景互斥 |
| `hidden` 态 | 存在 | **完全移除** | 按钮永远可见，避免用户找不到入口 |
| 结束会话入口 | 仅顶部按钮 | **顶部（AI）+ 操作按钮 end（人工）双入口** | 两个入口场景互斥，不是冗余 |

---

## 十、关联缺陷

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