simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ddebbe61a5f1512a66c39cf1cc2f0f0f71826365
wecom_it_smart_desk/docs/PRD-增量-人工按钮与术语统一.md
T

13 KiB
Raw Blame History

PRD-增量-人工按钮与术语统一

文档版本: v1.0 创建日期: 2026-06-11 产品经理: 许清楚 (Xu) · 宋献 状态: 待评审 对应任务: 人工按钮需求定义 + 术语/图标统一规范

摘要

本文档包含两个增量需求：

  1. "人工"按钮需求文档 — 定义H5用户端呼叫坐席按钮的完整产品规范
  2. 术语/图标统一规范 — 全局统一"人工"与"摇人"概念，取消"举手"概念

一、"人工"按钮需求文档

1.1 需求背景

当前H5用户端存在以下问题：

  • 按钮文案不统一：代码中为"呼叫"，产品语言中应为"人工"
  • 按钮图标使用了摇铃铛 🔔（手摇铃），与产品定义不符
  • 按钮启用条件未明确定义
  • 坐席端对应状态图标未同步

1.2 产品定义

"人工" = 用户（员工）主动呼叫IT坐席，请求人工服务。

属性 定义
触发者 H5用户端员工
接收者 IT坐席（主责坐席或系统分配坐席）
图标 传菜铃（桌面拍铃）—— 前台/厨房放在桌面、拍一下发出"叮"声的圆形金属铃铛
区别于 "摇人" = 坐席呼叫其他坐席（详见第二节）

图标说明：传菜铃 vs 摇铃

  • ✅ 传菜铃（正确）：圆形金属铃铛，放在桌面上，从上方拍打铃面发出"叮"声。代表"我已提出问题，请人工来看一下"。
  • ❌ 摇铃 🔔（错误）：有把手的手摇铃，摇动发出声响。当前代码中使用的是此图标，需替换。
  • 传菜铃的SVG/Unicode表示：无直接对应的Unicode字符，建议使用自定义SVG图标（圆形底座+金属铃面）

1.3 按钮设计

1.3.1 H5用户端按钮

位置：H5聊天界面标题栏右侧（当前"呼叫"按钮位置）

形态：

┌────────────────────────────────────┐
│  IT智能服务台          [🔔 人工]   │  ← 启用状态（橙色）
│                     [▓▓ 人工]   │  ← 禁用状态（灰色）
└────────────────────────────────────┘

文案：人工（按钮文字）

图标规范：

  • 启用状态：传菜铃SVG图标 + 橙色系配色 #FF9800
  • 禁用状态：传菜铃SVG图标 + 灰色 #9E9E9E，按钮整体 opacity: 0.5; cursor: not-allowed
  • 图标尺寸：16×16px（标题栏）、24×24px（弹窗内）

传菜铃SVG参考：

<!-- 传菜铃（桌面拍铃）SVG示意 -->
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
  <!-- 铃身（圆形，从上方拍打） -->
  <circle cx="12" cy="14" r="7" fill="#FFD54F" stroke="#FFA000" stroke-width="1.5"/>
  <!-- 铃底金属边框 -->
  <ellipse cx="12" cy="20" rx="5" ry="1.5" fill="#FFA000"/>
  <!-- 拍铃动画指示（从上方向下拍） -->
  <line x1="12" y1="4" x2="12" y2="7" stroke="#FF9800" stroke-width="2" stroke-linecap="round"/>
  <circle cx="12" cy="3" r="2" fill="#FF9800"/>
</svg>

1.3.2 启用条件

按钮在以下任一条件满足时启用（橙色，可点击）：

# 条件 说明
1 问题已确定 AI已识别问题类型（problem_confirmed = true），用户可能需要人工进一步处理
2 会话交互达3次 用户与AI的对话轮次 ≥ 3（不含：直接呼叫人工的消息、问候语如"你好""hi"）

禁用状态（灰色，不可点击）：

  • 以上条件均未满足时
  • 显示 title="请先描述您的问题，AI将为您匹配最佳坐席"

计数规则：

计入交互轮次：
  ✅ 用户发送有效问题消息
  ✅ AI回复消息
  ❌ 用户发送"你好"、"hi"等纯问候语（不计入）
  ❌ 用户直接点击呼叫（不计入，但触发呼叫流程）
  ❌ 系统消息（不计入）

1.3.3 点击流程

用户点击"人工"按钮
    │
    ▼
  CallAgentModal 弹窗
    │
    ├── 显示传菜铃动画（替换当前的摇铃铛动画）
    ├── 话术："叮！IT坐席马上来～"
    └── 同时发送 shake/fetch 请求到后端
          │
          ▼
      成功 → 显示"已通知坐席，请稍候"
      失败 → 提示"当前坐席繁忙，请稍后再试"

1.3.4 坐席端联动

坐席端（Agent工作台）对应位置的按钮/状态指示也使用传菜铃图标：

位置 当前状态 目标状态
会话列表 - 标签 "举手"黄色标签 "人工"橙色标签 + 传菜铃图标
会话列表 - 排序权重 hand_raise 标记 human_requested 标记
聊天区 - 系统消息 "员工摇人请求人工" "员工请求人工服务🔔"

1.3.5 坐席离线状态

当无坐席在线时：

  • H5标题栏坐席状态显示：灰色圆点 + "坐席离线"
  • "人工"按钮：保持可见但禁用（灰色），title="当前无在线坐席，请稍后再试或继续与AI对话"
  • 不隐藏按钮（保持用户认知一致性）

二、术语/图标统一规范

2.1 核心概念定义

术语 定义 触发者 接收者 图标 使用范围
人工 用户呼叫坐席，请求人工服务 H5用户端员工 IT坐席 传菜铃（桌面拍铃）SVG 用户端H5 + 坐席端（状态指示）
摇人 主责坐席呼叫其他坐席进入群聊协助 IT坐席 其他IT坐席 👋 招手 仅坐席端
举手 已取消 — — — 全局移除

2.2 "人工"详细规范

含义：用户（员工）需要人工坐席介入处理问题。

触发方式：

  1. 用户点击H5标题栏"🔔 人工"按钮
  2. 用户输入关键词（"转人工"、"人工"、"人工服务"等）—— 关键词触发仍有效

后端标记字段（重构方向）：

# backend/app/schemas/conversation.py

class ConversationTags(BaseModel):
    # 移除: hand_raise: bool = False
    # 新增:
    human_requested: bool = Field(default=False, description="用户请求人工服务")
    human_requested_at: datetime | None = Field(default=None, description="用户请求人工的时间")

前端显示：

  • H5端：标题栏按钮"🔔 人工"
  • 坐席端会话列表：橙色"人工"标签 + 传菜铃图标

2.3 "摇人"详细规范

含义：主责坐席在处理会话时，邀请其他坐席进入当前会话协助。

触发方式：

  • 坐席点击聊天区"🤝 摇人"按钮 → 弹出 InviteDialog.vue

与"人工"的区别：

维度 人工 摇人
触发者 用户（员工） 主责坐席
接收者 IT坐席 其他IT坐席
目的 请求人工服务 协作处理复杂问题
图标 传菜铃 SVG 👋 招手
对应代码 human_requested collaborating_agent_ids

InviteDialog.vue 改动：

  • 标题改为：🤝 摇人 — 邀请坐席协作（当前为"🤝 摇人 — 邀请坐席协作"，已正确）
  • 确保图标使用 👋 而非传菜铃

2.4 全局取消"举手"概念

涉及范围：

类别 涉及文件/位置 改动说明
代码变量名 hand_raise, hand_raise_keywords, detect_hand_raise() 标记为 @deprecated，下个迭代重构为 human_requested, human_request_keywords, detect_human_request()
数据库字段 tags JSON中的 hand_raise: true 保持兼容，新增 human_requested: true，逐步迁移
API响应 ConversationResponse.tags.hand_raise 新增 ConversationResponse.tags.human_requested，旧字段保留一个迭代周期
前端状态 store.tags.hand_raise 改为 store.tags.human_requested
UI文案 "举手标签"、"举手标记" 改为"人工标签"、"人工请求标记"
文档 PRD.md、ARCHITECTURE.md 等 全局替换"举手"为"人工（用户呼叫）"
测试用例 test_scoring_service.py、test_h5_shake.py 变量名重构时同步更新

兼容策略（避免一次性破坏）：

阶段1（本迭代）：
  - 新增 human_requested 字段
  - 旧 hand_raise 字段保留，标记为 @deprecated
  - UI全局切换为"人工"
  - 后端同时写入 hand_raise 和 human_requested（兼容旧逻辑）

阶段2（下个迭代）：
  - 重构变量名：hand_raise → human_requested
  - 移除 hand_raise 写入逻辑
  - 数据库迁移：将 tags 中的 hand_raise 合并到 human_requested

2.5 图标汇总表

场景 图标 说明
H5用户端 - "人工"按钮 传菜铃 SVG 橙色，启用状态
H5用户端 - "人工"按钮（禁用） 传菜铃 SVG 灰色，opacity: 0.5
坐席端 - 会话列表"人工"标签 传菜铃 SVG + "人工"文字 橙色标签
坐席端 - "摇人"按钮 👋 招手emoji
坐席端 - InviteDialog 标题 🤝 + 👋 "摇人 — 邀请坐席协作"
坐席离线状态 ⚪ 灰色圆点 CSS: background-color: #9E9E9E

三、改动清单

3.1 前端改动

文件 改动类型 说明
frontend-h5/src/components/chat/ChatPanel.vue 修改 按钮文案"呼叫"→"人工"，图标🔔→传菜铃SVG，启用条件逻辑
frontend-h5/src/components/chat/CallAgentModal.vue 修改 弹窗标题"摇铃呼叫人工坐席"→"呼叫人工坐席"，动画场景图标更新
frontend-h5/src/stores/conversation.ts 修改 canCallAgent 逻辑（问题确定或交互≥3轮）
frontend-agent/src/components/conversation/ConversationItem.vue 修改 "举手"标签→"人工"标签+传菜铃图标
frontend-agent/src/stores/conversation.ts 修改 排序逻辑中 hand_raise → human_requested
frontend-agent/src/components/conversation/InviteDialog.vue 修改 确认图标/文案为"摇人"=👋

3.2 后端改动

文件 改动类型 说明
backend/app/schemas/conversation.py 修改 新增 human_requested 字段，标记 hand_raise 为 @deprecated
backend/app/services/scoring_service.py 修改 detect_hand_raise() → detect_human_request()，关键词配置 key 不变（兼容）
backend/app/services/message_router.py 修改 标记检测：设置 human_requested = True
backend/app/api/h5.py 修改 shake 端点响应文案更新
backend/app/models/conversation.py 修改 tags 字段兼容 human_requested

3.3 文档改动

文件 改动类型 说明
docs/PRD.md 修改 全局"举手"→"人工（用户呼叫）"，更新术语表
docs/ARCHITECTURE.md 修改 更新排序规则描述，替换"举手"相关描述
docs/01-项目总览与部署手册.md 修改 替换"举手"标签说明
docs/团队沟通文档-架构消息知识库.md 修改 更新标记体系说明

四、验收标准

4.1 "人工"按钮

# 验收标准 验证方式
1 H5标题栏显示"🔔 人工"按钮（传菜铃图标） 视觉验收
2 问题未确定且交互<3轮时，按钮为灰色禁用状态 功能测试
3 问题确定或交互≥3轮时，按钮为橙色启用状态 功能测试
4 点击按钮弹出CallAgentModal，动画使用传菜铃场景 视觉+功能测试
5 坐席离线时，按钮禁用，title提示"当前无在线坐席" 功能测试
6 坐席端会话列表显示"人工"标签+传菜铃图标 视觉验收

4.2 术语统一

# 验收标准 验证方式
1 所有UI、代码注释中无"举手"一词（待重构变量除外，需标记@deprecated） 全文搜索
2 "人工"概念在用户端和坐席端统一 功能测试
3 "摇人"概念仅在坐席端出现，图标为👋 视觉验收
4 后端同时写入 hand_raise（兼容）和 human_requested（新） 单元测试

五、开发优先级

优先级 内容 预计工时
P0 H5"人工"按钮UI改动（文案+图标+启用条件） 0.5天
P0 坐席端"人工"标签显示 0.5天
P1 CallAgentModal动画更新（传菜铃） 0.5天
P1 后端新增 human_requested 字段 0.5天
P2 文档全局更新（PRD/ARCHITECTURE等） 0.5天
P3 代码变量名重构（hand_raise → human_requested） 1天（下个迭代）

附录 A：传菜铃图标注说明

由于Unicode中无直接对应的传菜铃字符，使用自定义SVG图标。

推荐SVG（简洁版）：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
  <!-- 铃身 -->
  <circle cx="12" cy="14" r="7" fill="#FFD54F" stroke="#FFA000" stroke-width="1.5"/>
  <!-- 金属高光 -->
  <ellipse cx="10" cy="12" rx="2.5" ry="1.5" fill="#FFF9C4" opacity="0.6"/>
  <!-- 铃底 -->
  <ellipse cx="12" cy="20" rx="5" ry="1.5" fill="#FFA000"/>
  <!-- 拍击指示（小圆点代表"拍"的动作） -->
  <circle cx="12" cy="5" r="1.8" fill="#FF9800"/>
  <line x1="12" y1="5" x2="12" y2="8" stroke="#FF9800" stroke-width="1.5"/>
</svg>

启用/禁用状态CSS：

.bell-counter-icon { filter: none; }
.bell-counter-icon--disabled { filter: grayscale(100%); opacity: 0.5; }
Reference in New Issue View Git Blame Copy Permalink