# 邀请功能 — 技术方案

> **场景**：坐席在处理会话时需要拉入其他员工/部门协助，通过邀请功能将新人加入同一会话。
>
> **与"摇人"的区别**：摇人是坐席→坐席的协作（`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人弹窗提醒而非阻断 |