wecom_it_smart_desk/docs/01-产品文档/08-集成生态/PRD-REQ-集成-002-管理后台-v1.2.archive.md

# 智能IT支持服务台 — 管理后台增量 PRD

> **文档版本**: v1.2  
> **创建日期**: 2026-06-16 · **更新日期**: 2026-07-28  
> **产品经理**: 许清楚 (Xu) · 宋献  
> **状态**: 阶段一 1B — 已迭代（v1.2 分配模式收编坐席管理 Tab）  
> **关联文档**: `docs/PRD.md` (主 PRD §18-20)、`原型-REQ-集成-000-管理后台-v1.0.html`（原型，与本文档同步更新）

---

## 目录

1. [项目信息](#1-项目信息)
2. [产品定义与目标](#2-产品定义与目标)
3. [用户故事](#3-用户故事)
4. [功能需求池](#4-功能需求池)
5. [页面清单与导航结构](#5-页面清单与导航结构)
6. [已实现功能映射](#6-已实现功能映射)
7. [数据模型扩展方案](#7-数据模型扩展方案)
8. [API 设计概要](#8-api-设计概要)
9. [占位模块规格](#9-占位模块规格)
10. [技术约束与约定](#10-技术约束与约定)
11. [待确认问题](#11-待确认问题)

---

## 1. 项目信息

| 字段 | 值 |
|------|------|
| 产品名称 | 智能IT支持服务台 — 管理后台 |
| 项目代号 | `wecom_it_smart_desk`（第三端：admin） |
| 编程语言 | 前端: Vue 3 + TypeScript + Element Plus + Pinia · 后端: FastAPI + SQLAlchemy + PostgreSQL + Redis |
| 部署路径 | `/itadmin/`（与 H5 `/itdesk/`、坐席 `/itagent/` 并列） |
| 文档语言 | 中文 |
| 原型参考 | `docs/prototypes/admin-dashboard-v1.html`（深色科技风，8页面） |
| 所属阶段 | 阶段一 1B — 管理后台骨架 |

---

## 2. 产品定义与目标

### 2.1 产品定位

管理后台是 IT 智能服务台的**第三端产品**，与员工端 H5（`/itdesk/`）和坐席工作台（`/itagent/`）并列，面向**坐席组长/IT运维负责人**（以下简称"组长"），提供系统配置、人员管理、内容运营三项核心能力。

### 2.2 阶段一 1B 目标

> 先把已实现功能相关的管理后台功能实现，后续项目功能开发时同步完成管理功能开发，未进行的管理功能预留占位。

**1B 交付范围**：
1. **功能开关/参数管理**（P0）— 可视化编辑 `system_configs` 表中的配置项
2. **坐席人员管理**（P0）— 坐席列表 + 角色/技能标签编辑 + 状态查看
3. **快速回复管理**（P1）— 分类列表 + 审核发布流程（坐席提交→组长审核→全员可见）
4. **外部系统集成配置**（P0 占位）— 6个外部系统卡片展示 + 配置入口（仅 Dify 可用）
5. **消息分配模式**（P1 占位，v1.2 起收编为坐席管理页第 2 Tab「分配策略」）— 手动接单为当前模式，其他模式灰化锁定
6. **排查模板管理**（P1 占位）— 模板列表查看 + JSON 导入导出入口（阶段三启用）
7. **运营总览仪表盘**（P0）— 关键指标统计卡片 + 待处理事项 + 系统健康状态

### 2.3 产品目标（3个正交目标）

| # | 目标 | 衡量标准 |
|---|------|---------|
| G1 | **运维自助化** — 组长无需改代码即可调整系统参数、管理人员、审核内容 | 100% 配置项可通过管理后台修改，无需重启 |
| G2 | **操作可追溯** — 配置变更、审核操作记录版本历史 | 每次变更记录操作人和时间戳 |
| G3 | **页面可扩展** — 已规划的 10 个模块在导航中均有对应位置，未实现页面以占位方式呈现 | 所有已规划模块在菜单可见，未来阶段功能有明确入口 |

---

## 3. 用户故事

| ID | 用户故事 | 涉及模块 | 优先级 |
|----|---------|---------|--------|
| US1 | 作为**坐席组长**，我希望能通过可视化界面开关功能模块（如应急模式），而不需要登录服务器修改数据库 | 功能开关 | P0 |
| US2 | 作为**坐席组长**，我希望能查看所有坐席的在线状态、技能标签和当前负载，以便合理分配工作 | 坐席管理 | P0 |
| US3 | 作为**坐席组长**，我希望能编辑坐席的角色（组长/坐席）和技能标签（电脑/网络/软件等），以匹配实际分工 | 坐席管理 | P0 |
| US4 | 作为**坐席组长**，我希望能审核坐席提交的快速回复模板，通过后全员可见，驳回后仅提交人可见 | 快速回复管理 | P1 |
| US5 | 作为**坐席组长**，我希望能查看已连接的外部系统状态，并配置 API Key/URL | 系统集成 | P0 |
| US6 | 作为**坐席组长**，我希望在运营总览页面一目了然地看到在线坐席数、今日会话量、AI命中率等关键指标 | 运营总览 | P0 |
| US7 | 作为**坐席组长**，我希望能通过搜索快速找到某个配置项或坐席，而不需要逐页翻找 | 全局搜索 | P1 |

---

## 4. 功能需求池

### 4.1 P0 功能（阶段一 1B 必须交付）

#### P0-01 运营总览仪表盘

- **功能描述**：管理后台首页，展示4个统计卡片（在线坐席、今日会话、平均响应时间、AI命中率）+ 待处理事项列表 + 系统健康状态
- **对应原型**：`page-dashboard`
- **数据来源**：
  - 在线坐席：`agents` 表 `status='online'` 计数
  - 今日会话：`conversations` 表当日创建数
  - 平均响应时间：`conversations` 表计算（若无则显示占位符）
  - AI命中率：`conversations` 表 `ai_hit` 字段统计
  - 待处理事项：快速回复待审核 + 系统告警
  - 系统健康：各集成系统连接状态
- **后端模型**：`Agent`、`Conversation`、`SystemConfig`
- **API**：需新建 `GET /api/admin/dashboard/overview`
- **复杂度**：S（纯查询+聚合，无写入操作）

#### P0-02 功能开关/参数管理

- **功能描述**：以卡片网格展示按功能模块分组的配置开关，每组包含若干 toggle 开关。配置变更即时生效（更新 `system_configs` 表）。支持回滚（记录旧值）
- **对应原型**：`page-features`（6张功能卡片）
- **功能卡片清单**：

| 卡片 | 配置键 | 当前值来源 | 开关数 |
|------|--------|-----------|--------|
| AI 对话引擎 | `ai_auto_reply`、`hand_raise_keywords`、`intervene_round_threshold` | `system_configs` | 3 |
| 人工服务 | `manual_pickup_enabled`、`invite_employee_enabled` | 新建 | 2 |
| 排队系统 | 阶段二功能，开关灰化 | 无 | 2（灰化） |
| 满意度评价 | 阶段二功能，开关灰化 | 无 | 2（灰化） |
| 应急模式 | `emergency_mode` | `system_configs` | 1 |
| 关键词管理 | `hand_raise_keywords`、`emotion_keywords_*` | `system_configs` | 2组关键词编辑 |

- **编辑交互**：点击关键词旁的"编辑"按钮弹出对话框，支持 JSON 数组编辑；普通开关直接 toggle
- **后端模型**：`SystemConfig`
- **API**：需新建 `GET /api/admin/configs`、`PUT /api/admin/configs/{key}`、`GET /api/admin/configs/{key}/history`
- **复杂度**：M（涉及分组展示、JSON 编辑验证、变更历史）

#### P0-03 坐席人员管理

- **功能描述**：坐席列表（表格形式），支持按状态筛选（全部/在线/忙碌/离线），展示：头像、姓名、工号、状态、技能标签、角色、当前/最大负载、今日结单数。组长可编辑坐席的角色和技能标签
- **对应原型**：`page-agents`
- **扩展需求**（Agent 模型需新增字段）：
  - `role`：VARCHAR(20)，取值 `admin`（组长）/ `agent`（坐席），默认 `agent`
  - `skill_tags`：JSON 数组，取值从 7 大类中选择：`["电脑","软件","外设","网络","安全","资产","其他"]`
- **后端模型**：`Agent`（需扩展）
- **已有 API**：`GET /api/agents`（坐席端用，可复用获取列表）
- **需新建 API**：`PUT /api/admin/agents/{id}`（编辑角色/技能标签）、`POST /api/admin/agents`（添加坐席）、`DELETE /api/admin/agents/{id}`（移除坐席）
- **复杂度**：M（涉及模型扩展 + CRUD + 状态筛选）

#### P0-04 外部系统集成配置（占位）

- **功能描述**：展示 6 个外部系统的集成状态卡片（3×2 网格）。阶段一仅 Dify 和 RAGFlow 可配置（已有后端集成），其余 4 个系统仅展示"未连接"/"待确认"状态
- **对应原型**：`page-integrations`
- **6个系统**：

| 系统 | 阶段一状态 | 可操作 |
|------|-----------|--------|
| Dify AI | 已连接 | 配置（URL/Key）、测试连接 |
| RAGFlow | 部分集成 | 配置（URL/Key） |
| 数据平台 | 未连接 | 仅展示状态 |
| 北森 eHR | 未连接 | 仅展示状态 |
| 火绒安全 | 未连接 | 仅展示状态 |
| 联软安全 | 待确认 | 仅展示状态 + "申请"按钮（无实际功能） |

- **后端模型**：需新建 `IntegrationConfig` 模型（或复用 `SystemConfig` 存 JSON）
- **API**：需新建 `GET /api/admin/integrations`、`PUT /api/admin/integrations/{id}`
- **复杂度**：S（大部分为静态展示 + 2个配置表单）

### 4.2 P1 功能（阶段一 1B 应交付）

#### P1-01 快速回复管理（审核流程）

- **功能描述**：卡片式列表展示快速回复模板，按 7 大分类筛选（电脑/软件/外设/网络/安全/资产/其他）。支持审核流程：坐席提交→状态"待审核"（仅提交人可用）→组长审核通过→"已审核"（全员可见）/ 驳回→返回修改。每个模板展示版本号、变量列表、最后更新时间
- **对应原型**：`page-quickreply`
- **审核状态机**：
  ```
  draft（草稿）→ pending_review（待审核，仅提交人可用）
      ├─→ approved（已审核，全员可见）
      └─→ rejected（驳回，返回修改）
  ```
- **后端模型**：`QuickReplyTemplate`（需扩展 `status`、`version`、`submitted_by` 字段）
- **已有 API**：`GET/POST/PUT/DELETE /api/quick-replies`（坐席端用，需扩展审核逻辑）
- **需新建 API**：`PUT /api/admin/quick-replies/{id}/review`（审核通过/驳回）、`GET /api/admin/quick-replies/pending`（待审核列表）
- **复杂度**：L（涉及审核状态机 + 版本管理 + 权限可见性逻辑）

#### P1-02 消息分配模式（占位）

- **功能描述**：展示 6 种分配模式卡片，阶段一仅「手动接单」可选（当前启用），其余 5 种模式灰化锁定并显示解锁条件
- **对应原型**：`page-agents` 第 2 Tab「分配策略」（v1.2 起收编，原 `page-assignment` 独立页已删除）
- **6 种模式**：手动接单（✅启用）、轮询分配（P2锁定）、最少活跃优先（P2锁定）、加权比例分配（P3锁定）、技能匹配分配（P3锁定）、优先队列（P3锁定）
- **后端模型**：可复用 `SystemConfig`（键 `assignment_mode`）
- **API**：`GET /api/admin/assignment-mode`、`PUT /api/admin/assignment-mode`
- **复杂度**：S（静态展示为主，仅1个配置读写）

#### P1-03 排查模板管理（占位）

- **功能描述**：展示排查模板列表（表格形式：名称、分类、节点数、版本、状态），提供 JSON 导入/导出按钮。阶段一仅展示已有模板数据，导入导出功能灰化标注"阶段三启用"
- **对应原型**：`page-flowchart`
- **后端模型**：`TroubleshootingTemplate`（已有，可直接查询）
- **已有 API**：`GET /api/troubleshooting-templates`（可复用）
- **复杂度**：S（数据展示 + 按钮占位）

#### P1-04 会话监控（占位，Demo预览）

- **功能描述**：展示会话统计卡片（进行中/等待中/今日已结单/异常告警）+ 实时会话表格。阶段一从数据库查询真实数据展示，标注"Demo 预览"
- **对应原型**：`page-monitor`
- **数据来源**：`conversations` 表实时查询
- **API**：需新建 `GET /api/admin/monitor/sessions`
- **复杂度**：S（只读查询展示）

### 4.3 P2 功能（阶段一预留占位）

以下模块仅需在导航菜单中预留入口（灰化 + "开发中"标识），页面内容为空白占位页：

| 模块 | 对应阶段 | 导航分组 |
|------|---------|---------|
| 主题模板 | 阶段二 | P2 高级功能 |
| 数据看板 | 阶段四 | P2 高级功能 |
| 知识库管理 | 阶段四 | P2 高级功能 |

### 4.4 全局功能

#### P0-05 导航布局框架

- 深色科技风侧边栏（220px宽）+ 顶部面包屑 + 内容区
- 导航分组：概览 → P0 核心配置 → P1 运营管理 → P2 高级功能
- 每个导航项显示优先级标签（P0红/P1黄/P2绿）
- 灰化菜单项：不可点击，显示 tooltip "阶段X 开发中"

#### P0-06 RBAC 权限控制（最小实现）

- 认证方式：复用坐席端 Redis token 机制，`Agent` 模型新增 `role` 字段
- 权限校验：`role='admin'` 可访问管理后台，`role='agent'` 返回 403
- 后端中间件：`/api/admin/*` 路由组统一校验 token + role
- 前端路由守卫：无 admin 角色跳转 403 页面

#### P1-05 全局搜索

- 顶部搜索框输入关键词，搜索范围：配置项名称、坐席姓名、快速回复标题
- 搜索结果以下拉菜单展示，点击跳转到对应页面

---

## 5. 页面清单与导航结构

### 5.1 页面树（v1.1 重构 · 5 组 27 项）

> v1.1 调整背景：v1.0 采用的 4 组（概览 / P0 / P1 / P2）按优先级分组，但实际运营中按"用户任务流"分组更友好（运营主管看运营中心、合规审计员看安全审计、运维看系统集成、知识管理员看知识与 AI）。本次重构调整为**5 组按用户场景**的结构。

```
管理后台 (/itadmin/)
├── 🟦 运营中心（7 项 · 实时作战 + 实时监控）
│   ├── 运营总览              /admin/dashboard            P0 ✅ (含会话监控 widget)
│   ├── 会话监控              /admin/monitor              P1 ⚡ (Dashboard 详情页跳转)
│   ├── 坐席管理              /admin/agents               P0 ✅ (含「分配策略」Tab，v1.2 收编原独立页)
│   ├── 角色管理              /admin/roles                P0 ✅ 🆕
│   ├── 权限矩阵              /admin/permissions-matrix   P1 ⚡ 🆕 补漏
│   ├── OTP 管理              /admin/mfa-manage           P1 ✅
│   └── 功能开关              /admin/configs              P0 ✅
├── 🟪 数据与监控（4 项 · 离线分析 + AI 指标）
│   ├── 会话审计              /admin/session-audit        P0 ✅
│   ├── 坐席绩效              /admin/agent-performance    P0 ✅
│   ├── 满意度评价            /admin/evaluation-stats     P1 ✅
│   └── 自动化指标            /admin/automation-metrics   P1 ✅
├── 🟥 安全审计（5 项 🆕 · 合规追溯 + 系统安全）
│   ├── 配置变更历史          /admin/system-logs          P0 ✅ 🆕
│   ├── 运行期日志            /admin/runtime-logs         P1 ✅ 🆕
│   ├── 安全审计日志          /admin/audit-logs           P0 ✅ 🆕
│   ├── 终端安全              /admin/terminal-security    P0 ✅ 🆕 移入
│   └── 快速回复审计日志      /admin/quick-rules/audit    P1 ✅ 🆕 移入（v1.1 调整：从快速回复规则组移至安全审计）
├── 🟩 系统与集成（4 项 · 底层能力配置）
│   ├── 系统集成              /admin/integrations         P0 ⚡
│   ├── 欢迎与引导            /admin/welcome-config       P1 ✅
│   ├── 自动化场景            /admin/automation-scenarios P1 ✅
│   └── 规则版本              /admin/automation-versions  P1 ✅
└── 🟪 知识与 AI（7 项 · 配置规则 + 知识沉淀 + 智能建议）
    ├── 配置规则（3 项）
    │   ├── 快速回复规则（5 个子页：index/greeting/contacts/routing/targets）
    │   │                                            /admin/quick-rules            P1 ✅ 🆕 包含模板 tab 收编
    │   ├── 排查流程图         /admin/flowcharts         P1 ⚡ 🆕 移入
    │   └── 代答排除           /admin/exclusion-rules    P1 ✅ 🆕
    ├── 知识沉淀（3 项）
    │   ├── 知识迭代管理       /admin/knowledge-iteration P1 ✅ 🆕
    │   ├── RAGFlow 文档导入   /admin/ragflow-ingestion  P1 ✅ 🆕
    │   └── 拓扑预览           /admin/topology-preview   P1 ✅ 🆕
    └── 智能建议（1 项）
        └── 知识库建议         /admin/knowledge-suggestions P1 ✅ 🆕 移入
```

> 图例：✅ 1B 实现 | ⚡ 部分实现/占位 | 🚧 仅占位页  
> 🆕 = v1.1 新增/移入/调整归属  
> 折叠区（不计入主导航）：主题模板 / 数据看板 / 知识库管理（3 个 P2 占位，灰化）

### 5.2 导航分组（v1.1 重构）

| 导航分组 | 菜单数 | 包含菜单项 | 用户角色 |
|---------|--------|-----------|---------|
| 🟦 运营中心 | 7 | 运营总览 / 会话监控 / 坐席管理 / 角色管理 / 权限矩阵 / OTP 管理 / 功能开关 | 运营主管 / 坐席组长 |
| 🟪 数据与监控 | 4 | 会话审计 / 坐席绩效 / 满意度评价 / 自动化指标 | 数据分析师 / 主管 |
| 🟥 安全审计 | 5 | 配置变更历史 / 运行期日志 / 安全审计日志 / 终端安全 / 快速回复审计日志 | 合规审计员 / 安全管理员 |
| 🟩 系统与集成 | 4 | 系统集成 / 欢迎与引导 / 自动化场景 / 规则版本 | 系统管理员 |
| 🟪 知识与 AI | 7 | 快速回复规则 / 排查流程图 / 代答排除 / 知识迭代 / RAGFlow 导入 / 拓扑预览 / 知识库建议 | AI 运营 / 知识管理员 |
| **合计** | **26** | + 折叠区占位 3 项；分配模式作为坐席管理第 2 Tab 收编 | — |

### 5.3 对应原型页面映射（v1.1 更新）

| 原型页面 `id` | PRD 模块 | 实现方式 | 所属分组 |
|--------------|---------|---------|---------|
| `page-dashboard` | 运营总览（含会话监控 widget） | Vue 组件实现 | 运营中心 |
| `page-monitor` | 会话监控（详情页） | Vue 组件实现 | 运营中心 |
| `page-agents` | 坐席管理（含「分配策略」Tab，v1.2 收编原 page-assignment） | Vue 组件实现（`el-tabs` 双 Tab） | 运营中心 🆕 v1.2 |
| `page-assignment` | 分配模式（已收编为 `page-agents` 第 2 Tab，v1.2 起不再独立展示） | — | — |
| `page-roles` | 角色管理 | Vue 组件实现 | 运营中心 🆕 |
| `page-permissions-matrix` | 权限矩阵 | Vue 组件实现（RBAC 可视化） | 运营中心 🆕 |
| `page-mfa-manage` | OTP 管理 | Vue 组件实现 | 运营中心 🆕 |
| `page-features` | 功能开关 | Vue 组件实现 | 运营中心 |
| `page-session-audit` | 会话审计 | Vue 组件实现 | 数据与监控 |
| `page-agent-performance` | 坐席绩效 | Vue 组件实现 | 数据与监控 |
| `page-evaluation-stats` | 满意度评价 | Vue 组件实现 | 数据与监控 |
| `page-automation-metrics` | 自动化指标 | Vue 组件实现 | 数据与监控 🆕 |
| `page-system-logs` | 配置变更历史 | Vue 组件实现 | 安全审计 🆕 |
| `page-runtime-logs` | 运行期日志 | Vue 组件实现 | 安全审计 🆕 |
| `page-audit-logs` | 安全审计日志 | Vue 组件实现 | 安全审计 🆕 |
| `page-terminal-security` | 终端安全 | Vue 组件实现 | 安全审计 🆕 移入 |
| `page-quick-rules-audit` | 快速回复审计日志 | Vue 组件实现 | 安全审计 🆕 移入（v1.1 调整：从快速回复规则组移出） |
| `page-integrations` | 系统集成 | Vue 组件实现（部分占位） | 系统与集成 |
| `page-welcome-config` | 欢迎与引导 | Vue 组件实现 | 系统与集成 🆕 |
| `page-automation-scenarios` | 自动化场景 | Vue 组件实现 | 系统与集成 🆕 |
| `page-automation-versions` | 规则版本 | Vue 组件实现 | 系统与集成 🆕 |
| `page-quick-rules` | 快速回复规则（含 5 子页 + 模板 tab 收编） | Vue 组件实现 | 知识与 AI 🆕 |
| `page-flowchart` | 排查流程图 | Vue 组件实现（大部分占位） | 知识与 AI 🆕 移入 |
| `page-exclusion-rules` | 代答排除 | Vue 组件实现 | 知识与 AI 🆕 |
| `page-knowledge-iteration` | 知识迭代管理 | Vue 组件实现 | 知识与 AI 🆕 |
| `page-ragflow-ingestion` | RAGFlow 文档导入 | Vue 组件实现 | 知识与 AI 🆕 |
| `page-topology-preview` | 拓扑预览 | Vue 组件实现 | 知识与 AI 🆕 |
| `page-knowledge-suggestions` | 知识库建议 | Vue 组件实现 | 知识与 AI 🆕 移入 |

---

## 6. 已实现功能映射

### 6.1 可直接复用的后端模型

| 模型 | 表名 | 复用方式 | 备注 |
|------|------|---------|------|
| `SystemConfig` | `system_configs` | 直接读写 | 已有 12 个配置键，功能开关页面直接映射 |
| `Agent` | `agents` | 查询列表 + 扩展字段 | 需要新增 role/skill_tags 列 |
| `QuickReplyTemplate` | `quick_reply_templates` | 查询列表 + 扩展字段 | 需要新增 status/version/submitted_by 列 |
| `TroubleshootingTemplate` | `troubleshooting_templates` | 只读查询 | 排查流程图页面展示 |
| `Conversation` | `conversations` | 只读聚合查询 | 仪表盘统计 + 会话监控 |
| `Employee` | `employees` | 只读查询 | 关联坐席信息 |

### 6.2 可直接复用的后端 API

| 现有 API | 复用场景 | 是否需要修改 |
|---------|---------|------------|
| `GET /api/agents` | 坐席列表查询 | 是，增加 role 和 skill_tags 返回 |
| `GET /api/quick-replies` | 快速回复列表 | 是，增加审核状态筛选 |
| `GET /api/troubleshooting-templates` | 排查模板列表 | 否，直接复用 |
| `GET /api/system/emergency-mode` | 应急模式状态读取 | 否，直接复用 |
| `PUT /api/system/emergency-mode` | 应急模式开关切换 | 否，直接复用 |

### 6.3 需要新建的 API 路由组

所有管理后台 API 统一挂载到 `/api/admin/` 路由组下：

| API | 方法 | 用途 | 优先级 |
|-----|------|------|--------|
| `/api/admin/dashboard/overview` | GET | 仪表盘统计数据 | P0 |
| `/api/admin/configs` | GET | 获取全部配置项（分组） | P0 |
| `/api/admin/configs/{key}` | PUT | 更新单个配置项 | P0 |
| `/api/admin/configs/{key}/history` | GET | 配置变更历史 | P0 |
| `/api/admin/agents` | GET | 坐席列表（管理视图，含角色/标签） | P0 |
| `/api/admin/agents` | POST | 添加坐席 | P0 |
| `/api/admin/agents/{id}` | PUT | 编辑坐席（角色/技能标签/负载上限） | P0 |
| `/api/admin/agents/{id}` | DELETE | 移除坐席 | P0 |
| `/api/admin/integrations` | GET | 集成系统列表+状态 | P0 |
| `/api/admin/integrations/{id}` | PUT | 更新集成配置 | P0 |
| `/api/admin/integrations/{id}/test` | POST | 测试连接 | P1 |
| `/api/admin/quick-replies/pending` | GET | 待审核模板列表 | P1 |
| `/api/admin/quick-replies/{id}/review` | PUT | 审核通过/驳回 | P1 |
| `/api/admin/assignment-mode` | GET/PUT | 分配模式读写 | P1 |
| `/api/admin/monitor/sessions` | GET | 实时会话列表 | P1 |
| `/api/admin/search` | GET | 全局搜索 | P1 |

### 6.4 需要扩展的已有模型

| 模型 | 新增字段 | 类型 | 默认值 | 说明 |
|------|---------|------|--------|------|
| `Agent` | `role` | VARCHAR(20) | `'agent'` | admin=组长, agent=坐席 |
| `Agent` | `skill_tags` | JSON | `[]` | 如 `["电脑","网络"]` |
| `QuickReplyTemplate` | `status` | VARCHAR(20) | `'approved'` | draft/pending_review/approved/rejected |
| `QuickReplyTemplate` | `version` | INTEGER | `1` | 版本号，每次审核通过后 +1 |
| `QuickReplyTemplate` | `submitted_by` | VARCHAR(36) | NULL | 提交人 agent_id（外键关联 agents） |

---

## 7. 数据模型扩展方案

### 7.1 Agent 模型扩展

```python
# 在 Agent 模型中新增：
role: Mapped[str] = mapped_column(
    String(20), nullable=False, default="agent",
    comment="角色：admin=组长, agent=坐席"
)
skill_tags: Mapped[List[str]] = mapped_column(
    JSON, nullable=False, default=list,
    comment="技能标签列表（电脑/软件/外设/网络/安全/资产/其他）"
)
```

已有种子数据：当前坐席（宋献 → 组长角色 + 电脑/网络/软件标签，王丽 → 坐席 + 外设/安全，张伟 → 坐席 + 资产/其他）。

### 7.2 QuickReplyTemplate 模型扩展

```python
# 在 QuickReplyTemplate 模型中新增：
status: Mapped[str] = mapped_column(
    String(20), nullable=False, default="approved",
    comment="状态：draft/pending_review/approved/rejected"
)
version: Mapped[int] = mapped_column(
    Integer, nullable=False, default=1,
    comment="版本号"
)
submitted_by: Mapped[str] = mapped_column(
    String(36), nullable=True, default=None,
    comment="提交人 agent_id"
)
```

已有种子数据默认 `status='approved'`（无需审核）。

### 7.3 新建 IntegrationConfig 模型（可选）

若需要持久化集成系统的配置（API URL、Key 等），建议新建：

```python
class IntegrationConfig(Base):
    __tablename__ = "integration_configs"
    id: str (UUID PK)
    system: str          # dify/ragflow/data_platform/beisen/huorong/liansoft
    name: str            # 显示名称
    api_url: str         # API 地址
    api_key: str         # API Key（加密存储）
    status: str          # connected/partial/disconnected/pending
    updated_at: datetime
```

阶段一可暂不复用此模型，直接硬编码 6 个系统的状态展示，Dify 和 RAGFlow 的配置暂时存 `system_configs`。

---

## 8. API 设计概要

### 8.1 路由注册

```python
# 新建 backend/app/api/admin.py
# 在 backend/app/api/router.py 中注册：
from app.api.admin import router as admin_router
api_router.include_router(admin_router, prefix="/admin", tags=["管理后台"])
```

### 8.2 权限中间件

```python
# 所有 /api/admin/* 路由需校验：
# 1. token 有效性（复用坐席端 Redis token）
# 2. Agent.role == 'admin'
# 不满足条件返回统一错误响应（code=1003, message="无管理权限"）
```

### 8.3 响应格式

沿用项目统一的 `success_response` / `error_response` 格式：

```json
{"code": 0, "message": "success", "data": {...}}
{"code": 1003, "message": "无管理权限"}
```

### 8.4 配置变更历史

`PUT /api/admin/configs/{key}` 时：
1. 读取当前值存入日志（`config_change_logs` 表或 JSON 字段）
2. 写入新值
3. 返回变更前后对比

日志结构：`{config_key, old_value, new_value, changed_by, changed_at}`

---

## 9. 占位模块规格

### 9.1 占位页面交互规范

所有未来阶段的占位页面遵循统一的展示方式：

**页面内容**：
```
┌────────────────────────────────────────┐
│                                        │
│         🚧  开发中                      │
│                                        │
│     该功能将在阶段 X 上线                │
│                                        │
│     预计功能：{简短描述}                  │
│                                        │
│              [返回首页]                  │
│                                        │
└────────────────────────────────────────┘
```

**导航菜单**：
- 灰化样式：`opacity: 0.4; pointer-events: none;`
- 不响应点击
- Tooltip 悬停提示："阶段X 开发中，敬请期待"

### 9.2 各占位页面规格

| 页面 | 占位类型 | 占位内容 |
|------|---------|---------|
| 主题模板 | 🚧 空白占位 | 居中显示"阶段二上线"，描述：支持全局/坐席端/H5端三层主题配置 |
| 数据看板 | 🚧 空白占位 | 居中显示"阶段四上线"，描述：坐席绩效、满意度趋势、热点问题排行 |
| 知识库管理 | 🚧 空白占位 | 居中显示"阶段四上线"，描述：标注→知识条目→RAGFlow同步迭代闭环 |
| 系统集成（部分） | ⚡ 功能占位 | 展示系统卡片但"配置""测试"按钮灰化，tooltip 说明"阶段二启用" |
| 排查流程图 | ⚡ 功能占位 | 展示已有模板数据，导入导出按钮灰化标注"阶段三启用" |

---

## 10. 技术约束与约定

### 10.1 前端技术栈

| 项目 | 值 |
|------|------|
| 框架 | Vue 3 + Composition API |
| 语言 | TypeScript |
| UI 库 | Element Plus |
| 状态管理 | Pinia |
| 构建工具 | Vite |
| 样式方案 | Tailwind CSS（与坐席端一致） |
| UI 风格 | 深色科技风（CSS 变量与原型一致） |
| 部署路径 | `/itadmin/` |

### 10.2 CSS 变量（与原型对齐）

```css
--bg-primary: #0f172a;      /* 主背景 */
--bg-secondary: #1e293b;    /* 侧边栏/卡片 */
--bg-tertiary: #334155;     /* 表格表头 */
--accent: #3b82f6;          /* 主题色 */
--success: #10b981;         /* 成功/在线 */
--warning: #f59e0b;         /* 警告 */
--danger: #ef4444;          /* 危险/错误 */
--text-primary: #f1f5f9;    /* 主文字 */
--text-secondary: #94a3b8;  /* 辅助文字 */
--text-muted: #64748b;      /* 弱化文字 */
```

### 10.3 后端技术栈

| 项目 | 值 |
|------|------|
| 框架 | FastAPI |
| ORM | SQLAlchemy 2.0 (async) |
| 数据库 | PostgreSQL（生产）/ SQLite（开发） |
| 缓存 | Redis（token + 配置热更新） |
| 认证 | Redis token + Agent.role 权限校验 |
| API 前缀 | `/api/admin/` |

### 10.4 部署

```nginx
# nginx 配置示例（新增 /itadmin/ 路由）
location /itadmin/ {
    alias /path/to/frontend-admin/dist/;
    try_files $uri $uri/ /itadmin/index.html;
}

location /api/admin/ {
    proxy_pass http://backend:8000/api/admin/;
}
```

### 10.5 其他约定

- 项目名称：`frontend-admin`，目录与 `frontend-agent/`、`frontend-h5/` 并列
- 后端新建文件：`backend/app/api/admin.py`、`backend/app/services/admin_service.py`（可选）
- 数据库迁移：新增列使用 Alembic 迁移脚本
- 中文界面，所有文案使用中文
- 配置项命名遵循现有 `snake_case` 规范

---

## 11. 待确认问题

| # | 问题 | 影响范围 | 建议方案 | 确认人 |
|---|------|---------|---------|--------|
| Q1 | 坐席组长是否只有 1 人（宋献）？其他坐席是否需要管理后台访问权限？ | RBAC 设计 | 阶段一仅宋献（role=admin），后续需新增组长时可扩展 | 宋献 |
| Q2 | IntegrationConfig 模型是新建独立表还是复用 SystemConfig 存 JSON？ | 数据模型 | 建议阶段一先用 SystemConfig，等集成系统配置复杂度上升后再建独立表 | 开发 |
| Q3 | 快速回复的版本历史是存一张新表（quick_reply_versions）还是在主表用 JSON 存历史版本？ | 数据模型 | 建议阶段一先用主表 version 字段递增 + JSON 字段存 diff，阶段二按需建版本表 | 开发 |
| Q4 | 配置变更历史的存储粒度：每键独立日志表 vs 通用 JSON 日志？ | 数据模型 | 建议阶段一在 config_change_logs 表中存 {key, old, new, who, when}，简单够用 | 开发 |
| Q5 | 仪表盘"平均响应时间"和"AI命中率"的计算口径需要确认（从坐席接单到首条回复？还是从员工发消息到坐席回复？） | 运营总览 | 建议阶段一先展示"今日会话数"和"在线坐席数"两个有把握的指标，其余用占位符 | 宋献 |
| Q6 | 快速回复"仅提交人可用"（待审核期间）的权限粒度：坐席端 API 是否需要改？ | 快速回复 | 是，坐席端 `GET /api/quick-replies` 返回需增加 status 筛选（全员可见的 approved + 自己的 pending_review） | 开发 |
| Q7 | 应急模式开启时，H5用户端展示引导文案的内容是否需要管理后台可配？ | 功能开关 | 建议阶段一固定文案（硬编码在 system.py 中），阶段二增加可配置 | 宋献 |

---

> **文档结束** — 本 PRD 覆盖管理后台阶段一 1B 的全部需求，与主 PRD §18-20 和原型 `admin-dashboard-v1.html` 对齐。后续阶段的功能将在迭代中增量补充。

---

## 12. 变更日志

| 版本 | 日期 | 变更内容 | 变更人 | 变更原因 | 影响范围 |
|------|------|---------|--------|---------|---------|
| v1.0 | 2026-06-16 | 初版 PRD（4 组导航：概览/P0 核心/P1 运营/P2 高级） | 许清楚 | 阶段一 1B 立项 | — |
| v1.1 | 2026-07-28 | **导航重构为 5 组按用户场景**（运营中心/数据与监控/安全审计/系统与集成/知识与 AI）；新增 12 项菜单（含 v1.0 未列出的角色管理/权限矩阵/OTP 管理/自动化指标/配置变更历史/运行期日志/安全审计日志/终端安全/快速回复审计/欢迎与引导/自动化场景/规则版本/知识迭代/RAGFlow 导入/拓扑预览/知识库建议/代答排除等）；终端安全从系统与集成移入安全审计组；快速回复审计从快速回复规则组移入安全审计组；快速回复模板作为快速回复规则页内"模板"tab 收编；会话监控 widget 嵌入运营总览 | 宋献 | v1.0 按优先级分组的导航不符合运营实际使用场景；安全审计类功能分散；快速回复模板与规则功能重复；用户进入运营总览看不到实时会话 | §5 全部；§4.1/4.2/4.3 部分功能项；§9.2 占位规格微调；新增 27 项页面映射到原型 |
| v1.2 | 2026-07-28 | **分配模式 Tab 收编到坐席管理**：原独立页 `page-assignment` 不再独立展示，整体内嵌为 `/admin/agents` 的第 2 个 Tab"分配策略"；路由 `/admin/assignment-mode` 移除；菜单导航「知识与 AI」8 项 → 7 项（合计 26 项）；坐席管理原型增加 `el-tabs` 双 Tab 切换 | 宋献 | 阶段一分配模式 6 个里 5 个灰化，占独立菜单过重；解锁条件强依赖坐席人数，Tab 合并后上下文最连贯；未来膨胀仍可拆回独立页 | §5.1/5.2/5.3 树状图与分组表；§9.2 占位表；§12 变更日志 |

### v1.2 关键变更说明

**1. 分配模式 Tab 收编到坐席管理**
- 原 `/admin/assignment-mode` 独立菜单/独立页 → 收编为 `/admin/agents` 的第 2 个 Tab「分配策略」
- 路由表删除 `/admin/assignment-mode` 项；菜单导航「知识与 AI」8 项 → 7 项，总菜单数 27 → 26
- 坐席管理页实现方式：`<el-tabs v-model="activeTab">`，Tab1 = 坐席列表（原内容），Tab2 = 分配策略（迁移 `AssignmentMode.vue` 的 6 张模式卡片）
- 后端零改动：分配模式的读写仍走 `system_configs.assignment_mode` + `GET/PUT /api/admin/assignment-mode`
- `views/AssignmentMode.vue` 保留文件但停用导入（防止后续回滚时再拆出）

**2. 决策依据**
- 阶段一分配模式 6 个里 5 个灰化占位，独立菜单过重
- 解锁条件强依赖坐席人数（轮询 ≥3、加权 ≥5），Tab 内可见当前在岗数，无需跨页比对
- 若阶段二/三分配模式膨胀（权重配置、技能匹配规则），可逆撤销为独立页

### v1.1 关键变更说明

**1. 5 组按用户场景分组**（替代 v1.0 的 4 组按优先级分组）
- 运营中心：日常运营主入口（运营主管/组长）
- 数据与监控：离线数据分析（数据分析师）
- 安全审计：合规追溯（合规审计员/安全管理员）🆕
- 系统与集成：底层能力配置（系统管理员）
- 知识与 AI：智能引擎 + 知识沉淀（AI 运营/知识管理员）

**2. 快速回复模板收编为 Tab**（节省 1 个菜单项）
- 原 `/admin/quick-replies` 独立菜单页面 → 整合为 `/admin/quick-rules` 内的"模板"tab
- 原 5 个子路由（greeting/contacts/routing/targets/audit）+ 新增 template tab = 6 个 tab
- 复用 quickReplyStore 与现有 API，无需新建后端

**3. 会话监控 widget 嵌入运营总览**（双视图模式）
- Dashboard 顶部新增"实时会话 Top 5" widget
- 点"查看更多"跳 `/admin/monitor` 详情页
- 优势：用户进入 Dashboard 即可见实时状态，无需跳转

**4. 快速回复审计日志移出知识与 AI 组**（v1.1 关键调整）
- 原规划：作为"快速回复规则"页的 6 个 tab 之一（与 greeting/contacts/routing/targets/template 并列）
- 调整后：独立菜单项，归入"安全审计"组（与配置变更历史/运行期日志/安全审计日志/终端安全 并列）
- 理由：审计类功能在性质上属于安全合规范畴，不应混杂在业务规则配置组

**5. 终端安全从系统与集成移入安全审计**
- 原位置：与系统集成、自动化场景、规则版本同组（系统集成 + 终端安全 = 4 项）
- 调整后：归入安全审计组（合规追溯 + 系统安全 = 5 项）
- 理由：终端安全本质是合规管控（联软/火绒管控），与底层引擎集成（系统集成/自动化场景）性质不同

**6. 新增 12 项菜单覆盖完整功能域**
- 运营中心：角色管理、权限矩阵、OTP 管理（v1.0 漏列）
- 数据与监控：自动化指标（v1.0 漏列）
- 安全审计：配置变更历史、运行期日志、安全审计日志（v1.0 漏列）
- 系统与集成：欢迎与引导、自动化场景、规则版本（v1.0 漏列）
- 知识与 AI：知识迭代管理、RAGFlow 文档导入、拓扑预览、知识库建议、代答排除、排查流程图（v1.0 部分漏列）