Simon
facc04aa65
本提交为 .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-*/
242 lines
8.0 KiB
Markdown
242 lines
8.0 KiB
Markdown
# 邀请功能 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已退出」 |
|
||
| 离线通知 | 被邀请人离线 → 再次登录企微 → 收到历史消息卡片 |
|