wecom_it_smart_desk/docs/PRD.md

# 企微IT智能服务台 — 产品需求文档 (PRD)

> **文档版本**: v1.0
> **创建日期**: 2025-07-11
> **最近更新**: 2026-06-10
> **产品经理**: 许清楚 (Xu) · 宋献
> **状态**: 阶段一开发完成，待端到端验证
> **说明**: 本文档已合并原 `PRD-v53-incremental.md` 内容（v5.3 坐席工作台增量需求）。v1.0 更新：新增管理后台远景规划（§18）、系统生态与集成规划（§19）、阶段细化与并行推进策略（§20）；明确管理后台为第三端产品；确立 AI 混合策略（流程图+AI+标注+迭代）；将阶段一细化为 1A/1B/1C 子阶段；新增零基础人员原则。v1.1 更新：新增邀请功能设计（§21），将邀请功能纳入M1 MVP（1A子阶段），新增P0-09~P0-11和P1-14~P1-16需求。

---

## 目录

1. [项目信息](#1-项目信息)
2. [项目背景](#2-项目背景)
3. [方案可行性判断](#3-方案可行性判断)
4. [产品定义](#4-产品定义)
5. [五阶段演进路径](#5-五阶段演进路径)
6. [需求池](#6-需求池)
7. [并行协作模式](#7-并行协作模式)
8. [界面设计](#8-界面设计)
9. [摇人功能设计](#9-摇人功能设计)
10. [技术约束](#10-技术约束)
11. [数据模型核心设计](#11-数据模型核心设计)
12. [待确认问题](#12-待确认问题)
13. [里程碑与交付物](#13-里程碑与交付物)
14. [AI Wingman — 坐席智能辅助设计](#14-ai-wingman--坐席智能辅助设计)
15. [v5.3 坐席工作台增量需求](#15-v53-坐席工作台增量需求)
16. [附录 A: 术语表](#附录-a-术语表)
17. [附录 B: 企微API关键接口](#附录-b-企微api关键接口)
18. [管理后台远景规划](#18-管理后台远景规划)
19. [系统生态与集成规划](#19-系统生态与集成规划)
20. [阶段细化与并行推进策略](#20-阶段细化与并行推进策略)
21. [邀请功能设计 — 多人会话协作](#21-邀请功能设计--多人会话协作)

| 字段 | 值 |
|------|------|
| 项目名称 | `wecom_it_smart_desk` |
| 编程语言 | 后端: FastAPI + Redis + PostgreSQL / 前端: Vue3 + ElementPlus |
| 部署环境 | Linux 服务器 (4核8GB+), Docker |
| 文档语言 | 中文 |
| 原始需求 | 基于企微自建应用消息API，自研IT服务坐席系统，替代企微"员工服务"模块，解决员工体验（绕过AI/另开窗口/无法跨主体）和管理人效（质量不稳定/成长慢/经验流失/缺乏数据）七项痛点 |

---

## 2. 项目背景

公司是一家约6000人的上市公司，全国主要城市设有分子机构，使用企业微信作为内部即时通讯系统。

### 2.1 现有生产环境现状

公司已通过企微AI机器人API接口与本地化千问模型、RAGFlow、Dify实现智能IT助手回答内部员工IT咨询。转人工环节使用关键字命中后返回企微员工服务功能跳转链接。

**现有系统架构**：

```
┌────────────────────────────────────────────────────────────────┐
│                    现有生产环境架构                               │
│                                                                │
│  员工 ←─1对1消息─→ 企微AI机器人应用                               │
│                       │                                        │
│                       ├─ AI回复 → RAGFlow + Dify + 千问          │
│                       │    （知识库语义检索 + 大模型生成）            │
│                       │                                        │
│                       ├─ 关键字触发 → 推送"员工服务"入口链接          │
│                       │    （如输入"转人工"/"人工"等关键字）          │
│                       │                                        │
│                       └─ 员工点击链接 → 跳转企微-员工服务-桌面IT支持   │
│                            （新窗口，人工坐席处理）                  │
│                                                                │
│  企微-员工服务-桌面IT支持：                                       │
│    · 企微内置客服模块，员工服务号接入                               │
│    · 排队分配 → 人工坐席1对1对话                                   │
│    · 无AI辅助、无知识管理、无数据统计                               │
└────────────────────────────────────────────────────────────────┘
```

**现有系统组成**：

| 组件 | 说明 | 状态 |
|------|------|------|
| 企微AI机器人 | 企微自建应用，1对1消息交互 | 已上线运行 |
| RAGFlow | 检索增强生成引擎，知识库语义检索 | 已上线运行 |
| Dify | AI应用开发平台，编排千问模型 | 已上线运行 |
| 千问（通义） | 阿里云大模型，AI回复生成 | 已上线运行 |
| 企微-员工服务 | 企微内置客服模块，人工坐席服务 | 已上线运行 |
| 关键字触发转人工 | 输入指定关键字后推送员工服务链接 | 已上线运行 |

**现有系统核心问题**：

| # | 问题 | 现状描述 |
|---|------|---------|
| 1 | AI→人工跳转割裂 | 关键字触发后仅推送链接，员工需手动点击跳转到"员工服务"新窗口 |
| 2 | 无法强制AI前置 | 员工可直接进入"员工服务"入口绕过AI，AI筛选比例低 |
| 3 | 坐席无AI辅助 | 人工坐席在"员工服务"模块中纯手动回复，无智能推荐、无快速回复 |
| 4 | 知识无法积累 | 坐席个人经验无法沉淀，AI知识库与坐席实际工作脱节 |
| 5 | 无数据闭环 | 缺乏坐席绩效、AI回答质量、员工满意度的量化数据 |
| 6 | 跨主体不可达 | "员工服务"模块不支持互联企业，跨企业员工无法使用 |

### 2.2 痛点分析

### 2.2 痛点分析

> **痛点归纳说明**：将原7条痛点归纳为4条核心痛点，每条对应明确的解决阶段，便于追溯开发升级功能的针对性。

| # | 核心痛点 | 具体表现（归纳自原痛点） | 影响 | 解决阶段 |
|---|---------|----------------------|------|---------|
| 1 | **员工入口体验差** | ①员工可绕过AI直达人工，AI筛选比例极低；②转人工需另开新窗口，体验割裂；③AI机器人和员工服务无法跨主体共享，跨企业服务不可达 | AI使用率低，员工困惑，服务覆盖范围受限 | **阶段二** |
| 2 | **坐席能力不稳定** | ①坐席回复质量依赖个人能力和经验，受情绪/状态影响；②实习生成长慢，辅导老师投入大但产出低，知识传承断档 | 服务质量参差不齐，人才培养投入产出比低 | **阶段三** |
| 3 | **知识无法积累传承** | 坐席个人经验和成果无法有效积累、传承、迭代更新，人员离职即经验流失 | 团队整体能力无法持续提升，重复踩坑 | **阶段四** |
| 4 | **管理缺乏数据支撑** | 坐席能力和绩效、IT支持员工满意度缺乏有效数据支撑，管理决策凭感觉 | 无法量化评估和持续优化，管理盲区大 | **阶段四** |

> **核心约束**: 所有对象都是企业内员工，必须避免使用企微微信客服能力。

> **痛点与阶段映射**: 痛点1（员工体验层）→ 阶段二解决；痛点2（坐席能力层）→ 阶段三解决；痛点3~4（管理迭代层）→ 阶段四解决。阶段五（自动/辅助审核开单结单）进一步解决多系统切换效率问题，提升整体人效。

---

## 3. 方案可行性判断

### 3.1 方案对比

> **对比基准**：新增"现有生产环境"行（企微AI机器人 + RAGFlow + Dify + 千问 + 员工服务），作为各方案的改进参照。

| 方案 | 痛点1<br>入口体验差 | 痛点2<br>能力不稳定 | 痛点3<br>知识不传承 | 痛点4<br>缺数据 | 推荐度 |
|------|:-:|:-:|:-:|:-:|--------|
| **现有：AI机器人+员工服务** | ❌ | ❌ | ❌ | ❌ | ⬅️ 对比基准 |
| 方式一：企微自建应用API + 员工服务转接 | ❌ | ❌ | ❌ | ❌ | ❌ 不推荐 |
| 方式二：企微自建应用消息 + 自研坐席后台 | ✅ | ✅ | ✅ | ✅ | ✅ 推荐 |
| 方式三：企微WebView嵌入 + 开源客服 | ⚠️ | ⚠️ | ❌ | ⚠️ | 有条件推荐 |
| **方式四：混合分阶段演进路径（H5优先）** | **✅** | **✅** | **✅** | **✅** | **✅ 当前推进方案** |
| 方式五：企微原生1对1 + 外援群聊 | ⚠️ | ✅ | ✅ | ✅ | 应急备选 |

> **说明**: 痛点1为体验层（方案对比核心维度），痛点2为坐席能力层，痛点3-4为管理与人效层（依赖自研坐席后台能力，方式一/三不具备）。
>
> **现有系统 vs 各方案的关键差异**：现有系统的"员工入口体验差"（可绕过AI、需另开窗口、无法跨主体）是最大体验短板。方式四通过H5 WebView在同一页面内完成AI→人工无缝切换，彻底解决此问题。

### 3.2 各方案原理与优劣

#### 方式一：企微自建应用API + 员工服务转接

**原理**：自建应用接收员工消息，通过企微"员工服务"模块的API将对话转接到人工坐席。员工在自建应用中与AI对话，转人工时跳转到企微"员工服务"窗口。

| 优点 | 缺点 |
|------|------|
| 开发量最小，复用企微现有员工服务能力 | 仍需另开窗口（员工服务与自建应用是两个独立窗口） |
| 员工服务模块有基础的排队、分配功能 | 无法强制AI前置筛选，员工可直接进入员工服务 |
| | 无法跨主体共享（员工服务模块不支持互联企业） |
| | 无自研坐席后台，痛点2-4无法解决 |

**结论**：❌ 不推荐 — 本质上只是给现有流程加了一层AI入口，核心痛点（员工入口体验差、坐席能力不稳定、无人效管理）均未解决。

#### 方式二：企微自建应用消息 + 自研坐席后台

**原理**：完全基于企微自建应用消息API，员工在自建应用中发消息，后端接收回调后路由至AI或坐席。坐席使用自研工作台处理会话，回复通过 `/message/send` 推送回员工端。

| 优点 | 缺点 |
|------|------|
| 消息路由完全可控，可强制AI前置筛选 | 员工端体验受限于企微应用消息格式 |
| 自研坐席后台，全面解决痛点2-4 | 开发量较大（坐席工作台 + 员工端 + 后端） |
| 支持跨主体（互联企业应用共享） | |
| 消息全量经后端，天然存档 | |

**结论**：✅ 推荐 — 技术路线正确，是方式四/五的架构基础。

#### 方式三：企微WebView嵌入 + 开源客服

**原理**：在自建应用中嵌入WebView加载开源客服系统（如 Chatwoot），员工在H5页面内完成AI+人工全流程对话。

| 优点 | 缺点 |
|------|------|
| 开源客服系统提供现成UI和管理后台 | 无法强制AI前置筛选（员工可直接联系人工） |
| 跨主体可通过H5嵌入其他平台实现 | 开源客服难以深度定制坐席智能辅助功能 |
| | 开源客服的知识管理和数据能力有限，痛点3-4覆盖不足 |
| | 员工端依赖WebView，体验不如原生 |

**结论**：有条件推荐 — 适合快速验证MVP，但长期来看坐席侧能力受限于开源客服的上限。

#### 方式四：混合分阶段演进路径（H5优先）⭐ 当前推进方案

**原理**：基于方式二的架构，员工端采用 H5 WebView（Vue3 + Vant4）嵌入企微自建应用，坐席端采用自研工作台（Vue3 + Element Plus）。消息流全量经后端路由，支持AI前置筛选、AI-人工无缝切换、跨主体扩展。

```
┌─────────────────────────────────────────────────────────────────┐
│                       员工端（H5 WebView）                        │
│                                                                    │
│  员工 ──消息──→ 企微自建应用 H5 页面                                 │
│                     │                                              │
│                     ├─ AI回复 → H5 内气泡显示（同一对话流）           │
│                     ├─ 转人工 → H5 内无缝切换（同一对话流）           │
│                     ├─ 摇人按钮 → 一键呼叫坐席                       │
│                     └─ 满意度评分 → H5 内评分组件                    │
│                                                                    │
└─────────────────────────────────────────────────────────────────┘
                              ↕ WebSocket + REST API
┌─────────────────────────────────────────────────────────────────┐
│                      坐席端（自研工作台）                           │
│                                                                    │
│  坐席 ←── 会话列表（按紧急度排序）                                   │
│       ├── 聊天区（AI建议内联 + 快速回复 + 排查步骤）                  │
│       ├── 用户信息栏（IT等级徽标 + VIP标记）                         │
│       └── 待办面板（工单/审批/设备任务）                             │
│                                                                    │
└─────────────────────────────────────────────────────────────────┘
                              ↕
┌─────────────────────────────────────────────────────────────────┐
│                        后端服务                                    │
│                                                                    │
│  消息路由层（强制AI前置）→ Dify/RAGFlow → 评分 → 分配坐席            │
│  快速回复知识库（180条模板）→ 排查步骤模板 → 摇人调度                 │
│                                                                    │
└─────────────────────────────────────────────────────────────────┘
```

**核心交互路径**：

| 阶段 | 交互路径 | 员工端体验 |
|------|---------|-----------|
| AI 自助 | 员工发消息 → 后端路由 → Dify/RAGFlow → H5 内气泡 | AI回复在**同一对话流**中显示 |
| 转人工触发 | AI回复N轮后触发 / 员工点击"摇人"按钮 / 关键词匹配 | **同一对话流**内无缝切换，无跳转 |
| 坐席介入 | 坐席工作台接收会话 → AI推荐回复 → 快速回复 | 员工端仍在**同一对话流**中收到人工回复 |
| 满意度评分 | 会话结束 → H5 内评分组件弹窗 | 原地评分，无需跳转 |

**五阶段演进路径**（详见 §5）：

| 阶段 | 目标 | 员工端 | 坐席端 | AI能力 |
|------|------|--------|--------|--------|
| 阶段一 | 转人工改H5+坐席工作台MVP | H5 登录+身份识别 + 转人工链接改H5 | 自研工作台MVP（会话列表+聊天+快速回复） | 不变（复用现有） |
| 阶段二 | 智能咨询集成 | H5 全流程 + 敲桌子 + 评分 | 三栏工作台MVP + AI建议 + 快速回复 | AI前置筛选 + 双通道推送 |
| 阶段三 | 坐席辅助回复/判断 | H5 体验优化 | AI Wingman（草稿+摘要+知识+排查步骤） | 千问深度集成 |
| 阶段四 | 日志标准+知识库迭代 | H5 跨平台扩展 | 绩效看板 + AI知识库自动迭代 | AI知识库自学习闭环 |
| 阶段五 | 自动/辅助审核开单结单 | H5 一站式 | 待办面板 + AI填单 + AI审核 + AI结单 | AI流程自动化 |

| 优点 | 缺点 |
|------|------|
| H5 员工端可做丰富的交互UI（评分/摇人/AI标识） | 员工需进入H5页面，非原生聊天体验 |
| 消息路由完全可控，可强制AI前置筛选 | 依赖WebView加载，有网络延迟 |
| 自研坐席后台，全面解决痛点4-7 | H5 需OAuth2鉴权（多一步跳转） |
| 支持跨主体（H5可嵌入其他企微主体/平台） | 开发量最大（员工端+坐席端+后端） |
| 一次开发，可扩展到钉钉/飞书/浏览器 | 通知依赖H5页面是否打开（不如原生必达） |
| AI/人工身份清晰区分（UI可做丰富标识） | |

**H5 端实时消息推送方案**：

方式四的 H5 员工端存在一个关键体验问题——坐席回复消息后，H5 页面需要实时刷新才能显示新消息。当前已实现的消息到达机制如下：

| 机制 | 实现状态 | 体验 |
|------|---------|------|
| 企微应用消息推送（`/message/send`） | ✅ 已实现 | 坐席发消息 → 企微系统级通知弹窗/红点 → 员工**点击通知**回到 H5 → 页面拉取新消息 |
| H5 轮询（`/h5/conversations/current/messages/poll`） | ✅ 已实现 | 前端每 3-5 秒请求一次新消息，延迟明显 |
| H5 WebSocket 实时推送 | 🔲 待开发 | 坐席发消息 → 后端推送 → H5 聊天区**秒级自动刷新**，体验最佳 |

**双通道通知策略**（推荐上线方案）：

```
坐席发送消息
    ├── 通道1: 企微 /message/send → 系统级通知（保证必达）
    │     → 员工未在 H5 页面时，收到企微通知弹窗
    │     → 员工已关闭 H5 时，仍可通过通知回到对话
    │
    └── 通道2: WebSocket 推送 → H5 页面内实时更新（保证即时）
          → 员工在 H5 页面时，聊天区秒级刷新
          → 页面未打开时，WebSocket 断连，自动降级为通道1
```

**WebSocket 推送技术方案**：

| 项目 | 说明 |
|------|------|
| 后端 | 扩展现有 `ws_manager.py`（已管理坐席 WS 连接），新增 `employee` 类型连接注册 |
| WS 端点 | `GET /api/h5/ws?token={bearer_token}` — H5 前端通过 Bearer Token 鉴权连接 |
| 消息格式 | `{"type": "new_message", "data": {"id": "...", "content": "...", "sender_type": "agent"}}` |
| 断连降级 | WebSocket 断连时，前端自动切换为轮询（现有 `/messages/poll` 兜底） |
| 重连策略 | 指数退避重连（1s → 2s → 4s → 8s → 最大 30s），断连期间消息由通道1保证 |
| 前端 | `frontend-h5/` 新增 `composables/useWebSocket.ts`，监听推送事件自动追加消息 |

**与现有系统对比**：

| 维度 | 现有生产环境 | 方式四（H5 + 双通道推送） |
|------|------------|------------------------|
| AI→人工切换 | 关键字触发 → 推送链接 → 跳转新窗口 | H5 内同一对话流无缝切换 |
| 人工回复通知 | 企微员工服务自带通知（原生窗口） | 企微系统通知 + H5 WebSocket 双通道 |
| 回复即时性 | 原生1对1窗口，即时 | WebSocket 秒级推送（H5 页面内）/ 企微通知（H5 未打开时） |
| 消息存档 | 企微员工服务存档（需开通会话存档权限） | 全量经后端，天然存档，无额外权限 |

**关键企微 API**：

| API | 路径 | 用途 | 关键限制 |
|-----|------|------|---------|
| 发送应用消息 | `/cgi-bin/message/send` | 通知/提醒推送到企微 | ≤账号上限×200人次/天 |
| 接收消息回调 | 自建应用回调URL | 接收员工发给应用的消息 | 需公网HTTPS回调URL |
| 构造网页授权链接 | `/cgi-bin/oauth2/authorize` | H5页面识别员工身份 | 需配置可信域名 |
| 互联企业应用共享 | 企微管理后台 | 跨主体员工使用同一应用 | 需双方管理员审批 |

**结论**：✅ 当前推进方案 — 全面解决7项痛点，生态扩展性最强，分阶段演进风险可控。

#### 方式五：企微原生1对1 + 外援群聊（应急备选方案）

> **定位**：非主推方案。当方式四的AI服务（Dify/RAGFlow）出现故障不可用时，作为**应急预案**切换至方式五，利用企微原生1对1消息维持基本服务。若方式四整体故障（坐席工作台也不可用），则退回"企微-员工服务-桌面IT支持"仅有人工坐席最简方式。

**原理**：员工直接在企微原生聊天窗口与自建应用1对1对话，AI和坐席回复均通过 `/message/send` 推送到同一窗口。外援场景通过 `/appchat/create` 创建群聊。

```
┌──────────────────────────────────────────────────────────────┐
│                    员工端（企微原生聊天窗口）                     │
│                                                               │
│  员工 ←─1对1消息─→ 自建应用（IT智能助手）                         │
│                      │                                        │
│                      ├─ AI回复 → /message/send → 同一窗口       │
│                      ├─ 坐席回复 → /message/send → 同一窗口     │
│                      │  （员工无感知AI/人工切换）                  │
│                      │                                        │
│                      └─ 外援场景 → /appchat/create → 新群聊窗口  │
│                                                               │
└──────────────────────────────────────────────────────────────┘
```

| 优点 | 缺点 |
|------|------|
| **应急价值高**：AI故障时可快速切换，员工仍可通过原生窗口获得人工服务 | 无法跨主体（仅同一企微主体内） |
| 员工端零开发量（原生聊天窗口） | AI/人工身份需消息前缀区分（如"[人工-张三]"） |
| 体验最优（与日常聊天无差异，通知必达） | 员工可直接1对1联系应用，绕过AI前置筛选 |
| 消息全量经后端API，天然存档 | 绑定企微生态，无法扩展到其他平台 |
| 外援走原生群聊，低频且轻量 | 满意度评分只能用模板卡片（体验不如H5评分组件） |

**关键企微 API**：

| API | 路径 | 用途 | 关键限制 |
|-----|------|------|---------|
| 发送应用消息 | `/cgi-bin/message/send` | AI/坐席向员工推送消息（主流程） | ≤账号上限×200人次/天，同一人≤30次/分 |
| 接收消息回调 | 自建应用回调URL | 接收员工发给应用的消息 | 需公网HTTPS回调URL |
| 创建群聊 | `/cgi-bin/appchat/create` | 外援场景：创建多方协作群 | ≤1000群/天，≤2000人/群 |
| 修改群聊 | `/cgi-bin/appchat/update` | 外援群管理（加人/改名） | ≤1000次/小时 |
| 获取群聊 | `/cgi-bin/appchat/get` | 查询群聊信息 | 仅本应用创建的群 |
| 推送群消息 | `/cgi-bin/appchat/send` | 群内推送消息（9种类型） | ≤2万人次/分 |

**方式四 vs 方式五详细对比**：

| 维度 | 方式四：H5 WebView（当前方案） | 方式五：原生1对1 + 外援群聊（应急备选） |
|------|-------------------------------|---------------------------------------|
| **员工入口** | 点击应用 → 进入 H5 页面 | 直接在企微与应用1对1聊天 |
| **对话体验** | H5 内部输入框，需切换上下文 | **原生聊天窗口，与日常聊天无差异** |
| **通知必达** | 依赖 H5 是否打开 | **企微原生推送，必达** |
| **富媒体支持** | H5 自定义 UI（需开发） | **原生支持6种输入+10种输出** |
| **前端开发量** | 大（Vue3+Vant4 H5 客户端） | **零（员工端无前端）** |
| **OAuth2 鉴权** | 必须（H5 需识别用户身份） | **不需要（回调自带 UserID）** |
| **跨平台移植** | **✅ H5 可挂载钉钉/飞书/浏览器等** | ❌ 绑定企微 |
| **跨主体企微支持** | **✅ 可，非静默登录时提供其他认证** | ❌ 仅同一企微主体内 |
| **AI/人工区分** | **✅ H5 可做丰富身份标识** | ⚠️ 需消息内容前缀区分（如"[人工-张三]"） |
| **转人工触发** | H5 内按钮（`ai_substantive_reply_count >= 3`） | 关键词"转人工" / 交互卡片按钮 |
| **满意度评分** | H5 内评分组件 | 模板卡片消息（按钮交互型） |
| **消息存档** | 全量经后端，天然存档 | **全量经后端（AI+坐席都走API），无需会话存档权限** |
| **外援/摇人** | 需额外设计 | **原生群聊(appchat)，新窗口** |
| **坐席工作台** | 保留 | 保留 |

**结论**：方式五体验最优但受限于企微主体内，定位为**应急备选方案**。当方式四的AI服务故障时切换使用，维持基本服务能力。

### 3.3 降级应急预案

当方式四（主方案）出现不同级别的故障时，按以下降级链路逐步回退：

```
方式四（正常）→ 方式五（AI故障，保留坐席工作台+原生1对1）→ 企微员工服务（仅人工坐席最简方式）
```

| 降级级别 | 触发条件 | 员工端变化 | 坐席端变化 | 恢复条件 |
|----------|---------|-----------|-----------|---------|
| **L0 正常** | 全部服务可用 | H5 完整体验 | 自研工作台全功能 | — |
| **L1 AI降级** | Dify/RAGFlow 不可用 | H5 内自动跳过AI，直接进入人工排队 | 工作台AI推荐/快速回复不可用，手动回复 | AI服务恢复 |
| **L2 方式五切换** | H5服务整体故障 | 切换至企微原生1对1消息（方式五） | 工作台仍可用，回复通过API推送到员工原生窗口 | H5服务恢复 |
| **L3 完全回退** | 坐席工作台也不可用 | 退回"企微-员工服务-桌面IT支持" | 使用企微员工服务后台手动处理 | 全部服务恢复 |

> **核心架构决策**: 彻底放弃企微"员工服务"模块，用自建应用消息API + 自研坐席服务台替代整个链路
> **消息路由**: 自建应用消息回调到自己服务器，所有消息先到路由层，可强制新会话默认进AI模式
> **跨企业**: 通过企微"互联企业"应用共享实现（方式四），或H5嵌入其他平台实现

---

## 4. 产品定义

### 4.1 产品目标

1. **提高AI首答率**: 通过消息路由层强制新会话先走AI，将AI筛选比例从当前低位提升至80%以上，降低人工坐席负载
2. **统一对话体验**: 员工从AI对话到人工服务在同一窗口无缝流转，消除跳转割裂感
3. **构建AI-人工协作闭环**: 建立坐席标注→知识库迭代的正向循环，持续提升AI解答质量

### 4.2 用户故事

| # | 角色 | 故事 | 验收标准 |
|---|------|------|---------|
| US-1 | 普通员工 | 我希望在企微应用中直接咨询IT问题，AI先回答，需要人工时无需切换窗口即可转接 | AI回复和人工回复在同一对话流中连续显示 |
| US-2 | 普通员工 | 我希望通过"摇人"一键呼叫IT坐席，不需要记住关键词 | 摇人按钮在输入框左侧，点击即触发转人工流程 |
| US-3 | IT坐席 | 我希望看到一个按紧急度排序的会话列表，优先处理最紧急的问题 | 会话列表按紧急→举手→需介入→活跃→AI处理中→已结单排序 |
| US-4 | IT坐席 | 我希望AI能在旁边给我建议回复和操作步骤，我可以采纳或修改 | AI建议条显示在对话区，支持采纳/编辑后采纳/忽略 |
| US-5 | IT主管 | 我希望坐席在日常工作中标注AI回复的准确性，系统能自动分析知识库缺陷 | 标注嵌入坐席工作流，千问自动分析生成优化建议 |
| US-6 | VIP员工 | 我希望我的问题能被优先处理 | VIP标记自动匹配，会话紧急度加成，列表优先展示 |
| US-7 | 跨企业员工 | 我希望在母公司的企微应用中也能使用IT服务 | 通过企微互联企业应用共享，跨主体员工可使用同一服务 |

---

### 4.3 竞品分析与差异化定位

> **新增日期**: 2026-06-14

#### 4.3.1 四大竞品对标

| 竞品 | 类型 | 核心能力 | 我们的差异化优势 |
|------|------|----------|------------------|
| **钉钉·智能客服** | 平台内置 | AI问答、工单、会话分析 | **私有化部署 + 企微深度集成** + 坐席工作台自定义 |
| **美团·IT服务台** | 自研 | 报修工单、资产盘点、BI看板 | **终端安全集成**（火绒+联软）+ 免费开源 |
| **飞书·IT运维** | 插件生态 | 审批流、资产、知识库 | **企业微信原生** + AI混合策略 |
| **Jira Service Management** | 商业SaaS | ITSM、资产管理、SLA | **本土化免费** + 国有大模型集成 |

#### 4.3.2 市场定位

> **一句话定位**: 融合服务台+资产+终端安全的**企业级ITSM**，基于企微生态的免费开源解决方案。

| 维度 | 定位说明 |
|------|----------|
| **目标客户** | 6000人左右的中大型企业，使用企微作为办公通讯 |
| **核心价值** | 免费开源 + 私有化部署 + 终端安全一体化 |
| **差异化标签** | AI驱动 · 多系统对接 · 一站式处理 |
| **定价策略** | 社区版免费，专业版定制收费 |

#### 4.3.3 竞争优势

| 优势 | 说明 |
|------|------|
| **企微深度集成** | 原生OAuth2、企业API、消息推送、通讯录同步 |
| **终端安全联动** | 火绒+联软API直连，威胁自动响应 |
| **免费开源** | MIT协议，社区支持，降低采购阻力 |
| **AI混合策略** | 流程图+AI生成+坐席标注+自动迭代 |

#### 4.3.4 风险与挑战

| 风险 | 等级 | 应对策略 |
|------|------|----------|
| 企微API限制 | 中 | 保持降级通道（企微员工服务） |
| 集成复杂度 | 高 | 分阶段交付，MVP先行 |
| 社区活跃度 | 低 | 先在内部打磨，文档完善后开源 |

---

### 4.4 功能优先级 (MoSCoW)

> **新增日期**: 2026-06-14

#### Must have (P0 - MVP必须)

| 功能 | 说明 | 阶段 |
|------|------|------|
| AI对话 | 员工在H5中咨询IT问题，AI回答 | 阶段1 |
| 转人工 | AI无法解决时一键转人工坐席 | 阶段1 |
| 坐席工作台 | 会话列表+聊天+快速回复 | 阶段1 |
| 消息推送 | 企微消息实时到达 | 阶段1 |
| 身份识别 | OAuth2企微登录 | 阶段1 |

#### Should have (P1 - 第一版应该有)

| 功能 | 说明 | 阶段 |
|------|------|------|
| 摇人按钮 | 输入框左侧一键呼叫坐席 | 阶段2 |
| 满意度评价 | 会话结束后评价 | 阶段2 |
| 排队系统 | 多会话时排队等待 | 阶段2 |
| 快速回复 | 坐席常用语管理 | 阶段2 |
| 知识库(基础) | FAQ手动维护 | 阶段2 |

#### Could have (P2 - 最好有)

| 功能 | 说明 | 阶段 |
|------|------|------|
| AI Wingman | AI建议回复 | 阶段3 |
| 会话标注 | 坐席标注AI回复准确性 | 阶段3 |
| 自动摘要 | 会话结束后AI摘要 | 阶段3 |
| 数据看板 | 基础统计 | 阶段4 |
| 知识库自动迭代 | AI分析+知识库更新 | 阶段4 |

#### Won't have (暂缓)

| 功能 | 说明 | 阶段 |
|------|------|------|
| 工单系统 | 开单/审批/结单 | 阶段5 |
| 资产联动 | 联软资产集成 | 阶段5 |
| 终端安全 | 火绒终端集成 | 阶段5 |
| 跨企业共享 | 企微互联 | 未来 |

---

### 4.5 推广计划

> **新增日期**: 2026-06-14

#### 5阶段推广节奏

| 阶段 | 时间 | 目标 | 策略 |
|------|------|------|------|
| **封闭内测** | 第1-2周 | 30人IT部门 | 邀请制，收集反馈，优化体验 |
| **全员试用** | 第3-4周 | 200人种子用户 | 企微群推广，管理员推动 |
| **正式上线** | 第5-6周 | 1000人 | 培训+推广材料 |
| **功能扩展** | 第7-12周 | 3000人 | 阶段2功能，推广摇人+评价 |
| **生态构建** | 第3-6月 | 6000人 | 阶段3-4，数据驱动优化 |

#### 推广关键指标 (KPI)

| 指标 | 目标值 | 说明 |
|------|--------|------|
| AI首答率 | ≥80% | AI直接解决的比例 |
| 人工平均响应 | ≤60s | 从提交到坐席响应的平均时间 |
| 会话满意度 | ≥4.5★ | 5分制评价 |
| 问题解决率 | ≥90% | AI+人工最终解决的比例 |
| 坐席人均处理 | ≤30/天 | 坐席日均处理会话数 |

#### 推广资源需求

| 资源 | 说明 |
|------|------|
| IT支持组 | 3人坐席值班 |
| 培训材料 | 5分钟入门视频+图文手册 |
| 推广文案 | 企微公告+海报 |
| 激励机制 | 满意度前10%奖励 |

---

## 5. 五阶段演进路径

> **演进原则**：每个阶段都基于现有生产环境（企微AI机器人 + RAGFlow + Dify + 千问）进行增量升级，不做大爆炸式替换。现有AI机器人持续运行直到新系统对应阶段稳定上线。

### 5.1 阶段总览

| 阶段 | 目标 | 核心变更 | 解决痛点 | 现有系统影响 |
|------|------|---------|---------|------------|
| **阶段一** | 转人工改H5+坐席工作台MVP | AI机器人转人工链接从"员工服务"改为H5自建应用，员工端解决登录和身份识别，坐席端交付自研工作台MVP（会话列表+聊天+快速回复），AI能力不变 | 痛点1（部分）、坐席摆脱员工服务限制 | AI转人工链接从员工服务改为H5，原有1对1窗口保留为降级通道 |
| **阶段二** | 迁移和集成面向员工的智能咨询功能 | H5员工端完整体验（AI对话+转人工+摇人+评分），双通道消息推送 | **痛点1** | 员工服务入口逐步迁移至H5 |
| **阶段三** | 面向坐席的辅助回复和辅助判断 | 坐席工作台 AI Wingman（草稿回复+自动摘要+知识推荐+排查步骤） | **痛点2** | 坐席从员工服务后台切换至自研工作台 |
| **阶段四** | 日志标准和AI知识库迭代 | 会话标注体系 + AI知识库自动迭代闭环 + 数据统计看板 | **痛点3~4** | AI知识库从人工维护升级为自动迭代 |
| **阶段五** | 自动/辅助审核、开单、结单 | 工单/审批/设备异常一站式处理 + AI辅助填单+自动结单 | 多系统切换效率问题 | 替代多系统切换，统一工作台闭环 |

### 5.2 各阶段详细规划

#### 阶段一：转人工改H5 + 坐席工作台MVP

> **本阶段解决痛点**：坐席摆脱企微员工服务限制（为阶段二解决痛点1打基础）。
>
> **关键前提**：企微AI机器人 + Dify + RAGFlow + 千问**已在生产环境运行**，本阶段不做任何AI引擎改动，仅改变转人工环节的链接指向和坐席端工具。

**目标**：现有AI机器人继续运行（不动），仅将转人工的链接从"企微员工服务"改为H5自建应用；员工端解决OAuth2登录和身份识别；坐席端交付自研工作台MVP（会话+快速回复），摆脱企微内置员工服务的限制。坐席端AI能力**暂不接入**。

**现状 → 目标对比**：

| 维度 | 现有生产环境 | 阶段一目标 |
|------|------------|----------|
| AI机器人 | 企微1对1对话，RAGFlow+Dify+千问（**不变**） | 企微1对1对话，RAGFlow+Dify+千问（**不变**） |
| 转人工 | 关键字触发 → 推送"企微员工服务"链接 → 跳转新窗口 | 关键字触发 → 推送H5自建应用链接 → 同一WebView内切换 |
| 员工端 | 无独立身份识别，员工服务窗口无登录 | H5 WebView（OAuth2静默授权 → 身份识别） |
| 坐席端 | 企微内置员工服务后台（功能受限） | 自研工作台MVP，摆脱员工服务限制 |
| 坐席快速回复 | 无（纯手动输入） | 三级导航快速回复面板（7大类28子类180条模板） |
| 坐席AI能力 | 无 | **暂不接入**（阶段三引入） |

**范围**：

**员工端（H5 WebView，Vue3 + Vant4）**：
- 自建应用创建 + H5页面基础框架
- OAuth2 静默授权 → 员工身份识别（核心）
- 接收坐席消息的展示（人工回复在H5页面显示）
- 企微应用消息推送（坐席回复通过 `/message/send` 推送企微通知）

**坐席端（自研工作台MVP，Vue3 + Element Plus）**：
- 会话列表（显示进行中的会话，按时间排序）
- 聊天窗口（显示完整对话记录，可回复）
- 发送消息（文本消息发送）
- 快速回复面板（三级渐进导航：7大类→28子类→180条模板，数字键快捷操作）
- **邀请功能**（坐席邀请其他员工/部门加入会话，详见§21）
- 摆脱企微员工服务限制，坐席使用独立工作台处理会话
- **不含AI能力**（AI建议、排查步骤等留到阶段三）

**后端变更**：
- AI机器人转人工链接配置：从"员工服务"改为H5自建应用URL
- 坐席WebSocket连接管理（复用现有 `ws_manager.py`）
- 消息路由：AI对话→关键字触发→创建人工会话→分配坐席

**完成标准**：员工在企微与AI机器人对话 → 关键字触发转人工 → 推送H5链接 → 员工点击进入H5页面（OAuth2自动登录） → 坐席在自研工作台收到会话 → 坐席使用快速回复或手动输入回复 → 员工在H5页面看到人工回复；坐席可邀请其他员工/部门加入会话协作 → 被邀请人收到企微通知 → 通过H5链接加入 → 多人同一会话协作

**开发周期**：6-8周

#### 阶段二：迁移和集成面向员工的智能咨询功能

> **本阶段解决痛点**：痛点1（员工入口体验差：可绕过AI、另开窗口、无法跨主体）。

**目标**：完善H5员工端全流程体验，实现AI→人工无缝切换，取代关键字触发跳转链接的转人工方式，并增强坐席工作台能力（仍不含AI）。

**现状 → 目标对比**：

| 维度 | 阶段一 | 阶段二目标 |
|------|--------|----------|
| 转人工方式 | 关键字触发 → 推送H5链接（同一WebView切换） | H5内"敲桌子"按钮/摇人 → 同一对话流切换 |
| 人工回复到达 | 坐席自研工作台回复 → 员工H5页面查看（轮询） | H5内WebSocket实时推送 + 企微通知双通道 |
| AI→人工切换 | 关键字触发，两个窗口（AI对话+人工H5） | 同一对话流，AI历史+人工回复连续显示 |
| 坐席端能力 | 基础MVP（会话列表+聊天+快速回复） | 用户信息栏 + 会话标记 + 排队显示（不含AI） |
| 满意度评分 | 无 | H5内评分组件，会话结束后弹出 |
| 排队系统 | 无 | 等待坐席接入的排队机制，含等待提示 |

**范围**：

**员工端（H5）**：
- H5 "敲桌子/摇人"按钮 + 转人工触发逻辑（AI实质性回复≥3轮）
- H5 WebSocket 实时推送（双通道通知策略）
- 满意度评分组件
- AI→人工同一对话流无缝切换

**坐席端（工作台增强，不含AI）**：
- 用户信息栏（员工基本信息、IT等级徽标）
- 会话标记系统（VIP/举手/需介入/情绪标记）
- 会话列表增强（按紧急度排序、标记显示）
- 排队信息展示

**后端**：
- 消息路由层优化：新会话→AI优先，AI判断/用户触发→坐席队列
- 排队系统 + 等待提示
- 会话状态增强（排队中/服务中/已结单 + 标记）

**完成标准**：员工H5内AI对话→敲桌子→坐席接入→人工回复→员工同一对话流看到→结单→评分

**开发周期**：5周

**开发计划**：

| 周 | 天数 | 内容 |
|----|------|------|
| 第1周 | D1-D5 | H5敲桌子/摇人 + 消息路由优化 + AI→人工切换 |
| 第2周 | D6-D10 | WebSocket推送 + 双通道通知策略 |
| 第3周 | D11-D15 | 坐席AI建议面板 + 用户信息栏 + 会话标记 |
| 第4周 | D16-D20 | 排队系统 + 满意度评分 |
| 第5周 | D21-D25 | 联调测试 + 现有系统切换 |

#### 阶段三：面向坐席的辅助回复和辅助判断

> **本阶段解决痛点**：痛点2（坐席能力不稳定：回复质量依赖个人能力、实习生成长慢）。

**目标**：坐席工作台引入AI Wingman（智能副驾驶），消灭重复劳动、增强认知能力。

**现状 → 目标对比**：

| 维度 | 阶段二 | 阶段三目标 |
|------|--------|----------|
| 坐席回复方式 | 纯手动输入 | AI草稿回复 + 快速回复模板 + 排查步骤 |
| 会话摘要 | 无 | AI自动生成结构化摘要（问题/原因/解决方案） |
| 知识获取 | 坐席自行搜索 | 基于对话上下文自动推送知识库文档 |
| 问题判断 | 依赖个人经验 | AI辅助判断 + 相似工单推荐 + SOP流程导航 |
| 新人上手 | 老带新，成长慢 | AI推荐回复降低认知负荷，上手周期缩短50% |

**范围**：
- AI Wingman 效率层：AI草稿回复（采纳/编辑/忽略）+ 自动摘要 + 自动标签
- AI Wingman 认知层：知识推荐 + SOP流程导航 + 相似工单 + 客户画像
- 排查步骤栏 + 决策树流程图
- 坐席端双区布局（内嵌区 + 侧栏区）
- 两个 Dify Agent（员工端AI + 坐席端Wingman）共用知识库

**完成标准**：坐席接会话→AI自动生成草稿→采纳/修改→发送；结单→自动摘要→确认存档

**开发周期**：4-6周

#### 阶段四：日志标准和AI知识库迭代

> **本阶段解决痛点**：痛点3（知识无法积累传承）+ 痛点4（管理缺乏数据支撑）。

**目标**：建立AI-人工协作闭环，坐席标注驱动AI知识库自动迭代，构建数据驱动的管理体系。

**现状 → 目标对比**：

| 维度 | 阶段三 | 阶段四目标 |
|------|--------|----------|
| AI回答质量保障 | 依赖坐席主观感受 | 坐席标注→AI自动分析→知识库自动优化 |
| 知识库维护 | 人工定期审查更新 | 千问自动分析标注数据，判断缺文档/信息过时 |
| 数据统计 | 无 | 坐席绩效看板 + AI回答质量看板 + 员工满意度统计 |
| 管理决策 | 凭感觉 | 数据支撑：响应时效/解决率/AI筛选率/知识库覆盖率 |

**范围**：
- 坐席标注AI回复正确/错误（嵌入日常工作流，不单独开标注页面）
- 千问自动分析待优化队列：缺文档→生成FAQ→推送RAGFlow；过时→标记→推送管理员审核
- 数据统计看板：坐席绩效/会话量/AI筛选率/员工满意度
- 日志标准：会话日志格式规范，支持后续审计和分析
- 跨企业共享（通过企微互联企业应用共享）

**完成标准**：坐席标注→千问分析→自动生成FAQ→推送RAGFlow→AI回答质量提升→闭环验证

**开发周期**：4-6周

#### 阶段五：自动/辅助审核、开单、结单

> **本阶段解决痛点**：多系统切换效率问题（延伸痛点4/5，进一步提升人效）。

**目标**：将工单/审批/设备异常等外部系统整合到坐席工作台，实现一站式闭环处理。

**现状 → 目标对比**：

| 维度 | 阶段四 | 阶段五目标 |
|------|--------|----------|
| 工单处理 | 坐席手动切到外部系统开单 | 坐席工作台内一键开单/结单 |
| 审批流程 | 坐席告知员工审批链接，员工自行操作 | 工作台内直接发起/审批 |
| 设备异常 | 坐席手动记录，另开系统处理 | 工作台内查看设备状态+派工+标记恢复 |
| 结单流程 | 坐席手动输入结单描述 | AI自动生成结单摘要→坐席确认→自动结单 |
| 审核机制 | 无 | AI辅助审核（检测遗漏步骤/不合规操作） |

**范围**：
- 待办事项面板（工单/审批/设备异常）
- 中间栏任务详情视图切换
- AI辅助填单（基于对话内容自动填写工单字段）
- AI辅助审核（检测遗漏步骤、不合规操作）
- AI辅助结单（自动生成结构化摘要）
- 外部系统API对接（ITSM/审批系统/设备管理）

**完成标准**：坐席接会话→AI辅助开单→处理→AI辅助审核→AI辅助结单→一站式闭环

**开发周期**：4-6周

### 5.3 阶段间降级兼容

> 每个阶段上线期间，现有生产环境必须保持可用，作为降级通道。

| 阶段 | 降级方案 | 触发条件 | 恢复条件 |
|------|---------|---------|---------|
| 阶段一 | 回退到原企微1对1AI机器人窗口 | H5页面无法访问 | H5服务恢复 |
| 阶段二 | 回退到关键字触发推送员工服务链接 | 坐席工作台故障 | 工作台恢复 |
| 阶段三 | 坐席关闭AI辅助，纯手动回复（功能降级，非切换） | Dify AI服务故障 | AI服务恢复 |
| 阶段四 | 数据统计暂时中断，坐席继续工作 | 分析服务故障 | 分析服务恢复 |
| 阶段五 | 回退到外部系统手动处理 | 工作台任务模块故障 | 模块恢复 |

---

## 6. 需求池 (Requirements Pool)

### P0 — Must Have（第一步必须交付）

| ID | 需求 | 说明 | 验收标准 |
|----|------|------|---------|
| P0-01 | 企微自建应用消息接收 | 通过企微回调URL接收员工消息 | 员工发送消息，服务器能收到并解析 |
| P0-02 | 企微自建应用消息发送 | 通过企微API向员工发送消息 | 服务器主动发消息，员工在企微应用中收到 |
| P0-03 | 消息路由层 | 所有消息先到路由层，按规则分发 | 新会话默认路由到坐席队列（第一步无AI） |
| P0-04 | 坐席会话列表 | 显示所有进行中的会话，含基本排序 | 按时间倒序，显示员工姓名、最后消息摘要 |
| P0-05 | 坐席对话区 | 显示选定会话的完整对话记录，可回复 | 消息实时显示，坐席可发送文本回复 |
| P0-06 | 员工同窗口体验 | 员工AI对话和人工服务在同一企微应用对话流 | 无需切换窗口，消息连续显示 |
| P0-07 | 会话状态管理 | 会话状态：排队中/服务中/已结单 | 数据库状态字段正确流转 |
| P0-08 | 测试环境隔离 | 在正式企微企业中测试可见范围隔离 | 测试用户可见，其他用户不可见 |
| P0-09 | 邀请功能-邀请发起 | 坐席在会话中可邀请其他员工/部门加入 | 坐席点击邀请→选人→确认→被邀请人收到企微通知 |
| P0-10 | 邀请功能-加入会话 | 被邀请人通过链接进入H5会话，可查看和回复 | 点击通知→H5加载→拉取历史→可发送消息 |
| P0-11 | 邀请功能-参与者管理 | 会话显示所有参与者，区分发起人/被邀请人 | 参与者列表可见，角色标识清晰 |

### P1 — Should Have（第一步应交付，第二步完善）

| ID | 需求 | 说明 | 验收标准 |
|----|------|------|---------|
| P1-01 | 会话标记系统 | VIP/举手/需介入/情绪标记 + 紧急度评分 | 标记在会话列表中正确显示，紧急度计算准确 |
| P1-02 | 会话列表排序 | 紧急→举手→需介入→活跃→AI处理中→已结单 | 排序规则生效，会话按紧急度排列 |
| P1-03 | VIP标记自动匹配 | 基于企微通讯录API规则匹配（总监及以上或关键部门） | 匹配规则可配置，VIP标记自动显示 |
| P1-04 | 举手标记 | 员工说"转人工"或关键词触发 | 关键词可配置，触发后自动举手 |
| P1-05 | 需介入标记 | 同一问题追问超过N轮(默认3轮)或AI判断需要人工 | N值可配置，自动触发标记 |
| P1-06 | 情绪标记（规则版） | 关键词规则匹配("急/紧急/马上/崩溃"等) | 关键词可配置，命中后自动标记 |
| P1-07 | 紧急度评分 | 公式：紧急度=基础分(关键词)+情绪加成+VIP加成+重复追问加成，1-5分映射 | 评分计算正确，映射为低/中/高/紧急/最高 |
| P1-08 | 置顶/代办 | 坐席手动操作，数据库加is_pinned和is_todo字段 | 操作后列表位置变化，数据持久化 |
| P1-09 | 坐席端AI助手面板 | AI建议回复/快速回复模板/操作步骤/风险提示/用户信息 | 5个模块在右栏显示，功能可用 |
| P1-10 | 用户端H5双栏 | 左侧对话区 + 右侧AI助手面板 | 企微应用内H5正确渲染双栏布局 |
| P1-11 | 摇人按钮 | 输入框左侧，橙色渐变铃铛图标，点击触发转人工 | 视觉交互符合设计稿，功能正确触发 |
| P1-12 | 趣味话术体系 | 存配置表，支持后台动态修改 | 6种场景话术正确触发，后台可修改 |
| P1-13 | 用户端AI助手面板 | 相似问题/审批流程/软件下载/知识库搜索 | 4个模块在右栏显示，未实现功能显示"即将上线"占位 |
| P1-20 | 邀请功能-历史消息共享 | 邀请时可选择共享历史消息模式（全部/最近10条/不共享） | 默认最近10条，被邀请人可查看共享的历史消息 |
| P1-21 | 邀请功能-部门批量邀请 | 可按部门批量邀请，勾选部门=邀请全部门成员 | 部门节点勾选后自动展开子成员，支持取消个别成员 |
| P1-22 | 邀请功能-系统消息广播 | 邀请成功/加入/退出时在会话中广播系统消息 | 所有参与者看到"XX邀请XX加入会话""XX已加入会话" |
| P1-23 | 文件上传 | 坐席/员工可发送文件附件（PDF/Word/Excel/压缩包等） | 文件可上传、存储、下载，大小限制可配置（默认20MB） |

### P2 — Nice to Have（第二步及之后交付）

| ID | 需求 | 说明 | 验收标准 |
|----|------|------|---------|
| P2-01 | AI前置筛选 | 新会话默认走AI，AI判断/用户触发转人工 | AI筛选率≥80% |
| P2-02 | 转人工触发配置 | 关键词/连续追问轮次/AI超时阈值写配置文件 | 配置文件修改后即时生效 |
| P2-03 | 排队系统 | 等待坐席接入的排队机制，含等待提示 | 排队人数/预计等待时间显示 |
| P2-04 | 对话日志标注 | 坐席标注AI回复正确/错误，嵌入日常工作流 | 标注操作在对话区内完成，不跳转页面 |
| P2-05 | AI知识库自动迭代 | 千问分析标注数据，判断缺文档/信息过时 | 自动生成FAQ推送RAGFlow，过时标记推送管理员 |
| P2-06 | 情绪标记（模型版） | 第二阶段迭代接入轻量模型替代关键词规则 | 模型推理准确率≥85% |
| P2-07 | 跨企业共享 | 通过企微"互联企业"应用共享 | 跨主体员工可使用同一服务 |
| P2-08 | AI建议回复动态生成 | 千问基于对话上下文+RAGFlow知识生成建议回复 | 建议回复采纳率≥30% |
| P2-09 | 操作步骤AI动态生成 | 替代静态配置，AI动态生成问题解决步骤 | 步骤可操作性强，坐席可直接转发 |
| P2-10 | 风险提示AI动态判断 | 替代已知故障匹配，AI动态风险判断 | 关键风险不遗漏 |

---

## 7. 并行协作模式

### 7.1 核心设计理念

传统"串行排队"改为"并行协作"——AI和人工并行，AI全程在场，人工随时介入。

### 7.2 坐席看板分区

| 区域 | 说明 | 坐席是否主动看 |
|------|------|---------------|
| AI自主处理区 | AI处理简单问题 | 折叠，默认不展开 |
| 举手等待区 | 员工明确要求人工或AI识别异常 | 核心关注区 |
| 人工处理区 | 当前坐席正在处理 | 我的会话 |
| 已结单区 | 会话已结束 | 灰色，折叠 |

### 7.3 会话标记系统详细设计

| 标记类型 | 图标颜色 | 触发条件 | 数据来源 |
|---------|---------|---------|---------|
| VIP标记 | 红色 | 企微通讯录API规则匹配（总监及以上或关键部门） | 企微通讯录 |
| 举手标记 | 黄色 | 员工说"转人工"或关键词触发 | 消息内容匹配 |
| 需介入标记 | 橙红色🔔 | 同一问题追问超过N轮(默认3轮)或AI判断需要人工 | 对话轮次计数 + AI判断 |
| 情绪标记 | 红色 | 第一阶段：关键词规则("急/紧急/马上/崩溃"等)；第二阶段：轻量模型 | 消息内容分析 |

### 7.4 紧急度评分公式

```
紧急度 = 基础分(关键词) + 情绪加成 + VIP加成 + 重复追问加成
```

- 评分范围: 1-5分
- 映射: 1=低, 2=中, 3=高, 4=紧急, 5=最高

### 7.5 会话列表排序规则

```
紧急 → 举手 → 需介入 → 活跃 → AI处理中 → 已结单
```

---

## 8. 界面设计

### 8.1 用户信息去重规则

| 区域 | 显示内容 | 不显示 |
|------|---------|--------|
| 左栏（会话列表） | 姓名头像 + 标签 + 最后消息摘要 | 办公地点 |
| 中栏（对话区） | 姓名 + 标签（VIP/举手/需介入） | 部门/岗位/等级 |
| 右栏（AI助手面板） | 部门/岗位/等级/完整信息 | — |

### 8.2 用户端界面

**布局**: 企微H5双栏
- **左侧**: 对话区
  - AI回复和人工回复在同一对话流
  - AI回复后附带3张推荐卡片（相似问题、下载入口、审批流程）
  - 摇人按钮在输入框左侧
  - 底部引导条："点击 摇人 = 一键呼叫 IT 坐席"
- **右侧**: AI助手面板
  - 相似问题与做法（RAGFlow语义检索，异步加载）
  - 审批流程链接（静态映射表，存数据库/配置文件）
  - 软件下载快捷入口（分类到下载链接映射，显示版本号和平台）
  - 知识库搜索（用户主动触发，加防抖300ms）
  - **功能未实现前预留占位符+"即将上线"灰字提示**

### 8.3 坐席端界面

**布局**: 三栏
- **左栏**: 会话列表
  - 排序 + 彩色标签 + 红点 + 未读消息数
- **中栏**: 对话区
  - AI回复和坐席回复明确区分
  - AI建议条
  - 操作按钮
- **右栏**: AI助手面板（5个模块）
  - AI建议回复（采纳/编辑后采纳/忽略）
  - 快速回复模板（按问题分类，支持变量替换{员工姓名}等）
  - 问题解决操作步骤
  - 风险提示
  - 用户特点和其他注意事项（基本信息+VIP标记+历史咨询模式+坐席备注）

---

## 9. 摇人功能设计

### 9.1 视觉设计

| 属性 | 值 |
|------|------|
| 位置 | 输入框左侧，和微信语音按钮同样的位置 |
| 图标 | 铃铛图标 |
| 颜色 | 橙色渐变(#FF6B35→#FF8F5E) |
| 右上角 | 红点 |
| 尺寸 | 44px圆形 |
| Hover | 放大110%弹性回弹 |
| 点击 | 0.6秒摇晃动画 |

### 9.2 趣味话术体系

| 触发场景 | 话术 | 语气 | 存储方式 |
|---------|------|------|---------|
| 点击摇人按钮 | 大哥，俺这就去摇人，稍等... | 亲切 | 配置表 |
| 关键词触发转人工 | 收到！这就帮您摇位大神来 | 稍正式 | 配置表 |
| 排队等待(30秒无人接单) | 人还在路上，别急别急～ | 安抚 | 配置表 |
| 坐席接入 | 人摇来了！IT坐席为您服务 | 明确交接 | 配置表 |
| 等待超时(2分钟) | 坐席都在忙，不过AI还在呢，要不先聊聊？我再继续摇 | 降级安抚 | 配置表 |
| VIP员工(自动切换) | 这就帮您安排专家，请稍候 | 正式 | 配置表 |

> **配置管理**: 话术存配置表，支持后台动态修改，无需发版。

---

## 10. 技术约束

| 约束项 | 说明 |
|--------|------|
| 消息通道 | 企微自建应用消息API，禁止使用微信客服能力 |
| 前端框架 | Vue3 + ElementPlus |
| 后端框架 | FastAPI + Redis + PostgreSQL |
| 部署方式 | Docker 容器化部署（Docker Compose 一键启停） |
| 用户端渲染 | 企微H5（方式B：双栏布局，非对话卡片内方式A） |
| 坐席端通信 | 第一步使用轮询(每3-5秒)，不使用WebSocket |
| AI接入 | 第一步不接入千问/Dify/RAGFlow |
| 排队系统 | 放在第二步之后 |
| 跨企业共享 | 放在第三步之后 |
| 开发者 | 宋献，IT支持组组长，开发零基础，通过学习+AI辅助完成开发 |

---

## 11. 数据模型核心设计

### 11.1 会话表 (conversations)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 会话ID |
| employee_id | String | 企微员工ID |
| employee_name | String | 员工姓名 |
| department | String | 部门 |
| position | String | 岗位 |
| level | String | 等级 |
| status | Enum | 会话状态: ai_handling / queued / serving / resolved |
| is_vip | Boolean | VIP标记 |
| is_pinned | Boolean | 置顶标记 |
| is_todo | Boolean | 代办标记 |
| urgency_score | Integer | 紧急度评分(1-5) |
| tags | JSON | 标签集合(举手/需介入/情绪等) |
| assigned_agent_id | String | 分配的坐席ID |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

### 11.2 消息表 (messages)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 消息ID |
| conversation_id | UUID | 所属会话ID |
| sender_type | Enum | 发送者: employee / agent / ai / system |
| sender_id | String | 发送者ID |
| content | Text | 消息内容 |
| msg_type | Enum | 消息类型: text / image / file |
| ai_suggestion | Boolean | 是否为AI建议(坐席端) |
| is_read | Boolean | 是否已读 |
| created_at | DateTime | 创建时间 |

### 11.3 坐席表 (agents)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 坐席ID |
| user_id | String | 企微用户ID |
| name | String | 坐席姓名 |
| status | Enum | 在线/离线/忙碌 |
| current_load | Integer | 当前服务会话数 |
| created_at | DateTime | 创建时间 |

---

## 12. 待确认问题 (Open Questions)

| # | 问题 | 影响范围 | 建议 |
|---|------|---------|------|
| OQ-01 | 坐席数量上限：第一步测试环境计划支持几个坐席同时在线？ | 服务器资源/轮询频率 | 建议3-5个坐席 |
| OQ-02 | 消息存储策略：会话记录保留多久？是否需要归档机制？ | 数据库容量/合规要求 | 建议6个月热数据+归档 |
| OQ-03 | 多媒体消息：M1支持文件上传，图片共享留到M2 | 企微API对接范围 | M1支持文本+文件上传，图片共享M2再评估 |
| OQ-04 | 坐席排班：是否需要坐席排班/轮班功能？ | 坐席管理模块 | 建议第二步考虑 |
| OQ-05 | 满意度评价：会话结束后是否需要员工评价？ | 用户端界面/数据收集 | 建议第二步增加 |
| OQ-06 | 企微应用命名：自建应用在企微中显示的名称？ | 用户感知 | 建议命名"IT服务台" |
| OQ-07 | 坐席端权限：是否区分坐席/组长/管理员角色？ | 权限系统设计 | 建议第一步简单区分，第二步完善 |
| OQ-08 | 企微互联企业应用共享范围：共享给哪些上下游企业？ | 跨企业功能边界 | 第三步确认 |
| OQ-09 | AI回复末尾提示语："以上为AI自动回复，如需人工帮助请回复'转人工'"——是否需要可配置？ | 第二步AI接入 | 建议存配置表 |
| OQ-10 | 转人工阈值：AI调用超时3秒是否需要可配置？ | 第二步AI接入 | 建议写配置文件 |

---

## 13. 里程碑与交付物

| 里程碑 | 预计周期 | 核心交付物 | 现有系统变化 |
|--------|---------|-----------|------------|
| 阶段一：转人工改H5+坐席工作台MVP | 6-8周 | H5登录+身份识别 + 转人工链接改H5 + 坐席工作台MVP（会话列表+聊天+快速回复+邀请功能，不含AI） | AI转人工链接从员工服务改为H5，坐席使用自研工作台 |
| 阶段二：智能咨询集成 | 5周 | H5全流程 + 敲桌子 + 双通道推送 + AI建议面板 + 排队 + 评分 | 员工服务入口逐步迁移至H5，坐席工作台增强 |
| 阶段三：坐席辅助回复/判断 | 4-6周 | AI Wingman（草稿+摘要+知识+排查步骤）+ 双区布局 | 坐席从员工服务后台切换至自研工作台 |
| 阶段四：日志标准+知识库迭代 | 4-6周 | 标注系统 + AI知识库自动优化 + 数据看板 + 跨企业共享 | AI知识库从人工维护升级为自动迭代 |
| 阶段五：自动/辅助审核开单结单 | 4-6周 | 待办面板 + AI填单/审核/结单 + 外部系统对接 | 替代多系统切换，统一工作台闭环 |

---

## 附录 A: 术语表

| 术语 | 说明 |
|------|------|
| 企微 | 企业微信 |
| 员工服务 | 企微内置的客服模块，本方案将放弃使用 |
| 自建应用 | 企微中由企业自行开发的应用 |
| 互联企业 | 企微跨主体企业互联功能 |
| RAGFlow | 检索增强生成引擎，用于知识库语义检索 |
| Dify | AI应用开发平台 |
| 千问 | 阿里云通义千问大模型 |
| 摇人 | 一键呼叫IT坐席的趣味化交互设计 |
| 并行协作 | AI和人工同时在线，人工可随时介入的创新服务模式 |

## 附录 B: 企微API关键接口

| 接口 | 用途 | 文档 |
|------|------|------|
| 接收消息 | 通过回调URL接收员工发送的消息 | 企微自建应用消息回调 |
| 发送消息 | 主动向员工发送消息 | 企微应用消息发送API |
| 通讯录读取 | 获取员工信息（VIP判断） | 企微通讯录API |
| 互联企业应用共享 | 跨主体共享应用 | 企微互联企业API |
| OAuth2静默授权 | H5页面身份认证 | 企微网页授权API |

---

## 14. AI Wingman — 坐席智能辅助设计

> **设计日期**: 2026-06-04 | **设计者**: 宋献 | **状态**: 方案已确认，待开发

### 14.1 设计理念

传统IT服务台的设计重心偏向"员工端体验"——让员工更快获得答案。但**坐席人员的工作体验同样关键**。IT坐席每天面对大量重复性问题（密码重置、账号解锁、VPN连接），同时承受员工焦虑情绪传导带来的心理消耗。

**AI Wingman 的核心使命**：让AI不仅服务员工，更是坐席的"智能副驾驶"——消灭重复劳动、增强认知能力、守护情绪健康。

```
┌─────────────────────────────────────────────────────────────────────┐
│                     AI Wingman 三层设计架构                           │
│                                                                     │
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                     情感层 · 守护情绪健康                         ││
│  │  情绪识别预警 → 安抚话术推荐 → 语气润色 → 正向激励 → 疲劳检测     ││
│  │  目标：减少坐席情绪耗竭 45%，降低职业倦怠风险                      ││
│  └─────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                     认知层 · 消除认知负荷                         ││
│  │  知识推荐 → SOP流程导航 → 相似工单推荐 → 下一步建议 → 客户画像    ││
│  │  目标：降低坐席认知负荷 55%，新人上手周期缩短 50%                 ││
│  └─────────────────────────────────────────────────────────────────┘│
│  ┌─────────────────────────────────────────────────────────────────┐│
│  │                     效率层 · 消灭重复劳动                         ││
│  │  AI草稿回复 → 会话自动摘要 → 智能填单 → 自动标签 → 快捷回复库    ││
│  │  目标：坐席打字量减少 80%，单次会话处理时间缩短 60%               ││
│  └─────────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────────┘
```

### 14.2 行业最佳实践验证

调研了 NiCE Copilot、Helpshift AI Copilot、Zendesk Agent Assist、天润融通、循环智能、合力亿捷等 7 家主流解决方案，提炼出关键数据：

| 行业基准数据 | 数值 | 来源 |
|-------------|------|------|
| AI草稿回复可减少坐席打字量 | 70%-80% | 天润融通、合力亿捷实测 |
| 自动填单节省时间 | 从1分钟降至10秒 | 天润融通实测 |
| 知识推荐缩短新人上手 | 50% | 循环智能实测 |
| 情绪识别预警准确率 | 85%+ | Helpshift 实测 |
| 自动摘要节省文书记录时间 | 70% | 合力亿捷实测 |

**5 大设计原则**（行业共识）：
1. **非侵入式** — AI 辅助不干扰坐席原生工作流
2. **坐席始终主导** — AI 只建议，不自动发送，坐席始终有最终决定权
3. **反馈闭环** — 采纳/编辑/忽略行为持续优化 AI 推荐质量
4. **上下文继承** — AI → 人工切换时完整上下文（对话历史、客户画像、AI诊断）无缝跟随
5. **渐进式赋能** — 每阶段独立可用，不依赖后续阶段

### 14.3 新增用户故事（坐席端）

| # | 角色 | 故事 | 验收标准 |
|---|------|------|---------|
| US-8 | IT坐席 | 当我接到一个会话时，AI 已经帮我生成了草稿回复，我只需审核后点击发送，不用从头打字 | 每条新员工消息自动生成 1 个 AI 草稿，[采纳]/[编辑]/[忽略] 三选一 |
| US-9 | IT坐席 | 当我完成一个会话时，系统自动生成结构化摘要（问题/原因/解决方案），我只需确认或微调 | 会话结单时自动弹出摘要确认框，坐席可编辑后确认，确认后存入 messages 表 |
| US-10 | IT坐席 | 在处理复杂问题时，右侧自动显示知识库中的相关文档和操作步骤，不用切屏搜索 | 基于当前对话上下文，自动检索知识库并推送 Top 3 相关文档 |
| US-11 | IT坐席 | 当员工情绪激动时，AI 提醒我注意语气，并推荐安抚话术，帮助我平和应对 | 情绪关键词触发预警图标，自动推荐 1-2 条安抚话术，支持一键发送 |
| US-12 | IT坐席 | 我希望看到"历史上类似问题是怎么解决的"，避免重复调查 | 基于当前问题自动搜索历史已结单会话，展示相似工单及解决方案 |
| US-13 | IT主管 | 我希望了解坐席团队的工作效率和情绪健康状态，及时发现职业倦怠信号 | 仪表盘展示响应时效、会话时长、情绪事件统计、坐席疲劳指数 |

### 14.4 Phase 1 实施方案：效率层（已确认）

**双区布局设计**：
- **内嵌区（对话流中）**：针对当前员工消息的 AI 草稿回复，以特殊气泡样式显示在对话流中，[采纳]/[编辑]/[忽略] 按钮内嵌
- **侧栏区（右侧面板）**：会话自动摘要、自动标签、快捷回复库、相关知识推荐

**内嵌区 vs 侧栏区的设计逻辑**：

| 功能 | 呈现位置 | 理由 |
|------|---------|------|
| AI草稿回复 | **内嵌**（对话流中） | 与当前对话上下文紧密相关，坐席需逐条审核 |
| 会话自动摘要 | **侧栏** | 会话结束后查看，不干扰实时对话 |
| 知识推荐 | **侧栏** | 参考性信息，按需查阅 |
| 快捷回复模板 | **侧栏** | 已有功能，保持一致性 |
| 自动标签 | **侧栏** | 批次操作，不打断对话流 |

**底层实现**：扩展现有 Dify —— 新增一个 `assistant` 类型的 Dify Agent，与员工端 AI 共用知识库，但 system prompt 侧重"辅助坐席回复"而非"直接回复员工"。

| Agent | 用途 | system prompt 侧重 |
|-------|------|-------------------|
| Agent 1 — 员工端 AI（已有） | 回答员工问题 | 友好、准确、引导自助 |
| Agent 2 — 坐席端 Wingman（新增） | 为坐席生成草稿/摘要/知识 | 专业、结构化、可操作 |

### 14.5 Phase 2+ 前置规划

| 阶段 | 功能 | 核心价值 | 预计周期 |
|------|------|---------|---------|
| Phase 1 效率层 | AI草稿 + 自动摘要 + 自动标签 | 消灭重复劳动 | 2-3 周 |
| Phase 2 认知层 | 知识推荐 + SOP导航 + 相似工单 + 客户画像 | 降低认知负荷 | 3-4 周 |
| Phase 3 情感层 | 情绪识别 + 安抚话术 + 语气润色 + 疲劳检测 | 减少情绪消耗 | 4-6 周 |

### 14.6 新增需求池

**P1 — Should Have（AI Wingman 效率层）**

| ID | 需求 | 说明 | 验收标准 |
|----|------|------|---------|
| P1-14 | AI草稿回复 | 每条新员工消息自动生成AI建议回复，坐席可采纳/编辑/忽略 | 草稿生成 <3秒，内嵌在对应的员工消息下方 |
| P1-15 | 会话自动摘要 | 会话结单时AI自动生成结构化摘要（问题/原因/解决方案） | 摘要包含 3 个结构化字段，坐席可编辑后确认 |
| P1-16 | 自动标签 | AI基于对话内容自动建议会话标签（如：账号问题/网络故障） | 标签建议在结单时弹出，支持添加自定义标签 |
| P1-17 | AI建议采纳追踪 | 记录坐席对AI建议的采纳/编辑/忽略行为 | 每个AI建议的操作记录到 messages 表 |

**P2 — Nice to Have（认知层 + 情感层）**

| ID | 需求 | 说明 | 验收标准 |
|----|------|------|---------|
| P2-11 | 知识推荐 | 基于对话自动检索知识库，推送 Top 3 相关文档 | 推荐刷新 <2秒，链接可点击跳转 |
| P2-12 | SOP流程导航 | 高频问题预置SOP步骤，引导标准流程 | SOP步骤可勾选完成，支持动态调整 |
| P2-13 | 相似工单推荐 | 搜索历史已结单会话，展示相似问题及解决方案 | 相似度排序，展示 Top 5 |
| P2-14 | 客户画像 | 展示员工历史咨询模式、技术偏好等 | 画像自动提取，支持坐席补充 |
| P2-15 | 情绪识别预警 | 检测员工消息情绪，坐席端预警图标 | 关键词+语气分析，准确率 ≥ 85% |
| P2-16 | 安抚话术推荐 | 检测到情绪波动时自动推荐安抚话术 | 话术可一键发送，支持自定义 |
| P2-17 | 语气润色 | 检查坐席即将发送的消息，提示语气问题 | 仅提示不拦截，坐席可选择忽略 |
| P2-18 | 正向激励 | 会话满意结单时向坐席发送正向反馈 | 激励信息以系统消息方式推送 |
| P2-19 | 坐席疲劳检测 | 统计连续工作时间、情绪事件次数，提醒休息 | 阈值可配置，温和提示 |


---

## 15. v5.3 坐席工作台增量需求

> 以下内容合并自 PRD-v53-incremental.md（2026-06-06），章节编号保持原样以便对照原文档。

---

## 1. 项目信息

| 字段 | 值 |
|------|-----|
| **项目名称** | it_smart_desk_workspace_v53 |
| **技术栈** | 前端: Vue3 + TypeScript + Element Plus + Pinia + Vite / 后端: FastAPI + SQLAlchemy |
| **语言** | 中文 |
| **原型文件** | `agent-workspace-v5_3.html` |
| **项目根目录** | `C:\Users\simon\wecom_it_smart_desk\` |

### 原始需求复述

对企微 IT 智能服务台的坐席工作台进行 UI/UX 全面升级（v5.3 增量迭代）。现有系统已具备会话管理、消息收发、AI 助手（5 Tab 结构）、快速回复等基础功能，本次迭代需根据 v5.3 原型图实现：主题系统、左栏会话列表改造（三段折叠 + 优先级图标 + 待办面板）、中栏聊天区改造（用户信息栏 + AI 推荐内联 + 排查步骤栏 + 视图切换）、右栏 AI 助手面板重构（移除 Tab 改上下两区）、后端模型扩展等 7 大模块变更。

### 现有系统基线

当前坐席工作台采用三栏布局：

- **左栏（280px）**：`ConversationList.vue` — 6 区会话列表（待接单/我的/协作/其他/AI/已结单），基础搜索
- **中栏（flex-1）**：`ChatArea.vue` — 顶部标题栏 + 消息区 + 回复输入框
- **右栏（320px）**：`AiAssistantPanel.vue` — 5 Tab（AI 副驾驶/快速回复/操作步骤/风险提示/用户信息）

后端模型：`Conversation`（含 urgency_score/tags/assigned_agent_id 等）、`Employee`（基础字段）、`Agent`、`Message`、`QuickReplyTemplate`

---

## 2. 产品定义

### 2.1 产品目标

1. **提升坐席效率**：通过 AI 推荐回复（Ctrl+1/2/3 快捷填入）、键盘驱动的快速回复（Alt+1~5 + ↑↓ + Enter）、排查步骤流程图，将坐席平均响应时间降低 30%
2. **增强信息感知**：通过优先级图标体系（⛔阻断性/👥影响范围/⭐角色等级/🔁重复问题）、用户情绪状态芯片、IT 等级徽标，让坐席在 3 秒内掌握会话全貌
3. **统一工作闭环**：通过待办事项面板 + 中间栏视图切换，将工单/审批/设备异常等任务类型整合到同一工作台，消除多系统切换成本

### 2.2 用户故事

| # | 用户故事 |
|---|---------|
| US-1 | **As a** IT 坐席, **I want** 在会话列表每条会话上直接看到阻断性/影响范围/角色等级/重复问题等优先级图标, **so that** 我能快速判断哪些会话需要优先处理，不必逐一点开查看详情 |
| US-2 | **As a** IT 坐席, **I want** 在聊天区顶部常驻显示用户情绪、等待时长、IT 等级等信息芯片，点击展开 6 卡片详情, **so that** 我在对话过程中始终掌握用户画像，及时调整沟通策略 |
| US-3 | **As a** IT 坐席, **I want** 在聊天区内看到 1-3 条 AI 推荐回复并支持 Ctrl+1/2/3 快捷填入, **so that** 我能快速回复常见问题，减少手动输入时间 |
| US-4 | **As a** IT 坐席, **I want** 点击左侧待办事项时中间栏切换为任务类型专属页面（工单/审批/设备异常）, **so that** 我无需切换到其他系统即可一站式处理所有任务 |
| US-5 | **As a** IT 坐席, **I want** 在右栏通过 Alt+1~5 切换快速回复分类、↑↓ 导航、Enter 确认填入, **so that** 我可以在不离开键盘的情况下高效完成回复 |

---

## 3. 需求池（P0/P1/P2）

### P0 — 必须完成（核心体验）

---

#### FE-01 主题系统

| 项目 | 说明 |
|------|------|
| **需求** | 浅色/深色主题切换 |
| **交互** | 顶部工具栏右侧添加 ☀️/🌙 切换开关（Track + Thumb 滑块样式），点击即切换 |
| **实现** | `data-theme="light\|dark"` 属性切换；CSS 变量驱动两套配色（`:root` 浅色 / `[data-theme="dark"]` 深色） |
| **持久化** | 切换后写入 `localStorage`，页面加载时读取恢复 |
| **约束** | 切换即时生效，过渡时长 ≤ 300ms（`transition: background 0.3s, color 0.3s`）；所有新增组件必须兼容双主题 |
| **设计规格** | 深色主题：主背景 `#0f1923`，次背景 `#151f2b`，三级背景 `#1a2736`，悬停 `#1e3044`，激活 `#243b52`；主文字 `#e8edf2`，次文字 `#8ba1b7`；强调色 `#4da6ff` |
| **变更范围** | `Workspace.vue` 顶部栏重构为独立 `TopBar.vue`；新增 `composables/useTheme.ts`；`global.css` 新增深色 CSS 变量 |

---

#### FE-02 左栏会话列表 — 三段折叠 + 搜索增强 + 优先级图标

| 项目 | 说明 |
|------|------|
| **三段折叠** | 替代原 6 区结构，改为 3 段：📌 我的会话（默认展开）/ 👥 同事会话（默认折叠）/ 🕐 历史会话（默认折叠） |
| **段头交互** | 段头背景 `var(--bg-tertiary)`，hover 变 `var(--bg-hover)`；显示条目数量（药丸徽标）+ 折叠箭头（▼ 旋转 -90° 收起）；点击整行切换折叠 |
| **搜索增强** | 搜索框 placeholder "搜索用户、关键词..."；下方增加快捷筛选标签：全部/待处理/进行中/已完成（药丸样式，active 态 `var(--accent-soft)` + `var(--accent)` 色） |
| **优先级图标** | 每条会话名称右侧显示：⛔ 阻断性（`is_blocking`，红底）、👥 影响范围（`impact_scope`，>5 人用高对比色）、⭐ 角色等级、🔁 重复问题。**不显示 IT 等级徽标** |
| **优先级图标规格** | 16×16px 圆角方块，8px 字体；`pi-blocked` 红底、`pi-impact` 黄底（high 变红底）、`pi-role` 紫底、`pi-repeat` 橙底 |
| **会话条目规格** | 条目间距 `margin: 1px 6px`，padding `8px 10px`；active 态 `var(--accent-soft)` + accent 边框；"待回复" 红色药丸标签 |
| **变更范围** | `ConversationList.vue` 重构分区逻辑 + 搜索标签；`ConversationItem.vue` 新增优先级图标渲染 |

---

#### FE-03 左栏底部 — 待办事项面板

| 项目 | 说明 |
|------|------|
| **位置** | 左栏底部，`border-top: 1px solid var(--border)`，`max-height: 220px`，内部滚动 |
| **标题** | "待办事项" + 紧急数量红色标记（如 "5 紧急"） |
| **条目** | 每条显示：优先级圆点（urgent 红 / high 黄）+ 文本 + 类型标签（工单/审批/设备）+ 时间 |
| **类型标签样式** | 工单：蓝底蓝字蓝边框；审批：紫底紫字紫边框；设备：橙底橙字橙边框（9px 字体） |
| **点击交互** | 点击条目 → 中间栏切换为对应任务类型详情视图 |
| **底部统计** | 在线/忙碌/离线坐席数（带状态圆点） |
| **变更范围** | `ConversationList.vue` 底部新增 `TodoPanel.vue` |

---

#### FE-04 中栏聊天区 — 用户信息栏

| 项目 | 说明 |
|------|------|
| **常驻区** | 替代原顶部标题栏，显示：头像（36px 圆形渐变）+ 姓名·部门岗位 + IT 等级徽标 + 信息 chips + 展开箭头 |
| **信息 chips** | 😟 情绪（黄底黄边）、⏱ 等待时长、💬 对话轮次、🔁 重复标记（红底红边）、📝 备注标记（紫底紫边）；默认态灰底 |
| **展开详情** | 点击整行展开/收起 6 卡片详情面板（3 列 grid 布局）：① 情绪状态 ② 会话详情 ③ 问题分析 ④ IT 技能等级 ⑤ 历史工单 ⑥ 其他备注 |
| **IT 等级徽标** | 7 级段位（见 §4.2），显示在用户名行 + 详情卡片 ④ 中 |
| **动画** | 展开箭头旋转 180°，详情面板 `max-height` 动画过渡 0.35s |
| **变更范围** | 新增 `UserInfoBar.vue` + `ItLevelBadge.vue`；`ChatArea.vue` 替换顶部栏 |

---

#### FE-05 中栏聊天区 — AI 推荐回复（内联）

| 项目 | 说明 |
|------|------|
| **位置** | 聊天消息流中，用户消息之后、坐席回复之前 |
| **触发条件** | 仅坐席未回复时显示；坐席发送回复后自动隐藏 |
| **样式** | 虚线边框（`1px dashed var(--accent)`）+ 浅蓝背景，全宽 |
| **内容** | "🤖 AI 推荐回复" 标签 + 1-3 个推荐选项卡片（横向排列，flex:1） |
| **快捷键** | Ctrl+1 / Ctrl+2 / Ctrl+3 快捷填入回复框 |
| **点击** | 点击卡片内容填入回复框并聚焦 |
| **变更范围** | 新增 `AiRecommendInline.vue`；修改 `ChatArea.vue` 消息渲染逻辑 |

---

#### FE-06 中栏聊天区 — 排查步骤栏

| 项目 | 说明 |
|------|------|
| **位置** | 聊天输入框下方，始终可见（不可整体收起） |
| **栏头** | "🔧 排查步骤" + "▶ 展开全流程图" 按钮（accent 色边框药丸） |
| **默认视图** | 最优路径横向方块：① 确认版本 → ② 清除缓存 → ③ 远程排查 → ...（可横向滚动） |
| **路径方块规格** | padding `7px 14px`，圆角方块；done 态绿底、current 态蓝底、默认灰底；hover 变 accent 边框 |
| **展开视图** | 点击 "展开全流程图" → 按钮文字变 "▼ 收起全流程图"，下方展开完整决策树 |
| **决策树规格** | 纵向步骤：圆点节点（22px）+ 连接线（2px）；判断节点（❓ 判断）黄底方块；分支用虚线左侧缩进；当前步骤蓝色节点，已完成绿色节点 |
| **动画** | 流程图区 `max-height` 过渡 0.35s；按钮箭头旋转 90° |
| **数据源** | 静态模板库（`TroubleshootingTemplate` 模型），P0 坐席手动选择模板 |
| **变更范围** | 新增 `TroubleshootBar.vue`；`ChatArea.vue` 底部挂载 |

---

#### FE-07 中栏 — 任务详情视图切换

| 项目 | 说明 |
|------|------|
| **触发** | 点击左栏待办事项条目 → 中间栏从聊天视图切换为任务详情视图 |
| **返回** | "← 返回会话" 按钮，切换回聊天视图 |
| **运维工单页** | 📋 工单描述卡片（标题/类型/优先级/上报人/时间/描述）+ 📍 处理进度卡片（状态/接单人/SLA）+ 操作按钮：📥 接单 / 🔧 开始处理 / ✅ 结单 / 🔄 转派 |
| **审批单页** | 📝 审批内容卡片 + ✏️ 审批意见输入区（textarea）+ 操作按钮：✅ 审批通过 / ❌ 拒绝审批 / 🔄 转交审批 |
| **设备异常页** | 🖥 设备状态网格（2×3 grid：名称/型号/在线状态/最后在线/IP/告警次数）+ 🔧 处理记录卡片 + 操作按钮：📝 一键开单 / 🚚 派工 / ✅ 标记恢复 / 📅 加入巡检 |
| **卡片规格** | 白底 + border + `radius-lg`(10px) + padding `14px 16px`；标签行 `tic-label`(70px) + `tic-value` |
| **状态色值** | 正常=success绿、告警=warning黄、异常=danger红 |
| **变更范围** | 新增 `TaskDetailView.vue`（含 3 种子视图）；`ChatArea.vue` 同级添加视图切换逻辑 |

---

#### FE-08 右栏 AI 助手面板重构

| 项目 | 说明 |
|------|------|
| **重构** | 移除现有 5 Tab 结构（`ElTabs`），改为上下两个区域 |
| **上方 ~1/3** | 🤖 AI 智能推荐区（`flex-shrink:0`，border-bottom 分隔）：标题栏（左侧蓝色竖线 3×12px + "🤖 AI 智能推荐"）+ 1-3 张推荐卡片 |
| **推荐卡片** | 灰底 + border，hover 变 accent 边框；卡片头：方案名称 + 置信度药丸（如 "92%"）；卡片文本：2 行截断；快捷键提示 `Ctrl+1/2/3` |
| **下方 ~2/3** | 快速回复区（`flex:1`，内部列布局）：搜索栏置顶 + 分类标签栏 + 回复条目列表 + 底部键盘指南 |
| **分类标签** | 横向排列，每个标签带 `Alt+N` 提示；active 态 `var(--accent-soft)` + accent 边框；如 "VPN/网络 Alt+1"、"邮箱/办公 Alt+2" 等 |
| **回复条目** | 左侧图标 + 文本 + 序号提示；selected 态蓝底蓝边框；hover 灰底 |
| **键盘导航** | Alt+1~5 切换分类；↑↓ 选中条目；Enter 确认填入；/ 聚焦搜索框 |
| **键盘指南** | 底部常驻：`Alt+1-5 切换` / `↑↓ 选择` / `Enter 填入` / `/ 搜索` |
| **移除** | 风险提示 Tab（`RiskAlert.vue` 废弃）、用户信息 Tab（`UserInfoPanel.vue` 废弃，功能已并入聊天区） |
| **变更范围** | `AiAssistantPanel.vue` 完全重写；`QuickReplyPanel.vue` 重写交互逻辑 |

---

#### FE-09 系统名称

| 项目 | 说明 |
|------|------|
| **顶部栏** | 左侧：logo 方块 "IT"（渐变紫蓝 26×26px）+ "IT智能服务台"（渐变文字）+ "· 坐席工作台 — AI驱动 · 多系统对接 · 一站式处理"（10px 灰色副标题，max-width 280px 溢出省略） |
| **变更范围** | `TopBar.vue`（从 `Workspace.vue` 顶部栏独立） |

---

#### BE-01 Employee 模型扩展

| 项目 | 说明 |
|------|------|
| **新增字段** | `it_level`: IT 等级枚举（bronze/silver/gold/platinum/diamond/star/king），默认 silver；`it_level_source`: 等级来源（system/manual），默认 system；`notes`: 备注 JSON |
| **API** | 新增 `PUT /api/employees/{id}/it-level` 坐席手动调整 IT 等级端点；修改 `GET /api/employees/{id}` 返回新字段 |
| **变更范围** | `models/employee.py` 新增 3 字段；`schemas/` 新增/修改；`api/` 新增端点 |

---

#### BE-02 Conversation 模型扩展

| 项目 | 说明 |
|------|------|
| **新增字段** | `impact_scope`: 影响范围（整数，受影响人数，默认 0）；`is_blocking`: 阻断性标记（布尔，默认 False）；`emotion_state`: 情绪状态（枚举 normal/anxious/angry/urgent，默认 normal） |
| **API** | 修改 `GET /api/conversations` 和 `GET /api/conversations/{id}` 响应包含新字段 |
| **变更范围** | `models/conversation.py` 新增 3 字段；`schemas/conversation.py` 修改；`api/conversations.py` 修改 |

---

#### BE-03 TodoItem 模型 + CRUD API

| 项目 | 说明 |
|------|------|
| **新增模型** | `TodoItem`：id(UUID), type(ticket/approval/device), title, priority(urgent/high/normal), description(JSON), status(pending/processing/resolved), assigned_agent_id(nullable), corp_id, created_at, updated_at |
| **API** | `GET /api/todo-items`（列表）、`GET /api/todo-items/{id}`（详情）、`PUT /api/todo-items/{id}/status`（更新状态）|
| **数据** | Mock 数据先行，预置 5-10 条示例待办 |
| **变更范围** | 新增 `models/todo_item.py` + `schemas/todo_item.py` + `api/todo_items.py` |

---

#### BE-04 TroubleshootingTemplate 模型 + CRUD API

| 项目 | 说明 |
|------|------|
| **新增模型** | `TroubleshootingTemplate`：id(UUID), name, category(vpn/email/system/account), path_steps(JSON 最优路径), flowchart(JSON 完整决策树), is_active(布尔), created_at, updated_at |
| **API** | `GET /api/troubleshooting-templates`（列表）、`GET /api/troubleshooting-templates/{id}`（详情）、`POST/PUT/DELETE`（管理员增删改） |
| **数据** | 预置常见问题模板（VPN 连接失败、邮箱配置、系统登录、账号权限等 5-8 套） |
| **变更范围** | 新增 `models/troubleshooting_template.py` + `schemas/troubleshooting_template.py` + `api/troubleshooting_templates.py` |

---

### P1 — 应该完成（体验增强）

---

#### FE-10 快捷键系统完善

| 项目 | 说明 |
|------|------|
| **需求** | 全局快捷键注册与统一管理 |
| **快捷键列表** | Ctrl+1/2/3（AI 推荐填入）、Alt+1~5（快速回复分类切换）、↑↓（快速回复条目导航）、Enter（确认填入）、/（聚焦快速回复搜索框） |
| **约束** | 快捷键仅在未聚焦输入框时生效（避免与打字冲突）；需提供快捷键提示 UI（右栏底部键盘指南） |
| **变更范围** | 新增 `composables/useKeyboardShortcuts.ts` |

---

#### FE-11 IT 等级手动调整交互

| 项目 | 说明 |
|------|------|
| **需求** | 坐席可在用户信息详情卡片中手动调整用户 IT 等级 |
| **交互** | 在 IT 等级详情卡片旁提供「调整」按钮，弹出 7 级选择器（下拉/弹窗） |
| **约束** | 调整后需记录 `it_level_source=manual`；前端立即更新显示，后端异步保存 |
| **变更范围** | `UserInfoBar.vue` 详情面板中新增调整交互 |

---

#### FE-12 主题切换过渡动画

| 项目 | 说明 |
|------|------|
| **需求** | 主题切换时的平滑过渡效果 |
| **实现** | `body` 添加 `transition: background 0.3s, color 0.3s`；所有 CSS 变量驱动的属性自动跟随过渡 |
| **约束** | 过渡时长 ≤ 300ms，不影响交互流畅度 |

---

#### BE-05 IT 等级自动评分逻辑（框架）

| 项目 | 说明 |
|------|------|
| **需求** | 为后续迭代搭建自动评分框架 |
| **实现** | 定义评分维度和权重接口，当前仅返回默认值（silver）或手动值 |
| **约束** | 不在 P0 实现完整评分，仅搭建扩展点 |

---

### P2 — 锦上添花（远期优化）

---

#### FE-13 排查步骤进度同步

| 项目 | 说明 |
|------|------|
| **需求** | 排查步骤的当前步骤与对话内容自动同步 |
| **实现** | 根据消息内容关键词自动推进步骤状态（如坐席说"清除缓存"→ 步骤 ② 标记 done） |

#### FE-14 待办事项实时推送

| 项目 | 说明 |
|------|------|
| **需求** | 通过 WebSocket 实时推送新的待办事项 |
| **实现** | 扩展 WS 消息类型，新增 `todo_item_created` 事件 |

#### FE-15 IT 等级完整自动评分

| 项目 | 说明 |
|------|------|
| **需求** | 基于用户历史工单、自助解决率、操作复杂度等维度自动计算 IT 等级 |
| **实现** | 后台定时任务 + 评分服务 |

#### FE-16 排查步骤模板管理后台

| 项目 | 说明 |
|------|------|
| **需求** | 管理员可在后台增删改排查模板 |
| **实现** | 独立管理页面或嵌入现有管理后台 |

---

## 4. UI 设计草案

### 4.1 整体布局（三栏 + 顶栏）

```
┌─────────────────────────────────────────────────────────────────────┐
│ [IT] IT智能服务台 · 坐席工作台 — AI驱动 · 多系统对接 · 一站式处理    │  ☀️/🌙 │ 坐席: 陈思远 │
├──────────┬──────────────────────────────────┬───────────────────────┤
│          │  👤 张伟 · 研发一部 🥇黄金        │  🤖 AI 智能推荐       │
│ 🔍 搜索  │  😟焦虑 ⏱8分32秒 💬6轮 🔁重复    │  ┌─────────────────┐  │
│ 全部|待处 │  ▼ [6卡片详情展开区]              │  │ 92% 远程协助方案 │  │
│ |进行|已完│──────────────────────────────────│  │ 85% 备用方案     │  │
│          │                                  │  └─────────────────┘  │
│ 📌我的会话│  [用户消息气泡]                   │───────────────────────│
│  ⛔👥👑🔁 │  [坐席消息气泡]                   │  🔍 搜索快速回复 /    │
│  张伟    │  🤖 AI推荐回复                    │  Alt+1│Alt+2│...     │
│  👥👑    │  ┌────────────────────────────┐  │  ┌─────────────────┐  │
│  陈芳    │  │①确认版本 → ②清除缓存 → ...│  │  │ VPN连接失败...   │  │
│          │  └────────────────────────────┘  │  │ VPN证书过期...   │  │
│ 👥同事会话│  💬 [回复输入框]          [发送] │  └─────────────────┘  │
│ (折叠)   │──────────────────────────────────│  Alt+1~5 ↑↓ Enter /   │
│          │  🔧 排查步骤  [▶展开全流程图]     │                       │
│ 🕐历史会话│  ①确认版本→②清除缓存→③远程排查→.. │                       │
│ (折叠)   │                                  │                       │
│──────────│                                  │                       │
│ 📋待办事项│                                  │                       │
│ 🔴工单   │                                  │                       │
│ 🟣审批   │                                  │                       │
│ 🟠设备   │                                  │                       │
├──────────┤                                  │                       │
│ 在线4 忙2│                                  │                       │
└──────────┴──────────────────────────────────┴───────────────────────┘
```

### 4.2 IT 等级徽标设计

| 等级 | 标识 | 配色 | CSS 类名 | 说明 |
|------|------|------|---------|------|
| 青铜 | 🛡️ 青铜 Lv.1 | 棕色渐变 `#78350f→#92400e`，文字 `#fef3c7`，边框 `#b45309` | `.bronze` | 基础操作需指导 |
| 白银 | 🛡️ 白银 Lv.2 | 灰色渐变 `#374151→#6b7280`，文字 `#f3f4f6`，边框 `#9ca3af` | `.silver` | 能完成常规操作 |
| 黄金 | 🥇 黄金 Lv.3 | 金色渐变 `#92400e→#d97706`，文字 `#fffbeb`，边框 `#f59e0b` | `.gold` | 熟练使用，高级操作需指导 |
| 铂金 | 💎 铂金 Lv.4 | 青蓝渐变 `#164e63→#0e7490`，文字 `#cffafe`，边框 `#22d3ee` | `.platinum` | 独立解决大部分问题 |
| 钻石 | 💎 钻石 Lv.5 | 靛蓝渐变 `#312e81→#4338ca`，文字 `#e0e7ff`，边框 `#818cf8` | `.diamond` | 高级排障能力 |
| 星耀 | ⭐ 星耀 Lv.6 | 粉紫渐变 `#831843→#be185d`，文字 `#fce7f3`，边框 `#ec4899` | `.star` | 技术专家级 |
| 王者 | 👑 王者 Lv.7 | 橙红渐变 `#7c2d12→#c2410c`，文字 `#ffedd5`，边框 `#f97316` + **发光动画** | `.king` | IT 管理员级 |

> 王者徽标特有动画：`king-glow`，`box-shadow` 在 `0 0 4px` 和 `0 0 10px` 之间交替，2s 循环

### 4.3 待办事项 → 中间栏视图切换

```
点击左侧「工单」→ 中间栏切换为：
┌──────────────────────────────────────────────┐
│ ← 返回会话    工单 #20240606001    [运维工单]  │
├──────────────────────────────────────────────┤
│ 📋 工单描述                                    │
│ 标题: CEO办公室 - 投屏设备故障                    │
│ 优先级: 🔴 紧急    SLA: ⏰ 剩余 12 分钟          │
│ ...描述详情...                                  │
│                                                │
│ 📍 处理进度                                     │
│ 状态: ⏳ 待接单    接单人: 未分配                  │
├──────────────────────────────────────────────┤
│ [📥 接单] [🔧 开始处理] [✅ 结单] [🔄 转派]     │
└──────────────────────────────────────────────┘
```

---

## 5. 数据模型变更

### 5.1 Employee 模型新增字段

```python
# 新增字段（在 models/employee.py 中追加）
it_level: Mapped[str] = mapped_column(
    String(20), nullable=False, default="silver",
    comment="IT技能等级: bronze/silver/gold/platinum/diamond/star/king"
)
it_level_source: Mapped[str] = mapped_column(
    String(20), nullable=False, default="system",
    comment="等级来源: system(系统初评)/manual(坐席手动)"
)
notes: Mapped[dict] = mapped_column(
    JSON, nullable=False, default=dict,
    comment="坐席备注(JSON): {pregnancy, preferred_time, special_needs, ...}"
)
```

### 5.2 Conversation 模型新增字段

```python
# 新增字段（在 models/conversation.py 中追加）
impact_scope: Mapped[int] = mapped_column(
    Integer, nullable=False, default=0,
    comment="影响范围(受影响人数)"
)
is_blocking: Mapped[bool] = mapped_column(
    Boolean, nullable=False, default=False,
    comment="阻断性标记: 是否导致用户无法工作"
)
emotion_state: Mapped[str] = mapped_column(
    String(20), nullable=False, default="normal",
    comment="情绪状态: normal/anxious/angry/urgent"
)
```

### 5.3 新增 TodoItem 模型

```python
class TodoItem(Base):
    __tablename__ = "todo_items"
    id: Mapped[str]           # UUID 主键
    type: Mapped[str]         # ticket/approval/device
    title: Mapped[str]        # 标题
    priority: Mapped[str]     # urgent/high/normal
    description: Mapped[dict] # JSON，类型专属详情
    status: Mapped[str]       # pending/processing/resolved
    assigned_agent_id: Mapped[str | None]  # 分配坐席
    corp_id: Mapped[str]      # 企业ID
    created_at: Mapped[datetime]
    updated_at: Mapped[datetime]
```

### 5.4 新增 TroubleshootingTemplate 模型

```python
class TroubleshootingTemplate(Base):
    __tablename__ = "troubleshooting_templates"
    id: Mapped[str]           # UUID 主键
    name: Mapped[str]         # 模板名称，如 "VPN连接失败"
    category: Mapped[str]     # 分类：vpn/email/system/account
    path_steps: Mapped[list]  # JSON，最优路径步骤 [{label, status}]
    flowchart: Mapped[dict]   # JSON，完整决策树（含判断节点、分支）
    is_active: Mapped[bool]   # 是否启用
    created_at: Mapped[datetime]
    updated_at: Mapped[datetime]
```

---

## 6. API 变更概要

### 6.1 新增端点

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/todo-items` | 获取当前坐席待办列表 |
| GET | `/api/todo-items/{id}` | 获取待办详情 |
| PUT | `/api/todo-items/{id}/status` | 更新待办状态 |
| GET | `/api/troubleshooting-templates` | 获取排查模板列表 |
| GET | `/api/troubleshooting-templates/{id}` | 获取排查模板详情 |
| POST | `/api/troubleshooting-templates` | 新增排查模板（管理员） |
| PUT | `/api/troubleshooting-templates/{id}` | 修改排查模板（管理员） |
| DELETE | `/api/troubleshooting-templates/{id}` | 删除排查模板（管理员） |
| PUT | `/api/employees/{id}/it-level` | 坐席手动调整 IT 等级 |

### 6.2 修改端点

| 方法 | 路径 | 变更说明 |
|------|------|---------|
| GET | `/api/conversations` | 响应新增 `impact_scope`, `is_blocking`, `emotion_state` 字段 |
| GET | `/api/conversations/{id}` | 同上 |
| GET | `/api/employees/{id}` | 响应新增 `it_level`, `it_level_source`, `notes` 字段 |

---

## 7. 组件变更矩阵

| 组件 | 变更类型 | 说明 |
|------|---------|------|
| `Workspace.vue` | **重构** | 顶部栏独立为 `TopBar.vue`；移除应急模式横幅到 TopBar；三栏布局微调 |
| `ConversationList.vue` | **重构** | 三段折叠替代原六段；搜索区增加筛选标签；底部新增待办事项面板 |
| `ConversationItem.vue` | **修改** | 新增优先级图标渲染（⛔👥⭐🔁）；移除 IT 等级徽标 |
| `ChatArea.vue` | **重构** | 顶部栏替换为 `UserInfoBar.vue`；底部新增 `TroubleshootBar.vue`；新增视图切换逻辑（聊天/任务详情） |
| `AiAssistantPanel.vue` | **完全重写** | 移除 5 Tab，改为上下两区（AI 推荐 ~1/3 + 快速回复 ~2/3） |
| `QuickReplyPanel.vue` | **重写** | 搜索栏置顶 + Alt 分类切换 + ↑↓ 键盘导航 + Enter 确认填入 + 底部键盘指南 |
| `RiskAlert.vue` | **废弃** | 功能移除 |
| `UserInfoPanel.vue` | **废弃** | 功能并入 `UserInfoBar.vue` |
| `AiSuggestReply.vue` | **修改** | 移至右栏上方 AI 推荐区；增加置信度显示 + Ctrl 快捷键 |
| `TopBar.vue` | **新增** | 独立顶栏组件（系统名称 + 主题切换 + 坐席信息 + 应急模式） |
| `UserInfoBar.vue` | **新增** | 聊天区顶部用户信息栏（chips + 展开详情 6 卡片） |
| `AiRecommendInline.vue` | **新增** | 聊天区内 AI 推荐回复（Ctrl+1/2/3 快捷填入） |
| `TroubleshootBar.vue` | **新增** | 排查步骤栏（路径视图 + 可展开流程图） |
| `TodoPanel.vue` | **新增** | 左栏底部待办事项面板 |
| `TaskDetailView.vue` | **新增** | 中间栏任务详情视图（工单/审批/设备三种子视图） |
| `ItLevelBadge.vue` | **新增** | IT 等级徽标组件（7 级段位 + 渐变配色 + 王者发光动画） |
| `useKeyboardShortcuts.ts` | **新增** | 全局快捷键管理 composable |
| `useTheme.ts` | **新增** | 主题切换 composable（CSS 变量 + localStorage 持久化） |
| `stores/todo.ts` | **新增** | 待办事项 Pinia Store |
| `stores/theme.ts` | **新增** | 主题 Pinia Store |
| `api/todo.ts` | **新增** | 待办事项 API |
| `api/troubleshooting.ts` | **新增** | 排查模板 API |

---

## 8. 待确认问题

| # | 问题 | 影响范围 | 建议 |
|---|------|---------|------|
| 1 | **情绪状态识别方式**：由 AI 自动分析消息内容识别，还是由坐席手动标记？ | BE-02, FE-04 | 建议先 AI 自动识别 + 坐席可手动修正 |
| 2 | **影响范围数据来源**：是员工自行填写、系统自动判断（如根据部门人数），还是坐席标记？ | BE-02 | 建议坐席手动标记为主，后续迭代增加 AI 辅助判断 |
| 3 | **排查模板与问题分类的关联**：排查模板如何匹配到当前会话？是按标签自动匹配还是坐席手动选择？ | BE-04, FE-06 | 建议 P0 坐席手动选择模板，P2 再做自动匹配 |
| 4 | **待办事项与外部系统对接时机**：工单/审批/设备的真实系统 API 何时对接？ | BE-03 | 已确认 Mock 先行，前端 UI 做完整交互 |
| 5 | **IT 等级在用户端显示方式**：用户端看到的 IT 等级是完整徽标还是简化文本？ | FE-04, BE-01 | 需与用户端（H5）产品确认 |
| 6 | **同事会话区的数据筛选**：「同事会话」是显示所有其他坐席的进行中会话，还是仅显示同组/同部门坐席的？ | FE-02 | 建议先显示同组坐席，后续可配置 |
| 7 | **排查步骤栏的高度**：排查步骤栏始终可见会占用聊天区空间，是否需要设置最小/最大高度？ | FE-06 | 参考原型：默认路径视图 ~44px，展开流程图最大 300px |
| 8 | **AI 推荐回复的触发时机**：是每条用户消息后都触发，还是有条件触发？ | FE-05 | 已确认仅坐席未回复时显示 |
| 9 | **原 6 区到 3 段的数据映射**：原"待接单"区并入"我的会话"还是独立显示？原"协作会话"区并入哪个段？ | FE-02 | 需确认分区数据映射规则 |

---

## 9. 关键决策记录

| # | 决策 | 依据 |
|---|------|------|
| 1 | 外部系统对接 Mock 先行，前端 UI 做完整交互 | 避免被外部系统 API 阻塞前端开发进度 |
| 2 | IT 等级采用混合模式（系统初评 + 坐席手动调整） | 系统自动评分不够准确，需坐席校准 |
| 3 | 排查步骤数据源为静态模板库 | 预置常见问题模板即可满足 MVP，后续可扩展为动态生成 |
| 4 | 右栏移除 5 Tab 结构，改为上下两区 | 原型验证：坐席主要使用 AI 推荐和快速回复，其他功能使用频率低 |
| 5 | 会话列表不显示 IT 等级徽标 | 避免信息过载，IT 等级在聊天区详情展示更合适 |
| 6 | 排查步骤栏整体不可收起 | 确保坐席始终能看到排查进度，避免遗漏步骤 |
| 7 | 原型样式已锁定（v5.3 版），调整样式前必须与用户确认 | 保证开发产出与设计稿一致 |

---

## 10. 里程碑建议

| 阶段 | 范围 | 预估周期 |
|------|------|---------|
| **Phase 1 — 基础框架** | FE-01 主题系统 + FE-09 系统名称 + BE-01/02 模型扩展 + 数据库迁移 | 2-3 天 |
| **Phase 2 — 左栏改造** | FE-02 三段折叠 + 优先级图标 + FE-03 待办面板 + BE-03 TodoItem API | 2-3 天 |
| **Phase 3 — 中栏改造** | FE-04 用户信息栏 + FE-05 AI 推荐内联 + FE-06 排查步骤栏 | 3-4 天 |
| **Phase 4 — 右栏改造** | FE-08 AI 助手面板重构 + BE-04 排查模板 API | 2-3 天 |
| **Phase 5 — 任务视图** | FE-07 视图切换 + 工单/审批/设备 3 种子页面 | 2-3 天 |
| **Phase 6 — 增强打磨** | FE-10 快捷键 + FE-11 IT 等级调整 + FE-12 过渡动画 + 联调测试 | 2-3 天 |

---

## 18. 管理后台远景规划

> **决策状态**: 已确认（2026-06-08）
> **决策依据**: 本平台未来产品、开发、维护人员并非专业岗位人员，所有模块功能需尽可能解耦，产品开发阶段和功能模块颗粒度需符合零基础岗位人员特点。

### 18.1 产品定位

管理后台是 IT 智能服务台的**第三端产品**（与员工端 H5、坐席工作台并列），面向**坐席组长**，提供系统配置、人员管理、内容运营、数据监控等能力。

**核心原则**：
- 运维人员能通过管理后台配置一切，代码修改仍需开发
- 代码修改由零开发基础员工逐步成长，但要合理控制代码开发变更颗粒度和影响范围
- 单功能单模块，每个菜单项可独立启用/禁用
- 配置优于代码，导入导出标准格式统一用 JSON/CSV
- 变更可回滚，每次配置变更记录版本

### 18.2 功能模块清单

| # | 模块 | 功能描述 | 优先级 | 上线阶段 | 备注 |
|---|------|---------|--------|---------|------|
| 1 | **功能开关/参数** | 按阶段控制功能开放，运行时切换无需改代码 | P0 | 阶段一 | 阶段一仅开核心功能，后续阶段解锁排队/评分等 |
| 2 | **坐席人员管理** | 在线/离线状态、技能标签（参考快速回复7大类）、权限分级（角色→权限组） | P0 | 阶段一 | 技能标签与快速回复分类对齐：电脑/软件/外设/网络/安全/资产/其他 |
| 3 | **消息分配模式** | 阶段一仅手动接单，后续按坐席规模扩展自动分配 | P1 | 阶段一(手动) → 阶段二+(自动) | 当前1人足够，手动接单完全满足；6种模式为远景规划，详见 §18.3 |
| 4 | **快速回复管理** | 分类管理 + 版本历史 + 审核发布流程 | P1 | 阶段一 | 审核通过前不影响提交人自己使用（提交人可用待审核版本） |
| 5 | **主题模板管理** | 三层管理（全局默认→坐席端→H5端），支持节日/活动主题 | P2 | 阶段二 | 三层统一一个主题体系，未来可加入节日和活动主题 |
| 6 | **会话监控** | 实时查看坐席工作状态、会话队列、异常告警（超时未响应等） | P1 | 阶段二 | 先出 Demo |
| 7 | **数据看板** | 坐席绩效（响应时间/结单率/AI采纳率）、满意度趋势、热点问题排行 | P1 | 阶段四 | 先出 Demo |
| 8 | **排查流程图管理** | JSON 导入导出 + 预览 + 版本管理 | P1 | 阶段三 | 后续升级为可视化拖拽编辑 |
| 9 | **知识库管理** | 标注→知识条目→迭代闭环 | P2 | 阶段四 | 与 RAGFlow 集成，详见 §19 |
| 10 | **外部系统集成** | Dify/RAGFlow/数据平台连接管理 + 同步日志 | P0~P2 | 阶段二起 | 详见 §19 |

### 18.3 消息分配模式

> **现状校准（2026-06-08）**：当前人工咨询量和坐席人员数量 1 人足以承担，引入多坐席主要是 AB 角色设置和冗余考虑。因此阶段一只需手动接单，自动分配模式为远景规划，按坐席规模增长渐次启用。

| # | 模式 | 描述 | 适用场景 | 启用时机 | 优先级 |
|---|------|------|---------|---------|--------|
| 1 | **手动接单** | 坐席在待办列表中自行选择接单 | 当前唯一模式：1人足以承担，AB角冗余 | ✅ 阶段一 | P0 |
| 2 | **轮询分配** | 按坐席列表顺序依次分配，循环往复 | 坐席≥3人且能力均匀 | 坐席≥3人时 | P2 |
| 3 | **最少活跃优先** | 自动分配给当前活跃会话数最少的坐席 | 坐席处理速度有差异 | 坐席≥3人时 | P2 |
| 4 | **加权比例分配** | 按坐席权重分配（如高级权重2、初级权重1） | 坐席能力分层明显 | 坐席≥5人时 | P3 |
| 5 | **技能匹配分配** | 根据问题类别匹配坐席技能标签 | 专业化分工 | 坐席≥5人+技能标签体系成熟时 | P3 |
| 6 | **优先队列** | 紧急/阻断性问题优先路由到高级坐席/组长 | 需要快速响应高优问题 | 坐席≥5人+紧急度评分上线时 | P3 |

**设计原则**：
- 阶段一管理后台分配模式设置页仅显示「手动接单」一项，界面简洁
- 后续模式按坐席规模自动解锁（如坐席<3人时自动分配选项灰显并提示"坐席人数不足3人，暂不需要"）
- 所有模式均支持热切换，不需重启服务

### 18.4 快速回复管理 — 审核流程

```
坐席提交模板 → 状态: 待审核（仅提交人可用）
    ↓
坐席组长审核 → 通过: 全员可见 / 驳回: 返回修改
    ↓
版本历史保留，支持回滚到任意版本
```

### 18.5 主题模板管理 — 三层架构

```
全局默认主题 ──→ 坐席端主题覆盖 ──→ H5端主题覆盖
    │                │                   │
    └─ 基础色板       └─ 坐席工作台专属     └─ 员工端专属
    └─ 字体/圆角      └─ 优先级高于全局      └─ 优先级高于全局

特殊主题：节日/活动主题 → 临时覆盖三层，到期自动恢复
```

---

## 19. 系统生态与集成规划

> **决策状态**: 已确认（2026-06-08）
> **核心策略**: 管理后台先建 + 集成渐次接入

### 19.1 五系统生态架构

| 系统 | 职责 | 部署位置 | 当前集成度 |
|------|------|---------|-----------|
| **IT智能服务台** | 员工端H5 + 坐席工作台 + 管理后台 | NAS Docker (Cloudflare Tunnel) | — |
| **Dify** | AI对话引擎（Agent1 员工自助 + Agent2 坐席辅助） | 公司内网 | 100%（dify2openai 集成） |
| **RAGFlow** | 知识库检索（Dify 通过 RAGFlow 获取知识） | 公司内网 | 0%（Dify 间接调用） |
| **智能IT助手数据处理平台** | 会话数据分析、报表、运营指标 | 公司内网 | 0%（物理隔离） |
| **企业微信** | 消息通道、身份认证、组织架构 | 企微云 | 100%（回调+API） |

### 19.2 Dify 管理边界

| 管理后台管的 | 仍在 Dify 网页管的 |
|------------|-----------------|
| Agent Key/URL 配置 | Workflow 逻辑设计 |
| System Prompt 参数 | 知识库与 Agent 绑定 |
| 转人工关键字列表 | 对话日志查看 |
| AI 命中阈值参数 | dify2openai 桥接配置 |

**设计原则**：管理后台管「配置和参数」，Dify 网页管「Workflow 逻辑」，两者边界明确。

### 19.3 RAGFlow 集成 — 知识库迭代闭环

**同步触发方式**: 阈值触发自动推送，管理员仅审核

```
坐席标注 → 同类问题超过 N 次 → 管理后台自动推荐「加入知识库」
    ↓
管理员确认 → 管理后台生成 FAQ 条目 → RAGFlow API 推送 → 知识库更新
    ↓
下次同类问题 → L1 流程图命中（不走 AI）→ 成本下降
```

**标注粒度**: 标注 + 坐席实际回复内容（不只是「有效/无效」，还记录坐席实际发了什么）

### 19.4 数据处理平台集成

**策略**: 短期 B+C，长期 A

| 阶段 | 方式 | 描述 |
|------|------|------|
| **短期** | B. 数据库只读 | 数据平台直连新系统 PostgreSQL（只读视图），获取全量会话/消息/评分数据 |
| **短期** | C. 看板嵌入 | 数据平台看板 URL 嵌入管理后台 iframe，体验统一 |
| **长期** | A. API 推送 | 会话结单时管理后台推送标签/评分到数据平台 API |

**数据同步内容**:

| 数据 | 同步方向 | 时机 |
|------|---------|------|
| 会话标签 | 服务台 → 数据平台 | 会话结单时 |
| 满意度评分 | 服务台 → 数据平台 | 员工评分后 |
| 坐席绩效 | 服务台 → 数据平台 | 每日汇总 |
| 运营报表 | 数据平台 → 管理后台 | iframe 嵌入实时查看 |

### 19.5 外部系统集成模块

| 子模块 | 功能 | 优先级 |
|--------|------|--------|
| Dify 连接管理 | API URL/Key 配置、连接测试、Agent 状态查看 | P0 |
| RAGFlow 连接管理 | API URL/Key 配置、知识库列表查看、同步状态 | P1 |
| 数据平台连接管理 | 数据库连接配置、看板 URL 嵌入、同步状态 | P1 |
| 同步日志 | 所有外部系统的推送/拉取记录、成功/失败统计 | P1 |
| 流程图→Dify 导出 | L1 流程图导出为 Dify 变量/知识条目 | P2 |

### 19.6 AI 混合策略 — 四层架构

> **决策状态**: 已确认（2026-06-08）
> **核心原则**: 不过度依赖 AI 实时能力，采用「固定流程图 + AI 动态能力 + 标注 + 迭代」混合模式，在响应速度、算力成本、管理可控、迭代循环实现最佳实践。

| 层级 | 名称 | 机制 | 成本 | 响应速度 | 可控性 |
|------|------|------|------|---------|--------|
| **L1** | 固定流程图 | 确定性分支树，关键词/规则匹配 | 零 | 毫秒级 | 100% |
| **L2** | AI 动态能力 | Dify Agent 调用（RAGFlow 检索增强） | 高 | 2-5秒 | 中 |
| **L3** | 人工标注 | 坐席对 AI 建议标注「有效/无效/部分有效」+ 实际回复内容 | 低 | 即时 | 高 |
| **L4** | 迭代闭环 | 高频问题→流程图补充，AI 命中率低→知识库补充 | 低 | 批量 | 高 |

**迭代目标**: 不断将 L2 的问题「降级」到 L1，提升系统确定性和响应速度，降低 AI 算力成本。

**L1 流程图编辑方式**:
- 阶段三: JSON 导入导出 + 预览（实现快、零基础人员可用）
- 后续升级: 可视化拖拽编辑

**迭代触发机制**: 阈值自动推荐（超过 N 次同类问题 → 管理后台弹推荐），管理员确认后执行

**关键设计原则**: AI 的 system prompt 中应注入当前流程图的结构摘要，让 AI 在已有流程图覆盖的领域内回答时与流程图保持一致。

### 19.7 排查流程图与 Dify 结合 — 实现路径

> **决策状态**: 已确认（2026-06-08），接收推荐的分阶段实现路径

#### 可行性矩阵

| 结合点 | 可行性 | 实现方式 |
|--------|--------|---------|
| 流程图→Dify System Prompt 注入 | ✅ 完全可行 | 导出为结构化文本→注入 Agent system prompt 变量 |
| 流程图→Dify 知识条目 | ✅ 完全可行 | 每个分支导出为 FAQ 对→推送 RAGFlow→Dify 通过 RAGFlow 检索 |
| 流程图→Dify Workflow 节点 | ⚠️ 有限可行 | Dify 不开放 Workflow 编辑 API，但可通过 HTTP 请求节点回调管理后台获取流程图分支 |
| Dify 对话结果→流程图标注 | ✅ 完全可行 | AI 回复后自动记录命中/未命中流程图，统计覆盖率 |

#### 分阶段实现路径

| 阶段 | 实现内容 | 对应子阶段 | 交付物 |
|------|---------|-----------|--------|
| **Step 1** | JSON 导入导出 + 预览 | 3B | 管理后台可管理流程图 JSON，坐席端展示流程图 |
| **Step 2** | 流程图导出为 Dify 变量/知识条目 | 4A | 管理后台一键导出→Dify system prompt 注入/RAGFlow 推送 |
| **Step 3** | Dify HTTP 请求节点回调流程图分支 | 4C | Dify Agent 可实时查询流程图分支，动态决策 |
| **Step 4** | 可视化拖拽编辑 | 远景 | 管理后台可视化编辑流程图，替代 JSON 手写 |

**Step 1→2 的关键价值**：流程图从「仅坐席可见的参考」升级为「AI 也遵循的规则」，实现 L1+L2 一致性。

---

## 20. 阶段细化与并行推进策略

> **决策状态**: 已确认（2026-06-08）
> **核心策略**: 资源审批期间并行推进不受阻断影响的需求，避免停工等待

### 20.1 阶段细化（子阶段划分）

每个子阶段独立可交付，不受其他子阶段阻断：

#### 阶段一：转人工改H5 + 坐席MVP + 管理后台骨架

| 子阶段 | 范围 | 独立可交付物 | 外部依赖 |
|--------|------|-------------|---------|
| **1A** | H5 Mock登录 + 坐席MVP + 邀请功能 | 员工手动登录→坐席可接单回复→坐席可邀请员工/部门加入会话 | 无 |
| **1B** | 管理后台骨架 | 功能开关 + 坐席管理 + 快速回复管理 | 无 |
| **1C** | 端到端验证 | 完整链路跑通 + 修复缺陷 | 需完整环境 |

#### 阶段二：H5全流程 + 实时推送 + 排队

| 子阶段 | 范围 | 独立可交付物 | 外部依赖 |
|--------|------|-------------|---------|
| **2A** | WebSocket推送 | 员工端实时消息 | 无 |
| **2B** | 排队分配 | 手动接单（已满足当前1人需求），自动分配按坐席规模渐次解锁 | 无 |
| **2C** | 满意度评分 | H5评分 + 后端存储 | 无 |
| **2D** | OAuth2切换 | 公司域名就绪后一键切回 | 公司备案域名 |

#### 阶段三：AI Wingman + 排查流程图

| 子阶段 | 范围 | 独立可交付物 | 外部依赖 |
|--------|------|-------------|---------|
| **3A** | AI Wingman验证 | Agent2 Key填入 + 草稿/摘要验证 | Dify Agent2 创建 |
| **3B** | 排查流程图+AI混合 | L1流程图管理(JSON) + L2 AI兜底 + 管理后台流程图模块 | 无 |
| **3C** | 标注体系 | 坐席标注 + 数据沉淀 + 阈值推荐 | 无 |

#### 阶段四：迭代闭环 + 数据看板

| 子阶段 | 范围 | 独立可交付物 | 外部依赖 |
|--------|------|-------------|---------|
| **4A** | 迭代闭环 | 高频问题→流程图补充 + RAGFlow 知识库推送 | RAGFlow API 联调 |
| **4B** | 数据看板 | 绩效/满意度/热点 + 数据平台集成 | 数据平台联调 |
| **4C** | 知识库管理 | 标注→知识条目→迭代闭环 | 无 |

### 20.2 并行推进策略

**核心原则**: P0 阻断项依赖外部资源审批，不等审批完成，并行推进不受阻断影响的需求。

| 外部依赖 | 阻断的子阶段 | 可并行推进的子阶段 |
|---------|------------|-----------------|
| 公司备案域名 | 2D（OAuth2切换） | 1A/1B/1C/2A/2B/2C/3A/3B/3C/4A/4B/4C |
| Dify Agent2 创建 | 3A（Wingman验证） | 1A/1B/1C/2A/2B/2C/3B/3C/4A/4B/4C |
| RAGFlow API 联调 | 4A（迭代闭环-知识推送） | 1A/1B/1C/2A/2B/2C/3A/3B/3C/4B/4C |
| 数据平台联调 | 4B（数据看板-平台集成） | 1A/1B/1C/2A/2B/2C/3A/3B/3C/4A/4C |

### 20.3 资源审批期间推荐推进事项

在 OAuth2 公司域名审批期间，优先推进以下**零外部依赖**的工作：

| 优先级 | 工作内容 | 所属子阶段 |
|--------|---------|-----------|
| 🔴 最高 | 管理后台骨架（功能开关+坐席管理+快速回复管理） | 1B |
| 🔴 最高 | 端到端测试验证 | 1C |
| 🟡 高 | H5 WebSocket 推送实现 | 2A |
| 🟡 高 | 手动接单优化（当前1人足够，AB角冗余场景） | 2B |
| 🟢 中 | 满意度评分组件 | 2C |
| 🟢 中 | 排查流程图 JSON 导入导出 + 预览 | 3B |

---

> **文档结束** — 本PRD涵盖企微IT智能服务台全部已确认设计决策和约束，作为后续架构设计和开发实施的基准文档。v1.0 新增管理后台远景规划、系统生态与集成规划、阶段细化与并行推进策略。

---

## 21. 邀请功能设计 — 多人会话协作

> **设计日期**: 2026-06-10 | **设计者**: 宋献 | **状态**: 方案已确认，纳入M1 MVP
> **原型文件**: `docs/prototypes/invite-flow-v1.html`
> **技术方案**: `docs/邀请功能-技术方案.md`

### 21.1 背景与动机

**问题场景**：IT坐席在处理会话时，经常需要拉入其他同事协助（如网络问题需要网络组同事确认、软件授权需要资产管理同事查证）。当前只有1对1模式，坐席只能手动告知对方会话内容，效率极低。

**方案选型**（2026-06-10 确认）：

| 方案 | 核心思路 | 可行性 | 结论 |
|------|---------|--------|------|
| 方案一：一对一+邀请 | 在现有会话上扩展参与者，企微应用消息通知 | ✅ 完全可行 | 备选 |
| 方案二：应用群聊 | 企微appchat创建群，群内沟通 | ❌ 应用无法接收群内消息回调 | 不可行 |
| **方案三：WebSocket+应用消息双通道** | **在现有架构上扩展，后端维护参与者列表** | ✅ **完全可行，零新增基础设施** | **当前方案** |

**方案二不可行的原因**：企微appchat是「应用推送消息群」，群成员在群内的发言**不会回调给应用**。应用只能单向推送消息到群，无法看到用户回复，坐席工作台无法获取群内对话。

### 21.2 核心设计理念

**邀请 ≠ 群聊**。邀请是在现有1对1会话基础上，将新参与者加入同一会话的协作模式：

```
原始：员工 ←→ 坐席（1对1）
邀请后：员工 ←→ 坐席 + 被邀请人A + 被邀请人B（多人同一会话）
```

- 所有参与者在同一会话中看到完整对话
- 坐席始终是会话的"主控者"（创建/结单/转接权限）
- 被邀请人是"协作者"（可查看和回复，不可结单/邀请他人）

### 21.3 用户故事

| # | 角色 | 故事 | 验收标准 |
|---|------|------|---------|
| US-14 | IT坐席 | 处理网络问题时，我想邀请网络组的同事直接进入当前会话查看情况并回复，不用我手动转发聊天记录 | 坐席点击邀请→选择人员→对方收到通知→加入会话→可看到历史消息并发送回复 |
| US-15 | IT坐席 | 邀请同事时，我想选择共享多少历史消息，避免对方被大量无关信息淹没 | 邀请时可选择共享模式（全部/最近10条/不共享），默认最近10条 |
| US-16 | IT坐席 | 我需要邀请整个部门参与，比如让安全组的同学一起排查 | 可按部门批量邀请，勾选部门=邀请全部门成员 |
| US-17 | 被邀请员工 | 收到邀请通知后，我希望一键加入会话，看到之前的问题上下文 | 点击企微通知→H5加载→看到共享历史→可发送消息 |
| US-18 | 被邀请员工 | 我协助完成后，想退出这个会话，不再收到消息 | 被邀请人可主动退出，退出后会话列表中不再显示 |

### 21.4 功能规格

#### 21.4.1 邀请发起（坐席端）

| 功能点 | 规格 |
|--------|------|
| 入口 | 会话详情头部工具栏「+ 邀请」按钮 |
| 选人方式 | ①搜索姓名/工号 ②组织架构树浏览 ③按部门批量勾选 |
| 组织架构数据 | 后端调用企微通讯录API，前端渲染部门树 |
| 历史消息共享 | 三选一：全部 / **最近10条**（默认）/ 不共享 |
| 邀请确认 | 显示已选人员列表 + 共享模式，确认后调用后端接口 |
| 人数提醒 | >10人时弹窗提醒"建议优先邀请关键人员"，不设硬上限 |

#### 21.4.2 通知与加入（被邀请人端）

| 功能点 | 规格 |
|--------|------|
| 通知方式 | 企微应用消息（template_card 卡片消息） |
| 卡片内容 | 邀请人姓名 + 发起人姓名 + 问题摘要（最近1条消息截取50字） + 「加入会话」按钮 |
| 加入方式 | 点击按钮→H5页面→自动加载会话（Mock登录或OAuth2） |
| 历史消息 | 根据邀请时的共享模式，加载对应历史消息 |
| 加入广播 | 加入后自动在会话中发送系统消息「XX已加入会话」 |

#### 21.4.3 多人会话（所有参与者）

| 角色 | 查看消息 | 发送消息 | 邀请他人 | 结单/转接 | 退出 |
|------|---------|---------|---------|----------|------|
| 原始员工 | ✅ | ✅ | ❌ | ❌ | 关闭页面即退出 |
| 主责坐席 | ✅ | ✅ | ✅ | ✅ | ❌（主责不可退） |
| 被邀请人 | ✅ | ✅ | ❌ | ❌ | ✅ |

#### 21.4.4 参与者管理

| 功能点 | 规格 |
|--------|------|
| 参与者显示 | 会话详情头部显示参与者头像+姓名，hover显示角色标签 |
| 系统消息 | 邀请/加入/退出均广播系统消息，所有参与者可见 |
| 退出机制 | 被邀请人点击「退出会话」→ 确认 → 从participants移除 → 广播系统消息 |
| 坐席视角 | 坐席工作台可查看参与者列表，可移除被邀请人 |

### 21.5 与「摇人」的关系

| 维度 | 摇人（§9） | 邀请功能（§21） |
|------|-----------|---------------|
| 邀请对象 | 坐席 → 坐席 | 坐席 → 任意员工/部门 |
| 通信通道 | WebSocket（坐席内部） | WebSocket + 企微应用消息（跨端） |
| 被邀请人入口 | 坐席工作台内弹窗通知 | 企微应用消息→H5页面 |
| 典型场景 | 坐席A请坐席B协助同一问题 | 坐席请网络组同事确认现场情况 |
| 数据字段 | `collaborating_agent_ids` | `participants` |
| 权限 | 协作坐席可邀请其他坐席 | 只有主责坐席可邀请员工 |

> **两套机制独立但互补**：摇人解决坐席间协作，邀请解决跨部门/跨角色协作。

### 21.6 非目标（Non-goals）

| 不做什么 | 原因 |
|---------|------|
| 不做企微群聊同步 | appchat API无法接收群内消息，技术上不可行 |
| 不做被邀请人二次邀请 | 防止邀请链失控，只有主责坐席能发起邀请 |
| 不做邀请审批流程 | 邀请是即时协作需求，加审批会破坏时效性 |
| 不做音视频通话 | 当前只做文字协作，音视频是独立功能 |
| 不做跨企业邀请 | 阶段一仅限内部员工，互联企业是阶段四的P2需求 |
| 不做文件/图片共享 | 阶段一支持文本+文件上传，图片粘贴共享留到阶段二 |

### 21.7 交互原型

详见 `docs/prototypes/invite-flow-v1.html`，包含9步完整交互流程：

1. 架构概览（SVG流程图）
2. 一对一会话中 → 点击邀请
3. 选人弹窗（组织架构树+已选列表+历史共享设置）
4. 批量选部门
5. 历史消息共享模式选择
6. 确认邀请（后端6步时序）
7. 企微通知卡片样式
8. 加入会话流程
9. 多人会话双视角对照

### 21.8 依赖与前提

| 依赖 | 状态 | 说明 |
|------|------|------|
| 企微通讯录API | ✅ 已有 | 读取部门/员工列表，OAuth2授权后可调用 |
| 企微应用消息推送 | ✅ 已有 | `/message/send` 推送邀请通知 |
| WebSocket通道 | ✅ 已有 | 坐席端和H5端均已实现 |
| H5 Mock登录 | ✅ 已有 | 被邀请人通过H5加入，Mock模式下手动登录 |
| template_card消息 | 🔧 需开发 | 邀请卡片消息类型，当前仅支持text消息 |