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