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

> **文档版本**: v1.0  
> **创建日期**: 2026-06-16  
> **产品经理**: 许清楚 (Xu) · 宋献  
> **状态**: 阶段一 1B — 待开发  
> **关联文档**: `docs/PRD.md` (主 PRD §18-20)、`docs/prototypes/admin-dashboard-v1.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 占位）— 手动接单为当前模式，其他模式灰化锁定
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-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 页面树

```
管理后台 (/itadmin/)
├── 概览
│   └── 运营总览                /admin/dashboard          P0 ✅
├── P0 核心配置
│   ├── 功能开关/参数            /admin/configs            P0 ✅
│   ├── 坐席人员管理            /admin/agents             P0 ✅
│   └── 外部系统集成            /admin/integrations       P0 ⚡（占位）
├── P1 运营管理
│   ├── 消息分配模式            /admin/assignment         P1 ⚡（占位）
│   ├── 快速回复管理            /admin/quick-replies      P1 ✅
│   ├── 会话监控                /admin/monitor            P1 ⚡（Demo预览）
│   └── 排查流程图              /admin/flowcharts         P1 ⚡（占位）
└── P2 高级功能
    ├── 主题模板                /admin/themes             P2 🚧（占位）
    ├── 数据看板                /admin/analytics          P2 🚧（占位）
    └── 知识库管理              /admin/knowledge          P2 🚧（占位）
```

> 图例：✅ 1B实现 | ⚡ 部分实现/占位 | 🚧 仅占位页

### 5.2 导航分组

| 导航分组 | 菜单项 | 排序 |
|---------|--------|------|
| 概览 | 运营总览 | 1 |
| P0 核心配置 | 功能开关、坐席管理、系统集成 | 2-4 |
| P1 运营管理 | 分配模式、快速回复、会话监控 | 5-7 |
| P2 高级功能 | 排查流程图、主题模板、数据看板、知识库 | 8-11 |

### 5.3 对应原型页面映射

| 原型页面 `id` | PRD 模块 | 实现方式 |
|--------------|---------|---------|
| `page-dashboard` | 运营总览 | Vue 组件实现 |
| `page-features` | 功能开关 | Vue 组件实现 |
| `page-agents` | 坐席管理 | Vue 组件实现 |
| `page-integrations` | 系统集成 | Vue 组件实现（部分占位） |
| `page-assignment` | 分配模式 | Vue 组件实现（大部分占位） |
| `page-quickreply` | 快速回复 | Vue 组件实现 |
| `page-monitor` | 会话监控 | Vue 组件实现（Demo预览） |
| `page-flowchart` | 排查流程图 | Vue 组件实现（大部分占位） |

---

## 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` 对齐。后续阶段的功能将在迭代中增量补充。