408 lines
15 KiB
Markdown
408 lines
15 KiB
Markdown
|
# 邀请功能 — 技术方案
|
|||
|
|
|
|||
|
|
> **场景**：坐席在处理会话时需要拉入其他员工/部门协助，通过邀请功能将新人加入同一会话。
|
|||
|
|
>
|
|||
|
|
> **与"摇人"的区别**：摇人是坐席→坐席的协作（`collaborating_agent_ids`），邀请是坐席→任意员工/部门的协作（`participants`）。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、方案决策记录
|
|||
|
|
|
|||
|
|
### 1.1 方案选型（2026-06-10 确认）
|
|||
|
|
|
|||
|
|
| 方案 | 核心思路 | 可行性 | 结论 |
|
|||
|
|
|------|---------|--------|------|
|
|||
|
|
| 方案一：一对一+邀请 | 在现有会话扩展参与者，企微应用消息通知 | ✅ 可行 | 备选 |
|
|||
|
|
| 方案二：应用群聊 | 企微 `appchat` 创建群，群内沟通 | ❌ 应用无法接收群内消息 | 不可行 |
|
|||
|
|
| **方案三：WebSocket+应用消息双通道** | 后端维护 `participants`，WebSocket 通信，企微消息仅通知 | ✅ 零新增基础设施 | **采纳** |
|
|||
|
|
|
|||
|
|
**方案二不可行原因**：企微 `appchat` 是「应用推送消息群」，群成员在群内发言**不会回调给应用**。应用只能单向推送消息到群，无法看到用户回复，坐席工作台无法获取群内对话。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、数据模型改动
|
|||
|
|
|
|||
|
|
### 2.1 Conversation 模型新增字段
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/models/conversation.py
|
|||
|
|
|
|||
|
|
# 会话参与者列表（JSON 数组）
|
|||
|
|
# 与 collaborating_agent_ids 的区别：
|
|||
|
|
# - collaborating_agent_ids：被邀请来协助的坐席ID（坐席间协作）
|
|||
|
|
# - participants：被邀请加入会话的员工/部门成员（跨端协作）
|
|||
|
|
# 每个 participant 包含：userid, name, department, joined_at, role, invited_by
|
|||
|
|
participants: Mapped[list] = mapped_column(
|
|||
|
|
JSON,
|
|||
|
|
nullable=False,
|
|||
|
|
default=list,
|
|||
|
|
comment="会话参与者列表",
|
|||
|
|
)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.2 participants 字段结构
|
|||
|
|
|
|||
|
|
```json
|
|||
|
|
[
|
|||
|
|
{
|
|||
|
|
"userid": "zhangsan",
|
|||
|
|
"name": "张三",
|
|||
|
|
"department": "技术部/网络组",
|
|||
|
|
"role": "invited", // "invited"=被邀请人, "owner"=原始员工
|
|||
|
|
"invited_by": "agent_001", // 邀请人的坐席ID
|
|||
|
|
"joined_at": "2026-06-10T14:30:00Z",
|
|||
|
|
"history_shared": "last_10", // "all" / "last_10" / "none"
|
|||
|
|
"status": "active" // "active" / "left"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.3 数据库迁移 SQL
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
-- 开发环境 SQLite / 生产环境 PostgreSQL 通用
|
|||
|
|
ALTER TABLE conversations ADD COLUMN participants JSON NOT NULL DEFAULT '[]';
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 2.4 权限矩阵
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
原始员工 主责坐席 协作坐席 被邀请人
|
|||
|
|
查看消息 ✅ ✅ ✅ ✅
|
|||
|
|
发送消息 ✅ ✅ ✅ ✅
|
|||
|
|
邀请他人 ❌ ✅ ✅ ❌
|
|||
|
|
结单 ❌ ✅ ❌ ❌
|
|||
|
|
转接 ❌ ✅ ❌ ❌
|
|||
|
|
退出会话 关闭页面 ❌（主责不可） ✅（退出协作） ✅
|
|||
|
|
移除参与者 ❌ ✅ ❌ ❌
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、后端实现
|
|||
|
|
|
|||
|
|
### 3.1 新增 Schema
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/schemas/conversation.py
|
|||
|
|
|
|||
|
|
class ConversationInviteRequest(BaseModel):
|
|||
|
|
"""邀请请求"""
|
|||
|
|
user_ids: list[str] = Field(..., description="被邀请人ID列表")
|
|||
|
|
department_ids: list[str] = Field(default_factory=list, description="部门ID列表（整部门邀请）")
|
|||
|
|
history_shared: str = Field("last_10", description="历史消息共享模式: all/last_10/none")
|
|||
|
|
|
|||
|
|
class ConversationInviteResponse(BaseModel):
|
|||
|
|
"""邀请响应"""
|
|||
|
|
conversation_id: UUID
|
|||
|
|
invited_count: int = Field(..., description="成功邀请人数")
|
|||
|
|
failed: list[dict] = Field(default_factory=list, description="邀请失败的用户及原因")
|
|||
|
|
participants: list[dict] = Field(default_factory=list, description="更新后的参与者列表")
|
|||
|
|
|
|||
|
|
|
|||
|
|
class ConversationLeaveRequest(BaseModel):
|
|||
|
|
"""退出会话请求"""
|
|||
|
|
pass
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 ConversationResponse 扩展字段
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class ConversationResponse(BaseModel):
|
|||
|
|
# ... 现有字段 ...
|
|||
|
|
|
|||
|
|
# ----- 邀请功能扩展字段 -----
|
|||
|
|
participants: list[dict] = Field(default_factory=list, description="参与者列表")
|
|||
|
|
participant_count: int = Field(0, description="参与者人数")
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 新增 API 端点
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/api/conversations.py
|
|||
|
|
|
|||
|
|
# POST /api/conversations/{id}/invite
|
|||
|
|
# 坐席邀请员工/部门加入会话
|
|||
|
|
@router.post("/conversations/{conversation_id}/invite")
|
|||
|
|
async def invite_participants(
|
|||
|
|
conversation_id: UUID,
|
|||
|
|
body: ConversationInviteRequest,
|
|||
|
|
db: AsyncSession = Depends(get_db),
|
|||
|
|
current_agent: Agent = Depends(get_current_agent),
|
|||
|
|
):
|
|||
|
|
"""
|
|||
|
|
邀请员工/部门加入会话。
|
|||
|
|
|
|||
|
|
校验规则：
|
|||
|
|
1. 当前用户必须是主责坐席或协作坐席
|
|||
|
|
2. 会话状态必须为 serving
|
|||
|
|
3. 被邀请人不能已在 participants 中
|
|||
|
|
4. 被邀请人不能是主责坐席
|
|||
|
|
|
|||
|
|
副作用：
|
|||
|
|
1. 更新 conversation.participants
|
|||
|
|
2. 企微应用消息通知被邀请人
|
|||
|
|
3. WebSocket 广播系统消息
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
# POST /api/conversations/{id}/leave
|
|||
|
|
# 被邀请人退出会话
|
|||
|
|
@router.post("/conversations/{conversation_id}/leave")
|
|||
|
|
async def leave_conversation(
|
|||
|
|
conversation_id: UUID,
|
|||
|
|
db: AsyncSession = Depends(get_db),
|
|||
|
|
current_user = Depends(get_current_user), # 可以是坐席或H5用户
|
|||
|
|
):
|
|||
|
|
"""
|
|||
|
|
参与者退出会话。
|
|||
|
|
|
|||
|
|
校验规则：
|
|||
|
|
1. 当前用户必须在 participants 中（role=invited）
|
|||
|
|
2. 主责坐席不能退出
|
|||
|
|
3. 原始员工不能退出（关闭页面即视为离开）
|
|||
|
|
|
|||
|
|
副作用：
|
|||
|
|
1. 更新 participant.status = "left"
|
|||
|
|
2. WebSocket 广播系统消息
|
|||
|
|
"""
|
|||
|
|
|
|||
|
|
|
|||
|
|
# DELETE /api/conversations/{id}/participants/{userid}
|
|||
|
|
# 坐席移除参与者
|
|||
|
|
@router.delete("/conversations/{conversation_id}/participants/{userid}")
|
|||
|
|
async def remove_participant(
|
|||
|
|
conversation_id: UUID,
|
|||
|
|
userid: str,
|
|||
|
|
db: AsyncSession = Depends(get_db),
|
|||
|
|
current_agent: Agent = Depends(get_current_agent),
|
|||
|
|
):
|
|||
|
|
"""
|
|||
|
|
主责坐席移除会话参与者。
|
|||
|
|
|
|||
|
|
校验规则：
|
|||
|
|
1. 当前用户必须是主责坐席
|
|||
|
|
2. 被移除人必须在 participants 中且 status=active
|
|||
|
|
|
|||
|
|
副作用：
|
|||
|
|
1. 更新 participant.status = "left"
|
|||
|
|
2. WebSocket 广播系统消息
|
|||
|
|
"""
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.4 企微通知卡片消息
|
|||
|
|
|
|||
|
|
邀请时发送企微 template_card 卡片消息：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/services/wecom_service.py
|
|||
|
|
|
|||
|
|
async def send_invite_card(
|
|||
|
|
self,
|
|||
|
|
invitee_userid: str,
|
|||
|
|
inviter_name: str,
|
|||
|
|
employee_name: str,
|
|||
|
|
problem_summary: str,
|
|||
|
|
conversation_id: str,
|
|||
|
|
) -> None:
|
|||
|
|
"""发送邀请卡片消息给被邀请人"""
|
|||
|
|
|
|||
|
|
card = {
|
|||
|
|
"msgtype": "template_card",
|
|||
|
|
"template_card": {
|
|||
|
|
"card_type": "button_interaction",
|
|||
|
|
"source": {
|
|||
|
|
"desc": "IT智能服务台"
|
|||
|
|
},
|
|||
|
|
"main_title": {
|
|||
|
|
"title": "🔔 会话邀请"
|
|||
|
|
},
|
|||
|
|
"emphasis_content": {
|
|||
|
|
"title": f"{inviter_name} 邀请你协助处理",
|
|||
|
|
"desc": f"员工：{employee_name}"
|
|||
|
|
},
|
|||
|
|
"sub_title_text": f"问题：{problem_summary[:50]}",
|
|||
|
|
"button_list": [
|
|||
|
|
{
|
|||
|
|
"text": "加入会话",
|
|||
|
|
"style": 1, # 蓝色主按钮
|
|||
|
|
"key": f"join_{conversation_id}"
|
|||
|
|
},
|
|||
|
|
{
|
|||
|
|
"text": "稍后查看",
|
|||
|
|
"style": 2, # 灰色次按钮
|
|||
|
|
"key": "later"
|
|||
|
|
}
|
|||
|
|
]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.5 WebSocket 事件定义
|
|||
|
|
|
|||
|
|
| 事件类型 | 推送范围 | 数据 |
|
|||
|
|
|---------|---------|------|
|
|||
|
|
| `participant_invited` | 所有在线坐席 + 会话内H5用户 | `{ conversation_id, invited_by, participants: [{userid, name, role}] }` |
|
|||
|
|
| `participant_joined` | 所有在线坐席 + 会话内H5用户 | `{ conversation_id, userid, name }` |
|
|||
|
|
| `participant_left` | 所有在线坐席 + 会话内H5用户 | `{ conversation_id, userid, name, reason: "self_left"/"removed" }` |
|
|||
|
|
| `participant_removed` | 所有在线坐席 + 被移除人 | `{ conversation_id, userid, name, removed_by }` |
|
|||
|
|
|
|||
|
|
### 3.6 历史消息共享逻辑
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# backend/app/services/session_service.py
|
|||
|
|
|
|||
|
|
async def get_shared_messages(
|
|||
|
|
self,
|
|||
|
|
conversation_id: UUID,
|
|||
|
|
history_shared: str, # "all" / "last_10" / "none"
|
|||
|
|
) -> list[dict]:
|
|||
|
|
"""根据共享模式返回历史消息"""
|
|||
|
|
|
|||
|
|
if history_shared == "none":
|
|||
|
|
return []
|
|||
|
|
|
|||
|
|
messages = await self._get_conversation_messages(conversation_id)
|
|||
|
|
|
|||
|
|
if history_shared == "last_10":
|
|||
|
|
# 取最近10条，优先包含人工消息
|
|||
|
|
return messages[-10:]
|
|||
|
|
|
|||
|
|
# "all" — 返回全部
|
|||
|
|
return messages
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、前端实现
|
|||
|
|
|
|||
|
|
### 4.1 坐席工作台（Agent）
|
|||
|
|
|
|||
|
|
#### 4.1.1 API 层新增
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
// frontend-agent/src/api/conversation.ts
|
|||
|
|
|
|||
|
|
/** 邀请员工/部门加入会话 */
|
|||
|
|
export function inviteParticipants(
|
|||
|
|
conversationId: string,
|
|||
|
|
data: { user_ids: string[]; department_ids?: string[]; history_shared?: string }
|
|||
|
|
): Promise<ConversationInviteResponse>
|
|||
|
|
|
|||
|
|
/** 退出会话 */
|
|||
|
|
export function leaveConversation(conversationId: string): Promise<void>
|
|||
|
|
|
|||
|
|
/** 移除参与者 */
|
|||
|
|
export function removeParticipant(conversationId: string, userid: string): Promise<void>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 4.1.2 邀请弹窗组件
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────────────────┐
|
|||
|
|
│ 邀请加入会话 │
|
|||
|
|
│ │
|
|||
|
|
│ 🔍 [搜索姓名/工号...] │
|
|||
|
|
│ │
|
|||
|
|
│ ┌── 组织架构 ──┐ ┌── 已选 (3人) ──────┐│
|
|||
|
|
│ │ ▼ 技术部 │ │ × 张三 / 网络组 ││
|
|||
|
|
│ │ ☑ 网络组 │ │ × 李四 / 运维组 ││
|
|||
|
|
│ │ ○ 运维组 │ │ × 王五 / 安全组 ││
|
|||
|
|
│ │ ▼ 行政部 │ └────────────────────┘│
|
|||
|
|
│ │ ○ 前台 │ │
|
|||
|
|
│ └──────────────┘ │
|
|||
|
|
│ │
|
|||
|
|
│ 历史消息共享： │
|
|||
|
|
│ ○ 全部 ● 最近10条 ○ 不共享 │
|
|||
|
|
│ │
|
|||
|
|
│ [取消] [确认邀请] │
|
|||
|
|
└──────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 4.1.3 参与者面板（聊天区头部）
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────────────────────────┐
|
|||
|
|
│ 👤 张三 · 网络问题 [+ 邀请] [⋮] │
|
|||
|
|
│ 👥 3人参与: 我(坐席) · 张三(员工) · 李四(受邀) │ ← 可点击展开
|
|||
|
|
└──────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.2 H5用户端（被邀请人视角）
|
|||
|
|
|
|||
|
|
#### 4.2.1 加入会话流程
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
点击企微通知 → H5加载 → Mock登录/自动登录 → 加载会话 → 拉取历史 → WebSocket连接 → 可发送消息
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### 4.2.2 参与者标识
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────────────────┐
|
|||
|
|
│ IT支持会话 [退出] │
|
|||
|
|
│ 👥 参与者: 坐席(小宋) · 你 · 张三(网络组) │
|
|||
|
|
├──────────────────────────────────────────┤
|
|||
|
|
│ │
|
|||
|
|
│ [系统] 李四(坐席)邀请你加入会话 │
|
|||
|
|
│ [系统] 你已加入会话 │
|
|||
|
|
│ [坐席] 网络组的同事来看下这个VPN问题 │
|
|||
|
|
│ [张三] 我看下，是零信任客户端连不上对吧 │
|
|||
|
|
│ │
|
|||
|
|
├──────────────────────────────────────────┤
|
|||
|
|
│ [输入消息...] [发送] │
|
|||
|
|
└──────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、改动清单汇总
|
|||
|
|
|
|||
|
|
| 文件 | 改动类型 | 说明 |
|
|||
|
|
|------|---------|------|
|
|||
|
|
| `backend/app/models/conversation.py` | 修改 | +`participants` 字段 |
|
|||
|
|
| `backend/app/schemas/conversation.py` | 修改 | +邀请/退出/移除Schema + 响应扩展字段 |
|
|||
|
|
| `backend/app/api/conversations.py` | 修改 | +`invite`/`leave`/`remove_participant` 三个端点 |
|
|||
|
|
| `backend/app/services/session_service.py` | 修改 | +邀请/退出/历史共享逻辑 |
|
|||
|
|
| `backend/app/services/wecom_service.py` | 修改 | +`send_invite_card` 卡片消息 |
|
|||
|
|
| `frontend-agent/src/api/conversation.ts` | 修改 | +3个API函数 |
|
|||
|
|
| `frontend-agent/src/stores/conversation.ts` | 修改 | +participants相关计算属性和方法 |
|
|||
|
|
| `frontend-agent/src/components/conversation/InviteDialog.vue` | **新建** | 邀请弹窗组件 |
|
|||
|
|
| `frontend-agent/src/components/conversation/ParticipantBar.vue` | **新建** | 参与者面板组件 |
|
|||
|
|
| `frontend-h5/src/components/chat/ParticipantList.vue` | **新建** | H5参与者列表组件 |
|
|||
|
|
| `frontend-h5/src/views/ChatView.vue` | 修改 | +退出按钮 + 参与者展示 |
|
|||
|
|
| `frontend-h5/src/api/conversation.ts` | 修改 | +退出会话API |
|
|||
|
|
| `frontend-agent/src/composables/useWebSocket.ts` | 修改 | +4个WS事件处理 |
|
|||
|
|
| `frontend-h5/src/composables/useWebSocket.ts` | 修改 | +4个WS事件处理 |
|
|||
|
|
| 数据库迁移 SQL | **新建** | `ALTER TABLE` 加列 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、开发顺序
|
|||
|
|
|
|||
|
|
| 步骤 | 内容 | 依赖 | 预计工时 |
|
|||
|
|
|------|------|------|---------|
|
|||
|
|
| 1 | 模型 + 迁移 SQL + participants字段 | 无 | 0.5天 |
|
|||
|
|
| 2 | Schema + SessionService邀请逻辑 | 1 | 1天 |
|
|||
|
|
| 3 | API端点（invite/leave/remove） + 历史共享 | 2 | 1天 |
|
|||
|
|
| 4 | 企微template_card消息发送 | 2 | 0.5天 |
|
|||
|
|
| 5 | 后端测试 | 3 | 0.5天 |
|
|||
|
|
| 6 | 坐席端 InviteDialog + ParticipantBar 组件 | 无（可并行） | 1.5天 |
|
|||
|
|
| 7 | H5端 ChatView改动 + ParticipantList | 无（可并行） | 1天 |
|
|||
|
|
| 8 | WebSocket 事件处理（双端） | 3 | 0.5天 |
|
|||
|
|
| 9 | 端到端集成测试 | 全部 | 1天 |
|
|||
|
|
| **合计** | | | **7-8天** |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、设计决策
|
|||
|
|
|
|||
|
|
| 决策 | 理由 |
|
|||
|
|
|------|------|
|
|||
|
|
| 使用 `participants` JSON 数组而非关联表 | 参与者数量少（1-5人），JSON 查询足够；与 `collaborating_agent_ids` 设计一致 |
|
|||
|
|
| 历史消息默认共享最近10条 | 避免被邀请人被大量无关历史淹没，同时保留足够上下文理解问题 |
|
|||
|
|
| 被邀请人不能二次邀请 | 防止邀请链失控，只有坐席有权管理参与者 |
|
|||
|
|
| 不使用企微 appchat 群聊 | appchat 群内消息不会回调给应用，坐席无法获取群内对话 |
|
|||
|
|
| 企微通知用 template_card 而非 text | 卡片消息提供「加入会话」按钮，体验优于纯文本+手动复制链接 |
|
|||
|
|
| 不设邀请人数硬上限 | 低频场景（1-3人常见），>10人弹窗提醒而非阻断 |
|