# 员工结束会话功能 - 技术方案

> **版本**: 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 |