284 lines
7.4 KiB
Markdown
284 lines
7.4 KiB
Markdown
|
# 员工结束会话功能 - 技术方案
|
|||
|
|
|
|||
|
|
> **版本**: v1.0
|
|||
|
|
> **日期**: 2026-07-24
|
|||
|
|
> **关联PRD**: PRD-REQ-会话-001-员工结束会话-v1.0
|
|||
|
|
> **状态**: 待评审
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、概述
|
|||
|
|
|
|||
|
|
本文档描述"员工结束会话功能"的技术实现方案，复用现有"人工咨询"按钮，实现三状态切换及满意度评价流程。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、技术架构
|
|||
|
|
|
|||
|
|
### 2.1 现有代码结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
frontend-h5/src/components/chat/
|
|||
|
|
├── InputBar.vue # 输入栏组件（含人工咨询按钮）
|
|||
|
|
├── CallAgentModal.vue # 呼叫坐席弹窗（现有）
|
|||
|
|
└── ResolveFeedback.vue # 满意度评价组件（现有）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.2 关键现有代码
|
|||
|
|
|
|||
|
|
**InputBar.vue 现有状态定义**：
|
|||
|
|
```typescript
|
|||
|
|
// 按钮状态类型
|
|||
|
|
type CallAgentState = 'hidden' | 'disabled' | 'active' | 'urgent'
|
|||
|
|
|
|||
|
|
// 按钮文字计算
|
|||
|
|
const callAgentBtnText = computed(() => {
|
|||
|
|
if (callAgentState.value === 'urgent') return '检测到紧急问题，直接呼叫人工坐席'
|
|||
|
|
if (callAgentState.value === 'active') return '点击呼叫人工坐席'
|
|||
|
|
if (callAgentState.value === 'disabled') return '暂不提供人工服务'
|
|||
|
|
return '人工坐席'
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、方案设计
|
|||
|
|
|
|||
|
|
### 3.1 状态机设计
|
|||
|
|
|
|||
|
|
新增"排队中"和"已接入"两种状态：
|
|||
|
|
|
|||
|
|
| 状态值 | 按钮文字 | 按钮样式 | 点击行为 |
|
|||
|
|
|--------|---------|---------|---------|
|
|||
|
|
| `active` | 🎧 人工咨询 | 绿色边框 | 触发 emit('call-agent') |
|
|||
|
|
| `waiting` | ⏳ 排队等待 | 橙色填充 | 弹出确认框（取消排队） |
|
|||
|
|
| `connected` | 📴 结束咨询 | 红色填充 | 弹出满意度评价 |
|
|||
|
|
|
|||
|
|
### 3.2 状态流转
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
active（人工咨询）
|
|||
|
|
↓ 点击
|
|||
|
|
waiting（排队等待） ⇄ 点击取消→active
|
|||
|
|
↓ 坐席接听
|
|||
|
|
connected（结束咨询）
|
|||
|
|
↓ 点击
|
|||
|
|
【调用API】POST /h5/conversations/current/close（关闭会话）
|
|||
|
|
↓ 会话状态变为 resolved
|
|||
|
|
弹出满意度评价 → 提交 → 窗口关闭
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> **技术要点**：必须先调用关闭会话API将会话状态变为resolved，否则评价会报错"只能评价已结单的会话"
|
|||
|
|
|
|||
|
|
### 3.3 组件改动
|
|||
|
|
|
|||
|
|
#### 3.3.1 InputBar.vue
|
|||
|
|
|
|||
|
|
**改动1：状态类型扩展**
|
|||
|
|
```typescript
|
|||
|
|
// 新增状态
|
|||
|
|
type CallAgentState = 'hidden' | 'disabled' | 'active' | 'waiting' | 'connected'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**改动2：按钮文字计算**
|
|||
|
|
```typescript
|
|||
|
|
const callAgentBtnText = computed(() => {
|
|||
|
|
// 新增状态判断
|
|||
|
|
if (callAgentState.value === 'waiting') return '排队等待'
|
|||
|
|
if (callAgentState.value === 'connected') return '结束咨询'
|
|||
|
|
// 保留原有逻辑
|
|||
|
|
...
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**改动3：按钮样式计算**
|
|||
|
|
```typescript
|
|||
|
|
const callAgentBtnClass = computed(() => ({
|
|||
|
|
'call-agent-btn--waiting': callAgentState.value === 'waiting',
|
|||
|
|
'call-agent-btn--connected': callAgentState.value === 'connected',
|
|||
|
|
// 保留原有样式
|
|||
|
|
}))
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**改动4：点击行为扩展**
|
|||
|
|
```typescript
|
|||
|
|
function handleCallAgent(): void {
|
|||
|
|
if (callAgentState.value === 'disabled') return
|
|||
|
|
|
|||
|
|
if (callAgentState.value === 'waiting') {
|
|||
|
|
// 弹出取消确认框
|
|||
|
|
emit('cancel-queue')
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
if (callAgentState.value === 'connected') {
|
|||
|
|
// 弹出满意度评价
|
|||
|
|
emit('end-session')
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 原有逻辑：发起呼叫
|
|||
|
|
emit('call-agent')
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**改动5：按钮显示判断**
|
|||
|
|
```typescript
|
|||
|
|
const showCallAgentBtn = computed(() =>
|
|||
|
|
callAgentState.value !== 'hidden'
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3.3.2 ChatPanel.vue（父组件）
|
|||
|
|
|
|||
|
|
**改动：状态管理**
|
|||
|
|
|
|||
|
|
需要从父组件传递或管理 `callAgentState`，因为：
|
|||
|
|
- 排队状态需要后端推送更新
|
|||
|
|
- 坐席接听状态需要WebSocket推送
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// 从 store 或 props 获取状态
|
|||
|
|
const callAgentState = computed(() => store.callAgentState)
|
|||
|
|
|
|||
|
|
// 事件处理
|
|||
|
|
function handleCancelQueue() {
|
|||
|
|
// 调用后端API取消排队
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function handleEndSession() {
|
|||
|
|
// 显示满意度评价组件
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3.3.3 复用现有组件
|
|||
|
|
|
|||
|
|
| 组件 | 复用方式 |
|
|||
|
|
|------|---------|
|
|||
|
|
| CallAgentModal.vue | 保持不变，用于发起呼叫 |
|
|||
|
|
| ResolveFeedback.vue | 保持不变，用于满意度评价 |
|
|||
|
|
|
|||
|
|
### 3.4 弹窗设计
|
|||
|
|
|
|||
|
|
#### 3.4.1 取消排队确认（复用 van-dialog）
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import { showConfirmDialog } from 'vant'
|
|||
|
|
|
|||
|
|
await showConfirmDialog({
|
|||
|
|
title: '取消排队？',
|
|||
|
|
message: '您正在排队等待人工坐席，是否取消？',
|
|||
|
|
confirmButtonText: '确认取消',
|
|||
|
|
cancelButtonText: '暂不取消',
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 3.4.2 满意度评价（复用 ResolveFeedback.vue）
|
|||
|
|
|
|||
|
|
现有组件已支持，无需大改：
|
|||
|
|
- 评价选项：满意/一般/不满意
|
|||
|
|
- 评语：可选文本输入
|
|||
|
|
- 提交后：emit 'feedback' 事件
|
|||
|
|
|
|||
|
|
**新增：提交后窗口关闭**
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
function handleFeedbackSubmit(feedback) {
|
|||
|
|
// 1. 提交评价到后端
|
|||
|
|
await submitEvaluation(feedback)
|
|||
|
|
|
|||
|
|
// 2. 关闭当前窗口（企业微信环境）
|
|||
|
|
WeixinJSBridge.call('closeWindow')
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、后端API需求
|
|||
|
|
|
|||
|
|
### 4.1 现有API（已存在）
|
|||
|
|
|
|||
|
|
| API | 说明 |
|
|||
|
|
|-----|------|
|
|||
|
|
| `POST /h5/conversations/current/close` | 员工主动关闭会话 |
|
|||
|
|
| `POST /api/conversations/{id}/evaluation` | 提交满意度评价 |
|
|||
|
|
|
|||
|
|
### 4.2 需新增/确认
|
|||
|
|
|
|||
|
|
| API | 说明 |
|
|||
|
|
|-----|------|
|
|||
|
|
| WebSocket推送 | 排队状态变更通知（waiting → connected） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、非技术变更
|
|||
|
|
|
|||
|
|
### 5.1 前端样式新增
|
|||
|
|
|
|||
|
|
```scss
|
|||
|
|
.call-agent-btn--waiting {
|
|||
|
|
background: #ff976a;
|
|||
|
|
color: #fff;
|
|||
|
|
border-color: #ff976a;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
.call-agent-btn--connected {
|
|||
|
|
background: #ee0a24;
|
|||
|
|
color: #fff;
|
|||
|
|
border-color: #ee0a24;
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、风险与依赖
|
|||
|
|
|
|||
|
|
| 风险 | 影响 | 缓解措施 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| R1：状态同步延迟 | WebSocket推送延迟导致UI状态不同步 | 增加轮询兜底 |
|
|||
|
|
| R2：窗口关闭兼容性 | 企业微信closeWindow可能失效 | 引导用户返回会话列表 |
|
|||
|
|
| R3：评价组件复用 | 现有组件可能不完全匹配 | 评估后微调 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、验收标准
|
|||
|
|
|
|||
|
|
| # | 验收条件 |
|
|||
|
|
|---|---------|
|
|||
|
|
| AC1 | 人工咨询按钮显示"人工咨询"，点击触发呼叫 |
|
|||
|
|
| AC2 | 排队等待按钮显示"排队等待"，点击弹出确认框 |
|
|||
|
|
| AC3 | 结束咨询按钮显示"结束咨询"，点击调用API关闭会话后弹出评价 |
|
|||
|
|
| AC4 | 评价提交后窗口自动关闭 |
|
|||
|
|
| AC5 | 重新进入应用显示全新会话 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 八、实施计划
|
|||
|
|
|
|||
|
|
| 阶段 | 任务 | 工时 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| 1 | InputBar.vue 状态扩展 | 2h |
|
|||
|
|
| 2 | ChatPanel.vue 事件对接 | 1h |
|
|||
|
|
| 3 | 窗口关闭逻辑 | 1h |
|
|||
|
|
| 4 | 样式调整 | 0.5h |
|
|||
|
|
| 5 | 联调测试 | 1.5h |
|
|||
|
|
| **合计** | | **6h** |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 九、变更记录
|
|||
|
|
|
|||
|
|
> 本章节记录需求发布后的 bug 修复与变更。技术方案主体（v1.0）保持不变，每次变更记录一行。
|
|||
|
|
|
|||
|
|
| 日期 | 变更内容 | 关联缺陷 | 变更人 |
|
|||
|
|
|------|----------|----------|--------|
|
|||
|
|
| 2026-07-30 | H5 员工端"结束会话失败,请稍后重试"修复：前端最小修复方案 A。`ChatPanel.vue:403-468` `handleExitWithEvaluation` 三件套改造（复用 `isExiting` 防抖 + API 成功后同步 `store.currentConversation.status = 'resolved'` + try/catch/finally 重置 + catch 优先显示后端真实 message）。零后端改动。部署 hash：CSS `index-CfEzPwEP.css` (167849B) / JS `index-DDJ_fm-u.js` (375397B)。 | [BUG-用户-003](../../03-测试文档/05-缺陷单/BUG-用户-H5结束会话失败-003.md) | Duckula (AI) |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十、关联缺陷
|
|||
|
|
|
|||
|
|
| 缺陷编号 | 标题 | 状态 | 优先级 |
|
|||
|
|
|----------|------|------|--------|
|
|||
|
|
| [BUG-用户-003](../../03-测试文档/05-缺陷单/BUG-用户-H5结束会话失败-003.md) | H5员工端"结束会话失败,请稍后重试" | 已修复（2026-07-30） | P2-Medium |
|