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. 项目信息
2. 产品定义与目标
3. 用户故事
4. 功能需求池
5. 页面清单与导航结构
6. 已实现功能映射
7. 数据模型扩展方案
8. API 设计概要
9. 占位模块规格
10. 技术约束与约定
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 模型扩展

# 在 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 模型扩展

# 在 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 等），建议新建：

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 路由注册

# 新建 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 权限中间件

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

8.3 响应格式

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

{"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 变量（与原型对齐）

--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 配置示例（新增 /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 部分漏列）