chore: initial baseline with P0-safety .gitignore

2026-06-14 16:49:18 +08:00
commit 63262292d7
510 changed files with 146008 additions and 0 deletions
@@ -0,0 +1,552 @@
+# 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` 对齐。后续阶段的功能将在迭代中增量补充。