wecom_it_smart_desk/docs/02-技术文档/技术方案-REQ-会话-001-员工结束会话-v1.0.archive.md

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

版本: 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 现有状态定义：

// 按钮状态类型
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：状态类型扩展

// 新增状态
type CallAgentState = 'hidden' | 'disabled' | 'active' | 'waiting' | 'connected'

改动2：按钮文字计算

const callAgentBtnText = computed(() => {
  // 新增状态判断
  if (callAgentState.value === 'waiting') return '排队等待'
  if (callAgentState.value === 'connected') return '结束咨询'
  // 保留原有逻辑
  ...
})

改动3：按钮样式计算

const callAgentBtnClass = computed(() => ({
  'call-agent-btn--waiting': callAgentState.value === 'waiting',
  'call-agent-btn--connected': callAgentState.value === 'connected',
  // 保留原有样式
}))

改动4：点击行为扩展

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：按钮显示判断

const showCallAgentBtn = computed(() =>
  callAgentState.value !== 'hidden'
)

3.3.2 ChatPanel.vue（父组件）

改动：状态管理

需要从父组件传递或管理 callAgentState，因为：

• 排队状态需要后端推送更新
• 坐席接听状态需要WebSocket推送

// 从 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）

import { showConfirmDialog } from 'vant'

await showConfirmDialog({
  title: '取消排队？',
  message: '您正在排队等待人工坐席，是否取消？',
  confirmButtonText: '确认取消',
  cancelButtonText: '暂不取消',
})

3.4.2 满意度评价（复用 ResolveFeedback.vue）

现有组件已支持，无需大改：

• 评价选项：满意/一般/不满意
• 评语：可选文本输入
• 提交后：emit 'feedback' 事件

新增：提交后窗口关闭

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 前端样式新增

.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	Duckula (AI)

---

十、关联缺陷

缺陷编号	标题	状态	优先级
BUG-用户-003	H5员工端"结束会话失败,请稍后重试"	已修复（2026-07-30）	P2-Medium