Files

T

Simon 63262292d7 chore: initial baseline with P0-safety .gitignore

2026-06-14 16:51:56 +08:00

26 KiB

Raw Permalink Blame History

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

文档版本: v1.0
创建日期: 2026-06-16
产品经理: 许清楚 (Xu) · 宋献
状态: 阶段一 1B — 待开发
关联文档: docs/PRD.md (主 PRD §18-20)、docs/prototypes/admin-dashboard-v1.html（原型参考）

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 交付范围：

功能开关/参数管理（P0）— 可视化编辑 system_configs 表中的配置项
坐席人员管理（P0）— 坐席列表 + 角色/技能标签编辑 + 状态查看
快速回复管理（P1）— 分类列表 + 审核发布流程（坐席提交→组长审核→全员可见）
外部系统集成配置（P0 占位）— 6个外部系统卡片展示 + 配置入口（仅 Dify 可用）
消息分配模式（P1 占位）— 手动接单为当前模式，其他模式灰化锁定
排查模板管理（P1 占位）— 模板列表查看 + JSON 导入导出入口（阶段三启用）
运营总览仪表盘（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 模型扩展

# 在 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} 时：

读取当前值存入日志（config_change_logs 表或 JSON 字段）
写入新值
返回变更前后对比

日志结构：{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 对齐。后续阶段的功能将在迭代中增量补充。

26 KiB Raw Permalink Blame History Unescape Escape