docs: complete documentation system (250+ files)

- System architecture and design documentation
- Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST)
- ASL module complete design (quality assurance, tech selection)
- Platform layer and common capabilities docs
- Development standards and API specifications
- Deployment and operations guides
- Project management and milestone tracking
- Architecture implementation reports
- Documentation templates and guides
This commit is contained in:
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions

View File

@@ -0,0 +1,872 @@
# 运营管理端架构设计
> **文档版本:** 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调用量
- 成本分析
---
### 模块6LLM模型管理 🆕 **新增(关键)**
**核心功能:**
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普通用户
- vipVIP用户高级功能
管理员角色:⭐ 新增
- 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. ✅ 管理端后端APINode.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接口