# 邀请功能 PRD

> **版本**: v1.0
> **日期**: 2026-07-19
> **REQ编号**: REQ-集成-002
> **优先级**: P1
> **阶段**: 近期（1-2个月）
> **状态**: 待开发
> **原型**: `原型-REQ-集成-002-邀请流程-v1.0.html`

---

## 一、需求概述

### 1.1 需求背景

当前 IT 智能服务台仅支持一对一对话（用户 ↔ 坐席）。在实际场景中，IT 问题往往涉及多个部门协作（如 VPN 问题需要网络安全组配合），坐席需要能够邀请其他坐席或特定人员加入会话，共同解决问题。

### 1.2 需求目标

1. 支持坐席在会话过程中邀请其他人员加入
2. 支持按组织架构树选择人员或部门批量邀请
3. 支持历史消息共享范围设置（保护隐私）
4. 通过企微应用消息通知被邀请人
5. 实现多人实时协作会话

### 1.3 用户故事

| 角色 | 故事 | 价值 |
|------|------|------|
| 坐席 | 作为坐席，我希望在处理会话时能够邀请其他同事加入，以便多人协作解决复杂问题 | 提升复杂问题处理效率 |
| 被邀请人 | 作为被邀请人，我希望收到企微消息通知并一键加入会话，以便快速响应协助请求 | 减少响应延迟 |
| 发起人 | 作为会话发起人，我希望被邀请人能看到必要的上下文，以便问题描述不重复 | 提升沟通效率 |

---

## 二、功能详情

### 2.1 核心功能清单

| 序号 | 功能 | 描述 | 优先级 |
|------|------|------|--------|
| F1 | 邀请按钮 | 坐席工作台会话区域显示「+ 邀请」按钮 | P0 |
| F2 | 选人弹窗 | 弹出选人弹窗，含组织架构树 + 已选列表 + 历史消息设置 | P0 |
| F3 | 组织架构选择 | 支持勾选人员或整个部门（批量邀请） | P0 |
| F4 | 人员搜索 | 支持按姓名/工号模糊搜索 | P1 |
| F5 | 历史消息共享 | 三档设置：全部/最近10条/不共享 | P0 |
| F6 | 邀请说明 | 坐席可填写邀请说明文字 | P1 |
| F7 | 企微消息通知 | 通过企微应用消息卡片通知被邀请人 | P0 |
| F8 | 加入会话 | 被邀请人点击消息卡片一键加入 H5 会话 | P0 |
| F9 | 多人实时通信 | 所有参与者通过 WebSocket 实时收发消息 | P0 |
| F10 | 参与者列表 | 实时显示当前会话所有参与者及角色 | P0 |
| F11 | 移除参与者 | 坐席可移除某参与者 | P1 |
| F12 | 退出会话 | 被邀请人可主动退出会话 | P1 |
| F13 | 结束会话 | 坐席可结束会话 | P1 |
| F14 | 转让坐席 | 坐席可将会话主导权转给其他参与者 | P2 |

### 2.2 交互流程

```
1. 坐席点击「+ 邀请」按钮
       ↓
2. 弹出选人弹窗（组织架构树 + 已选列表 + 历史消息设置）
       ↓
3. 坐席选择人员/部门 + 设置历史消息共享范围 + 填写邀请说明（可选）
       ↓
4. 点击「确认邀请」
       ↓
5. 后端更新 participants 数组 + 生成邀请卡片消息
       ↓
6. 企微推送应用消息给被邀请人
       ↓
7. 被邀请人点击「加入会话」按钮
       ↓
8. H5 建立 WebSocket 连接 + 拉取历史消息
       ↓
9. 所有人看到「XX 已加入」系统消息
       ↓
10. 多人会话持续进行（实时 WebSocket 通信）
```

### 2.3 历史消息共享模式

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

> **默认值**：建议默认选中「最近10条」，在可见性和隐私之间取得平衡。

### 2.4 邀请人数限制

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

---

## 三、角色与权限

| 操作 | 坐席 | 被邀请人 | 发起人 |
|------|------|----------|--------|
| 邀请人员 | ✅ | ❌ | ❌ |
| 移除参与者 | ✅ | ❌ | ❌ |
| 主动退出 | ❌ | ✅ | ✅ |
| 结束会话 | ✅ | ❌ | ❌ |
| 转让坐席 | ✅ | ❌ | ❌ |
| 发送消息 | ✅ | ✅ | ✅ |

---

## 四、API 接口设计

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/conversations/:id/invite` | POST | 邀请人员加入会话 |
| `/api/conversations/:id/participants` | GET | 获取会话参与者列表 |
| `/api/conversations/:id/participants/:uid` | DELETE | 移除参与者 |
| `/api/contacts/departments` | GET | 获取组织架构树 |
| `/api/contacts/search` | GET | 搜索人员（姓名/工号模糊匹配） |

### 4.1 POST /api/conversations/:id/invite

**请求体**：
```json
{
  "invitee_ids": ["userid1", "userid2"],
  "share_history": "last_10",  // "all" | "last_10" | "none"
  "message": "需要你协助排查VPN证书问题"
}
```

**响应**：
```json
{
  "success": true,
  "invited": [
    {"userid": "userid1", "name": "王工", "status": "notified"}
  ]
}
```

---

## 五、技术架构

### 5.1 核心架构

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

```
员工端(H5) ←→ 后端(FastAPI + Redis) ←→ 坐席工作台
                      ↓
               企微API（应用消息推送）
                      ↓
               被邀请人H5
```

### 5.2 与企微群聊的区别

| 特性 | 本方案 | 企微群聊 |
|------|--------|----------|
| 消息通道 | H5 WebSocket | 企微群消息 API |
| 群成员管理 | 后端自主控制 | 依赖企微群 API |
| 历史消息 | 可配置共享范围 | 群内可见 |
| 外部人员 | 可通过 H5 链接加入 | 需加群 |
| 管理权限 | 坐席拥有完整管理权 | 群主/管理员 |

### 5.3 降级方案

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

---

## 六、数据模型

### 6.1 Conversation 表扩展

```sql
-- 新增字段
ALTER TABLE conversations ADD COLUMN participants JSONB DEFAULT '[]';
-- participants 数组结构：
-- [
--   {"userid": "xxx", "role": "initiator"|"agent"|"invitee", "joined_at": "2026-07-19T10:00:00Z"},
--   ...
-- ]
```

### 6.2 Invitation 表

```sql
CREATE TABLE conversation_invitations (
    id SERIAL PRIMARY KEY,
    conversation_id VARCHAR(64) NOT NULL,
    inviter_id VARCHAR(64) NOT NULL,
    invitee_id VARCHAR(64) NOT NULL,
    share_history VARCHAR(20) DEFAULT 'last_10',
    message TEXT,
    status VARCHAR(20) DEFAULT 'pending',  -- pending / joined / expired
    created_at TIMESTAMP DEFAULT NOW(),
    joined_at TIMESTAMP
);
```

---

## 七、非目标（Non-goals）

1. ❌ 不支持创建企微群聊
2. ❌ 不支持被邀请人拉其他人入群（只能坐席邀请）
3. ❌ 不支持语音/视频通话
4. ❌ 不支持文件传输（文件上传功能独立开发）

---

## 八、关联文档

| 文档 | 位置 |
|------|------|
| 交互原型 | `08-集成生态/原型-REQ-集成-002-邀请流程-v1.0.html` |
| 产品规划总览 | `00-产品规划/PRD-产品规划总览-v1.0.md` |

---

## 九、验收标准

| 场景 | 验收条件 |
|------|----------|
| 邀请单人会话 | 坐席选择1人邀请 → 被邀请人收到企微消息 → 点击加入 → 成功进入会话 |
| 邀请部门 | 坐席勾选整个部门 → 部门下所有人员收到独立通知 |
| 历史消息-全部 | 被邀请人加入后能看到完整历史消息 |
| 历史消息-最近10条 | 被邀请人加入后只能看到最近10条消息 |
| 历史消息-不共享 | 被邀请人加入后看不到历史消息，只有「XX已加入」 |
| 多人协作 | 3人同时在线 → 各端消息实时同步 |
| 移除参与者 | 坐席移除某参与者 → 该人员会话中断 → 其他人员看到「XX已被移除」 |
| 退出会话 | 被邀请人点击退出 → 正常离开 → 其他人员看到「XX已退出」 |
| 离线通知 | 被邀请人离线 → 再次登录企微 → 收到历史消息卡片 |