# 方案三：邀请功能原型 — 交互流程

# 邀请功能 — 方案三交互原型

WebSocket + 应用消息双通道架构 | 在现有一对一对话上扩展多人参与
0. 架构概览
1. 一对一会话中
2. 点击邀请
3. 选人界面
4. 历史共享
5. 确认邀请
6. 被邀请方通知
7. 加入会话
8. 多人会话

### 方案三核心架构

在现有 WebSocket 双通道 架构上扩展，不引入群聊概念。后端维护 conversation.participants 数组，所有参与者共享同一个 WebSocket 会话通道。

架构流程图
关键区别：不创建企微群聊，所有参与者通过 H5+WebSocket 接入同一个后端 conversation。企微应用消息仅用于「通知被邀请人」和「断连降级推送」。

### 场景：坐席正在与用户一对一对话

用户「张三」遇到 VPN 问题，坐席「小李」正在处理。对话过程中发现需要网络安全组同事「王工」协助排查。

坐席工作台 — 会话区
张
张三
IT研发部 · 高级开发工程师
会话中
张
VPN 连接不上，提示证书错误
李
您好，请问您使用的是 ATrust 还是零信任客户端？
张
ATrust，之前一直正常的，今天突然不行了
李
这个问题可能涉及网络策略变更，我邀请网络安全组的同事一起排查

### 交互说明

1
坐席点击「+ 邀请」
坐席工作台
2
弹出选人弹窗（组织架构树/搜索）
坐席工作台
3
选择历史消息共享范围
选人弹窗
4
确认邀请 → 后端处理
后端 API
5
企微应用消息通知被邀请人
企微 API
6
被邀请人打开 H5 加入会话
H5 员工端

### 步骤 2：点击「+ 邀请」→ 弹出选人弹窗

弹窗包含三个区域：组织架构树（左侧）、已选人员（右侧上方）、历史消息共享设置（右侧下方）。

坐席工作台 — 邀请弹窗
选择邀请对象
▼
✓
信息技术部
▶
IT支持组
✓
王工 网络安全
赵磊 系统运维
软件开发组 8人
▶
信息安全部
已选择 (1)
王
王工
信息技术部·网络安全 ✕
历史消息共享
被邀请人加入后能看到哪些历史消息？
共享全部历史消息 仅共享最近10条消息 不共享历史消息
邀请说明（可选）

### 步骤 3：选择人员 — 支持按部门批量邀请

勾选部门节点 = 邀请该部门所有人。每个被邀请人都会收到独立的应用消息通知。

选人 — 勾选整个部门
▼
✓
信息安全部 全部邀请
✓
陈安全 安全主管
✓
刘防护 安全工程师
▶
IT支持组 3人

### 选人交互规则

操作 | 效果
--- | ---
勾选人员 | 该人员加入已选列表
勾选部门 | 该部门下所有人员加入已选列表
搜索姓名 | 模糊匹配，点击结果直接加入已选
取消勾选 | 从已选列表移除

注意：邀请人数建议上限 10 人。超过 10 人时应提示「当前邀请人数较多，建议优先邀请关键人员」。这不是硬限制，而是用户体验优化。

### 步骤 4：历史消息共享设置

邀请时坐席可以选择被邀请人能看到哪些历史消息。这是隐私保护的重要设计——避免敏感信息（如员工个人账号问题）被无关人员看到。

### 三种共享模式对比

模式 | 适用场景 | 隐私风险
--- | --- | ---
共享全部 | 通用IT问题（VPN/网络/打印），无敏感信息 | 低
最近10条 | 对话较长，仅需上下文即可理解当前问题 | 中
不共享 | 涉及员工个人账号/权限等敏感信息 | 低

### 被邀请人视角 — 共享 vs 不共享

共享全部
[张三] VPN连不上...
[小李] 请问用的是...
[张三] ATrust...
↑ 可看到完整上下文
不共享
[历史消息不可见]
── 加入会话 ──
[王工] 我来看看VPN...
↑ 仅能看到加入后的消息
默认值：建议默认选中「最近10条」，在可见性和隐私之间取得平衡。坐席可根据实际情况调整。

### 步骤 5：确认邀请 → 后端处理流程

确认邀请 — 后端处理时序
1
坐席点击「确认邀请」
坐席工作台 → POST /api/conversations/:id/invite
2
后端更新 participants 数组，将王工 userid 加入 conversation.participants
后端 → PostgreSQL
3
后端生成邀请卡片消息（含会话ID + H5入口链接 + 邀请说明 + 共享的历史消息摘要）
后端 → 企微应用消息 API
4
企微推送应用消息给王工（单聊卡片消息，非群聊消息）
企微 → 王工企微客户端
5
坐席工作台显示「已邀请王工」系统消息，会话参与者列表更新
WebSocket → 坐席工作台
6
坐席工作台显示「已邀请王工」系统消息，会话参与者列表更新
WebSocket → H5 发起者

### API 接口设计

接口 | 方法 | 说明
--- | --- | ---
/api/conversations/:id/invite | POST | 邀请人员加入会话
/api/conversations/:id/participants | GET | 获取会话参与者列表
/api/conversations/:id/participants/:uid | DELETE | 移除参与者（坐席/被邀请人退出）
/api/contacts/departments | GET | 获取组织架构树（缓存自eHR/企微通讯录）
/api/contacts/search | GET | 搜索人员（姓名/工号模糊匹配）

### 步骤 6：被邀请人收到企微应用消息

王工在企微中收到一条应用消息卡片，点击卡片中的按钮即可跳转到 H5 会话页面。

企微消息卡片 — 通知样式
IT
IT智能服务台
刚刚
邀请你加入 IT 支持会话
邀请人：小李（IT支持组）
发起人：张三（IT研发部）
问题摘要：VPN证书错误，ATrust客户端无法连接
邀请说明：需要你协助排查VPN证书问题
加入会话

### 消息卡片设计要点

- 使用交互式卡片消息（textcard 类型），而非纯文本
- 包含问题摘要，让被邀请人判断是否需要立即加入
- 「加入会话」按钮直接跳转 H5 页面（企微内置浏览器）
- 如果共享了历史消息，摘要中自动包含最近 2-3 条关键消息

### 降级方案

如果被邀请人未安装企微或处于离线：后端记录邀请状态为「待加入」。被邀请人下次登录企微时会收到消息。同时，坐席工作台显示邀请状态：待加入 / 已加入

### 步骤 7：被邀请人点击「加入会话」→ H5 页面

王工点击消息卡片按钮 → 企微内置浏览器打开 H5 页面 → 自动加入 WebSocket 会话 → 看到历史消息（如果被共享）→ 可直接发消息

H5 被邀请人视角 — 加入后
IT支持会话
3人参与
── 小李 邀请了 王工 加入会话 ──
张
VPN 连接不上，提示证书错误
李
请问您使用的是 ATrust 还是零信任客户端？
张
ATrust，之前一直正常的，今天突然不行了
── 王工 已加入会话 ──
王
我来看看，先确认下证书服务状态

### 加入流程细节

1
点击「加入会话」
企微内置浏览器打开 H5 URL（含 conversation_id + token）
2
H5 自动认证
企微环境 → OAuth2 自动登录；非企微 → Mock 登录
3
建立 WebSocket 连接
加入 conversation 的消息通道
4
拉取历史消息
根据共享设置，显示可查看的历史消息
5
广播「XX 已加入」
所有参与者（坐席+用户+其他被邀请人）都能看到

### 步骤 8：多人会话持续进行

所有人通过 WebSocket 实时通信。坐席工作台和所有 H5 参与者共享同一个消息通道。坐席拥有管理权限（可移除参与者、结束会话）。

坐席工作台 — 多人会话
张
张三发起
李
小李坐席
王
王工邀请
── 小李 邀请了 王工 加入会话 ──
张
张三
VPN 连接不上，提示证书错误
李
小李（坐席）
请问您使用的是 ATrust 还是零信任客户端？
张
张三
ATrust，今天突然不行了
── 王工 已加入会话 ──
王
王工（受邀）
证书服务器刚做了更新，我来检查下白名单配置
张
张三
好的，麻烦了
H5 被邀请人视角 — 王工
IT支持会话
3人 已加入
你可以查看最近10条历史消息
张
张三
ATrust，今天突然不行了
── 王工 已加入会话 ──
王
证书服务器刚做了更新，我来检查下白名单配置
张
张三
好的，麻烦了

### 坐席管理能力

操作 | 权限 | 说明
--- | --- | ---
邀请人员 | 坐席 | 选择人员加入会话
移除参与者 | 坐席 | 将某人移出会话（不通知）
主动退出 | 被邀请人 | 被邀请人可自行退出
结束会话 | 坐席 | 关闭会话，所有人断开
转让坐席 | 坐席 | 将坐席角色转给其他参与者

与企微群聊的核心区别：
1. 会话数据完全在后端控制，不依赖企微群聊 API
2. 被邀请人通过 H5 WebSocket 通信，无需加入企微群
3. 坐席拥有管理权限，可控制参与者和历史可见性
4. 外部联系人（供应商等）也可通过 H5 链接加入