simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be361fb63783520f5dcfd7cce386ac9b5523d4f
wecom_it_smart_desk/docs/01-产品文档/02-会话管理/PRD-REQ-会话-001-员工结束会话-v1.2.archive.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .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-*/
2026-08-07 22:31:32 +08:00

17 KiB
Raw Blame History

员工结束会话 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 H5员工端"结束会话失败,请稍后重试" 已修复（2026-07-30） P2-Medium
Reference in New Issue View Git Blame Copy Permalink