Simon
facc04aa65
本提交为 .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-*/
289 lines
14 KiB
Markdown
289 lines
14 KiB
Markdown
# 员工结束会话 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 | |