# 运营管理端架构设计

> **文档版本：** v1.0  
> **创建日期：** 2025-11-06  
> **最后更新：** 2025-11-06  
> **文档状态：** 架构设计中  
> **作者：** 技术架构师

---

## 📋 文档说明

本文档详细设计运营管理端（Admin/Operations Platform）的完整架构，包括：
1. 运营管理端的层次定位
2. 完整的功能清单
3. 对系统总体设计的影响
4. 技术实现方案

---

## 🎯 核心问题解答

### 1. 运营管理端是应用层吗？

**答案：运营管理端是"横跨多层"的特殊系统**

```
运营管理端的定位：

┌─────────────────────────────────────────────────────────┐
│              运营管理端（Admin Platform）                  │
│         独立的前端应用 + 独立的后端API                      │
│                                                           │
│  管理范围：                                                │
│  ├─ 平台基础层配置（用户、权限、租户）                      │
│  ├─ 通用能力层配置（LLM模型、Feature Flag）                │
│  ├─ 业务模块配置（智能体提示词、模块开关）                  │
│  └─ 运营数据分析（统计、监控、成本分析）                    │
└─────────────────────────────────────────────────────────┘
                          ↓ 管理
┌─────────────────────────────────────────────────────────┐
│                   业务模块层                              │
│  AIA | ASL | PKB | DC | SSA | ST | RVW                  │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   通用能力层                              │
│  LLM网关 | 文档处理 | RAG | ETL | NLP                    │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                   平台基础层                              │
│  用户权限 | 存储 | 通知 | 监控 | 配置                     │
└─────────────────────────────────────────────────────────┘
```

**准确定位：**
- ✅ 运营管理端是一个**独立的应用系统**
- ✅ 它管理和配置所有三层（平台层、能力层、业务层）
- ✅ 它有自己的前端应用、后端API、权限体系
- ✅ 它是"平台的管理者"，而不是"应用层"

**类比：**
- 业务前端（用户端）：给医生、研究者使用
- 运营管理端：给公司内部运营人员、管理员使用

---

### 2. 运营管理端的完整功能清单

基于7个业务模块，我为您补充了完整的功能清单：

---

## 📊 功能模块设计

### 模块1：用户管理 ✅ 已提到

**核心功能：**
1. **用户列表与搜索**
   - 列表展示（邮箱、姓名、注册时间、状态、版本）
   - 搜索和筛选（按邮箱、姓名、状态、版本、注册时间）
   - 批量操作（批量禁用、批量删除）

2. **用户详情与编辑**
   - 基本信息（邮箱、姓名、头像、手机号）
   - 账户状态（激活、禁用、锁定）
   - 用户版本（基础版、高级版、旗舰版）
   - 配额管理（知识库配额、文档配额、月度AI配额）
   - 试用期管理（是否试用、试用到期时间）

3. **用户权限管理**
   - 模块权限（可访问哪些模块：AIA、ASL、PKB等）
   - 功能权限（批处理、全文模式、模型切换等）
   - 角色分配（普通用户、高级用户、VIP用户、管理员）

4. **用户操作日志**
   - 登录日志（登录时间、IP地址、设备）
   - 操作日志（上传文档、创建对话、批处理任务等）
   - API调用日志（LLM调用次数、Token使用量）

5. **用户数据统计**
   - 知识库数量、文档数量
   - 对话数量、消息数量
   - AI调用次数、Token使用量
   - 存储空间使用量

---

### 模块2：智能体提示词管理 ✅ 已提到

**核心功能：**
1. **智能体列表**
   - 10个智能体（选题评价、PICO梳理、样本量计算等）
   - 每个智能体的基本信息（名称、描述、图标）
   - 启用/禁用状态

2. **提示词编辑**
   - System Prompt（系统提示词）
   - User Prompt Template（用户提示词模板）
   - 支持变量（如`{研究背景}`、`{研究目标}`）
   - 实时预览

3. **提示词版本管理**
   - 版本历史记录
   - 版本对比
   - 版本回滚
   - 版本发布（灰度发布、全量发布）

4. **测试与验证**
   - 提示词测试工具
   - 输入测试数据，查看AI输出
   - A/B测试（对比不同提示词效果）

---

### 模块3：版本功能设置（Feature Flag） ✅ 已提到

**核心功能：**
1. **版本定义**
   - 基础版（Basic）
   - 高级版（Advanced）
   - 旗舰版（Flagship）
   - 企业版（Enterprise）

2. **模块权限配置**
   - 7个业务模块的访问权限矩阵
   ```
   版本 | AIA | ASL | PKB | DC | SSA | ST | RVW
   -----|-----|-----|-----|----|----|----|----|
   基础 |  ✓  |  ✗  |  ✓  | ✗  | ✗  | ✗  | ✗  |
   高级 |  ✓  |  ✓  |  ✓  | ✗  | ✗  | ✓  | ✗  |
   旗舰 |  ✓  |  ✓  |  ✓  | ✓  | ✓  | ✓  | ✓  |
   ```

3. **功能权限配置**
   - AI模型选择权限（DeepSeek、Qwen3、Claude等）
   - 批处理功能
   - 全文阅读模式
   - 知识库配额（3个、10个、无限）
   - 文档配额（100个、1000个、无限）
   - 月度AI配额（100次、500次、2000次、无限）

4. **动态配置**
   - 实时生效（无需重启）
   - 配置预览（修改前预览效果）
   - 配置回滚

---

### 模块4：用户权限和版本设置 ✅ 已提到

**核心功能：**
1. **批量版本调整**
   - 选择多个用户批量升级/降级版本
   - 批量延长试用期
   - 批量调整配额

2. **自动化规则**
   - 新用户默认版本（基础版）
   - 新用户默认试用期（14天）
   - 试用期到期自动降级
   - 配额超出自动限流

3. **特殊权限**
   - 内部员工账号（所有权限）
   - 测试账号（无限配额）
   - 合作伙伴账号（特殊权限）

---

### 模块5：租户管理 🆕 **新增**

**适用场景：** 私有化部署、企业版

**核心功能：**
1. **租户列表**
   - 租户名称、Logo、域名
   - 租户状态（试用、正式、过期、禁用）
   - 租户类型（标准版、企业版、定制版）

2. **租户配置**
   - 品牌定制（Logo、主题色、名称）
   - 独立域名（如`hospital-a.yizhengxun.com`）
   - 数据隔离（独立Schema）
   - 模块开关（可选模块）

3. **租户统计**
   - 用户数量、活跃用户
   - 存储使用量
   - API调用量
   - 成本分析

---

### 模块6：LLM模型管理 🆕 **新增（关键）**

**核心功能：**
1. **模型配置**
   - 支持的模型列表（DeepSeek-V3、Qwen3、Qwen-Long、Claude等）
   - 每个模型的API Key
   - 模型基础URL
   - 模型参数（Temperature、Max Tokens等）

2. **模型与版本绑定**
   ```
   基础版：只能用DeepSeek-V3
   高级版：可用DeepSeek-V3、Qwen3
   旗舰版：可用DeepSeek-V3、Qwen3、Qwen-Long、Claude
   ```

3. **模型成本配置**
   - 每个模型的成本（¥/百万tokens）
   - DeepSeek-V3：¥1/百万tokens
   - Qwen3：¥5/百万tokens
   - Claude 3：¥50/百万tokens（估算）

4. **模型切换策略**
   - 默认模型（如DeepSeek-V3）
   - 降级策略（模型不可用时自动降级）
   - 限流策略（超出配额时禁用高成本模型）

---

### 模块7：系统配置管理 🆕 **新增**

**核心功能：**
1. **全局配置**
   - 系统名称、Logo、Favicon
   - 默认语言（中文、英文）
   - 时区设置
   - 文件上传限制（单文件大小、总大小）

2. **安全配置**
   - JWT Token过期时间
   - 密码强度要求
   - 登录失败锁定策略
   - CORS配置

3. **邮件配置**
   - SMTP服务器
   - 邮件模板（注册、密码重置、通知等）

4. **存储配置**
   - 对象存储类型（本地、MinIO、阿里云OSS、S3）
   - 存储配额限制

---

### 模块8：监控与日志 🆕 **新增（关键）**

**核心功能：**
1. **系统监控**
   - 实时在线用户数
   - 实时API调用量（TPS/QPS）
   - 系统资源使用（CPU、内存、磁盘）
   - 数据库连接数

2. **错误监控**
   - 错误日志列表（时间、用户、错误类型、错误信息）
   - 错误统计（按类型、按模块、按时间）
   - 错误告警（邮件、短信）

3. **性能监控**
   - API响应时间统计
   - 慢查询日志
   - LLM调用延迟

4. **审计日志**
   - 管理员操作日志（登录、修改配置、修改用户等）
   - 敏感操作记录（删除用户、修改权限、修改提示词等）

---

### 模块9：数据统计与报表 🆕 **新增（关键）**

**核心功能：**
1. **用户统计**
   - 注册用户趋势（日/周/月）
   - 活跃用户趋势（DAU/WAU/MAU）
   - 用户留存率
   - 用户版本分布

2. **业务统计**
   - 各模块使用情况（AIA、ASL、PKB等）
   - 智能体使用排行
   - 知识库数量趋势
   - 文档上传量趋势

3. **AI调用统计**
   - LLM调用次数趋势
   - Token使用量趋势
   - 各模型使用占比
   - 成本分析（按模型、按模块、按用户）

4. **存储统计**
   - 总存储使用量
   - 各模块存储占比
   - 用户存储排行

5. **导出报表**
   - Excel导出
   - PDF导出
   - 定期自动生成报表（周报、月报）

---

### 模块10：成本分析与计费 🆕 **新增（商业关键）**

**核心功能：**
1. **成本统计**
   - LLM API总成本（按日/周/月）
   - 各模块成本占比
   - 各用户成本排行
   - 各模型成本占比

2. **计费管理**
   - 用户账单生成
   - 欠费用户列表
   - 自动扣费
   - 发票管理

3. **成本预警**
   - 成本超出预算告警
   - 单用户成本异常告警
   - 免费用户滥用检测

4. **利润分析**
   - 收入 vs 成本
   - ROI分析
   - 各版本利润率

---

### 模块11：公告与通知管理 🆕 **新增**

**核心功能：**
1. **系统公告**
   - 创建公告（标题、内容、优先级）
   - 公告展示位置（首页横幅、弹窗、消息中心）
   - 公告定时发布
   - 公告过期时间

2. **站内消息**
   - 给所有用户发消息
   - 给特定版本用户发消息
   - 给特定用户发消息
   - 消息模板

3. **邮件群发**
   - 邮件内容编辑（富文本）
   - 邮件预览
   - 定时发送
   - 发送记录

---

### 模块12：帮助文档管理 🆕 **新增**

**核心功能：**
1. **文档库**
   - 文档分类（快速入门、功能介绍、常见问题等）
   - 文档列表（标题、状态、更新时间）
   - 文档编辑（Markdown富文本）
   - 文档预览

2. **视频教程**
   - 视频上传
   - 视频分类
   - 视频播放统计

3. **常见问题（FAQ）**
   - 问题分类
   - 问题编辑
   - 搜索优化

---

### 模块13：反馈与工单管理 🆕 **新增**

**核心功能：**
1. **用户反馈**
   - 反馈列表（用户、内容、类型、状态）
   - 反馈分类（功能建议、Bug报告、咨询）
   - 反馈回复
   - 反馈状态（待处理、处理中、已完成、已忽略）

2. **工单系统**
   - 工单创建
   - 工单分配（分配给客服、技术团队）
   - 工单跟进
   - 工单关闭

3. **满意度调查**
   - 问题解决后发送满意度调查
   - 满意度统计

---

### 模块14：系统健康检查 🆕 **新增**

**核心功能：**
1. **健康检查**
   - 数据库连接检查
   - Redis连接检查
   - Dify API连接检查
   - Python微服务连接检查
   - LLM API连接检查

2. **自动化测试**
   - API可用性测试
   - 端到端测试（注册、登录、上传文档、AI对话）

3. **告警通知**
   - 服务异常告警
   - 邮件/短信通知管理员

---

### 模块15：数据库备份与恢复 🆕 **新增**

**核心功能：**
1. **备份管理**
   - 手动备份
   - 定时自动备份（每日、每周）
   - 备份列表（时间、大小、状态）
   - 备份下载

2. **恢复管理**
   - 选择备份恢复
   - 恢复预览（确认恢复内容）
   - 恢复进度

---

## 📊 功能优先级分类

### P0（必须，阶段一）

| 模块 | 功能 | 原因 |
|------|------|------|
| **用户管理** | 用户列表、编辑、禁用 | 基础功能 |
| **版本功能设置** | Feature Flag配置 | 商业模式基础 |
| **LLM模型管理** | 模型配置、成本配置 | 成本控制 |
| **系统配置** | 全局配置、安全配置 | 系统运行基础 |

### P1（重要，阶段一或阶段二）

| 模块 | 功能 | 原因 |
|------|------|------|
| **智能体提示词管理** | 提示词编辑、版本管理 | 产品优化 |
| **监控与日志** | 错误监控、审计日志 | 稳定性 |
| **数据统计与报表** | 用户统计、AI调用统计 | 运营决策 |
| **成本分析与计费** | 成本统计、计费管理 | 商业运营 |

### P2（有用，阶段二或阶段三）

| 模块 | 功能 | 原因 |
|------|------|------|
| **租户管理** | 租户配置、数据隔离 | 私有化部署需要 |
| **公告与通知** | 系统公告、站内消息 | 用户运营 |
| **帮助文档** | 文档管理、视频教程 | 用户支持 |
| **反馈与工单** | 用户反馈、工单系统 | 客户服务 |
| **系统健康检查** | 健康检查、自动化测试 | 运维自动化 |
| **数据库备份** | 备份管理、恢复管理 | 数据安全 |

---

## 🏗️ 对系统总体设计的影响

### 影响1：独立的前端应用

**当前架构：**
```
frontend/              # 用户端前端（React）
  ├── src/
  │   ├── pages/
  │   │   ├── login/
  │   │   ├── dashboard/
  │   │   └── ...
  └── ...
```

**新架构（需要增加运营管理端）：**
```
frontend/              # 用户端前端（React）
  └── ...

admin-frontend/        # 运营管理端前端（React）⭐ 新增
  ├── src/
  │   ├── pages/
  │   │   ├── login/             # 管理员登录
  │   │   ├── dashboard/         # 运营仪表盘
  │   │   ├── users/             # 用户管理
  │   │   ├── agents/            # 智能体管理
  │   │   ├── feature-flags/     # Feature Flag管理
  │   │   ├── llm-models/        # LLM模型管理
  │   │   ├── monitoring/        # 监控与日志
  │   │   ├── statistics/        # 数据统计
  │   │   ├── cost-analysis/     # 成本分析
  │   │   └── ...
  │   └── ...
  └── ...
```

**部署方式：**
- 用户端：`https://app.yizhengxun.com`
- 运营管理端：`https://admin.yizhengxun.com`

---

### 影响2：独立的后端API

**当前后端API：**
```
/api/auth/*          # 用户认证
/api/users/*         # 用户相关
/api/projects/*      # 项目管理
/api/conversations/* # AI对话
/api/kb/*            # 知识库
...
```

**新增管理端API：**
```
/api/admin/auth/*              # 管理员认证 ⭐
/api/admin/users/*             # 用户管理 ⭐
/api/admin/agents/*            # 智能体管理 ⭐
/api/admin/feature-flags/*     # Feature Flag管理 ⭐
/api/admin/llm-models/*        # LLM模型管理 ⭐
/api/admin/tenants/*           # 租户管理 ⭐
/api/admin/monitoring/*        # 监控与日志 ⭐
/api/admin/statistics/*        # 数据统计 ⭐
/api/admin/cost-analysis/*     # 成本分析 ⭐
/api/admin/announcements/*     # 公告管理 ⭐
/api/admin/feedback/*          # 反馈管理 ⭐
...
```

---

### 影响3：权限体系扩展

**当前权限：**
```
用户角色：
- user（普通用户）
- admin（管理员，但功能有限）
```

**新权限体系：**
```
用户角色：
- user（普通用户）
- vip（VIP用户，高级功能）

管理员角色：⭐ 新增
- super_admin（超级管理员，所有权限）
- admin（管理员，部分权限）
- operator（运营人员，用户管理、数据统计）
- customer_service（客服，反馈管理、工单管理）
- auditor（审计员，只读权限，查看日志和报表）

管理员权限：⭐ 新增
- user_management        # 用户管理
- agent_management       # 智能体管理
- feature_flag_management # Feature Flag管理
- llm_model_management   # LLM模型管理
- tenant_management      # 租户管理
- monitoring_access      # 监控与日志访问
- statistics_access      # 数据统计访问
- cost_analysis_access   # 成本分析访问
- system_config_management # 系统配置管理
- announcement_management # 公告管理
- feedback_management    # 反馈管理
```

---

### 影响4：数据库Schema扩展

**当前Schema（逻辑隔离）：**
```sql
-- 平台层
platform_schema.users
platform_schema.admin_logs

-- 业务模块
aia_schema.projects
pkb_schema.knowledge_bases
...
```

**新增管理端Schema：**
```sql
-- 管理端Schema ⭐ 新增
CREATE SCHEMA admin_schema;

-- 管理员相关
admin_schema.admin_users          # 管理员账号
admin_schema.admin_roles          # 管理员角色
admin_schema.admin_permissions    # 管理员权限

-- Feature Flag
admin_schema.feature_flags        # Feature Flag配置
admin_schema.feature_flag_history # Feature Flag变更历史

-- 智能体配置
admin_schema.agent_configs        # 智能体配置
admin_schema.agent_prompt_history # 提示词版本历史

-- LLM模型配置
admin_schema.llm_models           # LLM模型配置
admin_schema.llm_cost_config      # 模型成本配置

-- 租户管理
admin_schema.tenants              # 租户表
admin_schema.tenant_configs       # 租户配置

-- 公告与通知
admin_schema.announcements        # 系统公告
admin_schema.notifications        # 站内通知

-- 反馈与工单
admin_schema.feedback             # 用户反馈
admin_schema.tickets              # 工单

-- 系统配置
admin_schema.system_configs       # 系统配置

-- 审计日志
admin_schema.audit_logs           # 审计日志
admin_schema.operation_logs       # 操作日志
```

---

### 影响5：新增通用能力

**LLM Gateway需要增强：**
```typescript
// 原有功能
interface LLMGateway {
  chat(...): Promise<ChatResponse>;
}

// 新增功能（支持运营管理端）⭐
interface LLMGateway {
  chat(...): Promise<ChatResponse>;
  
  // 管理端功能
  getUsageStats(startDate, endDate): Promise<UsageStats>;      // 使用量统计
  getCostStats(startDate, endDate): Promise<CostStats>;        // 成本统计
  getUserUsage(userId): Promise<UserUsage>;                    // 单用户使用量
  getModelConfig(): Promise<ModelConfig[]>;                    // 模型配置
  updateModelConfig(config): Promise<void>;                    // 更新模型配置
  checkQuota(userId): Promise<QuotaInfo>;                      // 配额检查
  resetQuota(userId): Promise<void>;                           // 重置配额
}
```

---

### 影响6：监控与日志增强

**新增监控能力：**
```typescript
// 监控服务 ⭐ 新增
interface MonitoringService {
  // 实时监控
  getSystemStatus(): Promise<SystemStatus>;           // 系统状态
  getOnlineUsers(): Promise<number>;                  // 在线用户数
  getApiMetrics(): Promise<ApiMetrics>;               // API指标（TPS/QPS）
  
  // 错误监控
  getErrorLogs(filter): Promise<ErrorLog[]>;          // 错误日志
  getErrorStats(): Promise<ErrorStats>;               // 错误统计
  
  // 性能监控
  getSlowQueries(): Promise<SlowQuery[]>;             // 慢查询
  getApiLatency(): Promise<LatencyStats>;             // API延迟
  
  // 审计日志
  getAuditLogs(filter): Promise<AuditLog[]>;          // 审计日志
  logAdminOperation(operation): Promise<void>;        // 记录管理员操作
}
```

---

## 🎯 实施方案

### 阶段一：核心功能（MVP）

**时间：1-2个月**

**实现内容：**
1. ✅ 管理端前端（React + Ant Design Pro）
2. ✅ 管理端后端API（Node.js + Fastify）
3. ✅ 管理员认证与权限
4. ✅ 用户管理（P0）
5. ✅ Feature Flag管理（P0）
6. ✅ LLM模型管理（P0）
7. ✅ 基础监控（错误日志、审计日志）

---

### 阶段二：运营功能

**时间：1-2个月**

**实现内容：**
1. ✅ 智能体提示词管理
2. ✅ 数据统计与报表
3. ✅ 成本分析与计费
4. ✅ 公告与通知管理

---

### 阶段三：高级功能

**时间：1-2个月**

**实现内容：**
1. ✅ 租户管理（私有化部署需要）
2. ✅ 反馈与工单系统
3. ✅ 帮助文档管理
4. ✅ 系统健康检查
5. ✅ 数据库备份与恢复

---

## 📊 技术选型

### 前端技术栈

**推荐：Ant Design Pro**
```
admin-frontend/
  ├── React 18
  ├── TypeScript
  ├── Ant Design Pro (开箱即用的中台前端解决方案)
  ├── Ant Design Charts (数据可视化)
  ├── ProComponents (高级组件)
  └── UmiJS (路由和构建)
```

**优势：**
- ✅ 专为中台/管理系统设计
- ✅ 开箱即用的布局、菜单、权限、表格、表单
- ✅ 丰富的数据可视化组件
- ✅ 与Ant Design生态完美集成

---

### 后端技术栈

**继续使用现有技术栈：**
```
backend/
  ├── Node.js + TypeScript
  ├── Fastify
  ├── Prisma
  └── PostgreSQL
```

**新增模块：**
```
backend/src/admin/
  ├── controllers/       # 管理端控制器
  ├── services/          # 管理端服务
  ├── middleware/        # 管理员认证中间件
  └── routes/            # 管理端路由
```

---

## 🎯 总结

### 运营管理端的定位

**运营管理端是：**
- ✅ 一个**独立的应用系统**（独立前端 + 独立API）
- ✅ **横跨所有层次**的管理者（管理平台层、能力层、业务层）
- ✅ **商业运营的核心**（Feature Flag、成本控制、计费管理）
- ✅ **系统健康的保障**（监控、日志、健康检查）

### 完整功能清单

**您提到的4个功能：**
1. ✅ 用户管理
2. ✅ 智能体提示词设置
3. ✅ 版本功能设置（Feature Flag）
4. ✅ 用户权限和版本设置

**我补充的11个功能：**
5. 🆕 租户管理（私有化部署）
6. 🆕 LLM模型管理（关键）
7. 🆕 系统配置管理
8. 🆕 监控与日志（关键）
9. 🆕 数据统计与报表（关键）
10. 🆕 成本分析与计费（商业关键）
11. 🆕 公告与通知管理
12. 🆕 帮助文档管理
13. 🆕 反馈与工单管理
14. 🆕 系统健康检查
15. 🆕 数据库备份与恢复

**总计：15个功能模块**

### 对系统总体设计的影响

1. ✅ **新增独立前端应用**（admin-frontend/）
2. ✅ **新增独立后端API**（/api/admin/*）
3. ✅ **扩展权限体系**（管理员角色、管理员权限）
4. ✅ **扩展数据库Schema**（admin_schema）
5. ✅ **增强LLM Gateway**（使用量统计、成本分析）
6. ✅ **新增监控服务**（实时监控、错误监控、性能监控）

### 实施建议

**阶段一（P0）：** 1-2个月
- 用户管理、Feature Flag、LLM模型管理、基础监控

**阶段二（P1）：** 1-2个月
- 智能体管理、数据统计、成本分析、公告管理

**阶段三（P2）：** 1-2个月
- 租户管理、反馈工单、帮助文档、健康检查、备份恢复

---

**下一步建议：**
1. 确认运营管理端的功能优先级
2. 设计管理端的UI原型
3. 设计管理端的数据库表结构
4. 设计管理端的API接口