Develop/AIclinicalresearch
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: complete documentation system (250+ files)

Browse Source 
- 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:
HaHafeng
2025-11-16 15:43:55 +08:00
parent 0fe6821a89
commit e52020409c
173 changed files with 46227 additions and 11964 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/03-业务模块/ADMIN-运营管理端/README.md Normal file
View File

@@ -0,0 +1,101 @@
# ADMIN - 运营管理端
> **模块代号：** ADMIN (Administration)
> **开发状态：** ⏳ 规划中
> **商业价值：** ⭐⭐⭐⭐⭐ SaaS运营基础
> **独立性：** ⭐⭐⭐⭐⭐
> **优先级：** P1
---
## 📋 模块概述
运营管理端横跨所有层次，是SaaS商业模式的技术基础。
**核心价值：** 实现多版本管理、成本控制、功能开关
---
## 🎯 核心功能（15个模块）
### P0（必须，阶段一）
1. **用户管理** - 用户列表、详情、激活/禁用
2. **Feature Flag管理** ⭐ - 版本功能控制（专业版/高级版/旗舰版）
3. **LLM模型管理** ⭐ - 模型配置、成本配置、版本绑定
4. **系统配置管理** - 全局配置、动态配置
### P1（重要，阶段二）
5. **智能体提示词管理** - Prompt模板管理
6. **监控与日志** - 操作日志、错误监控
7. **数据统计与报表** - 用户统计、使用统计
8. **成本分析与计费** - LLM成本统计、计费管理
### P2（有用，阶段三）
9. **租户管理** - 私有化部署的租户管理
10. **公告与通知管理**
11. **帮助文档管理**
12. **反馈与工单管理**
13. **系统健康检查**
14. **数据库备份与恢复**
15. **运营数据分析**
---
## 📂 文档结构
```
ADMIN-运营管理端/
├── [AI对接] ADMIN快速上下文.md # ⏳ 待创建
├── 00-项目概述/
│ ├── 01-产品需求文档(PRD).md # ⏳ 待创建
│ ├── 02-功能清单（15个模块）.md # ⏳ 待创建
│ └── 03-权限体系设计.md # ⏳ 待创建
├── 01-设计文档/
│ ├── 01-技术架构设计.md # ⏳ 待创建
│ ├── 02-数据库设计.md # ⏳ 待创建
│ └── 05-权限体系实现.md # ⏳ 待创建
└── README.md # ✅ 当前文档
```
---
## 🏗️ 技术选型
- **前端：** React + Ant Design Pro
- **后端：** Node.js + Fastify
- **数据库：** PostgreSQL (admin_schema)
---
## 🚀 实施阶段
- **阶段一（1-2个月）：** P0功能
- **阶段二（1-2个月）：** P1功能
- **阶段三（1-2个月）：** P2功能
---
## 🌐 部署方式
- **独立域名：** `https://admin.yizhengxun.com`
- **独立前端应用**
- **独立后端API**
---
**最后更新：** 2025-11-06
**维护人：** 技术架构师

504
docs/03-业务模块/ADMIN-运营管理端/[AI对接] ADMIN快速上下文.md Normal file
View File

@@ -0,0 +1,504 @@
# [AI对接] ADMIN快速上下文
> **阅读时间：** 5分钟 | **Token消耗：** ~2000 tokens
> **层级：** L2 | **优先级：** P1
> **前置阅读：** 03-业务模块/[AI对接] 业务模块快速上下文.md
---
## 📋 模块定位
**运营管理端是SaaS商业模式的运营基础，管理用户、权限、LLM模型、成本等15个功能模块。**
**商业价值：** ⭐⭐⭐⭐⭐ SaaS运营必备
**开发状态：** ⏳ 规划中（P1优先级）
**依赖能力：** 平台基础层（UAM、监控日志）、LLM网关
---
## 🎯 核心功能（15个模块）
### P0优先级（4个）⭐ 最核心
| 模块 | 功能 | 商业价值 |
|------|------|---------|
| **用户管理** | 用户CRUD、套餐管理、禁用/启用 | 基础运营 |
| **Feature Flag管理** | 功能开关配置、版本权限控制 | 商业模式基础 |
| **LLM模型管理** | 模型配置、价格管理、可用性控制 | 成本控制 |
| **系统配置** | 全局配置、环境切换、参数管理 | 系统运维 |
---
### P1优先级（8个）
| 模块 | 功能 | 说明 |
|------|------|------|
| **Prompt管理** | 智能体Prompt模板管理 | 提高AI效果 |
| **监控与日志** | 操作日志查询、错误监控 | 运维支持 |
| **成本分析** | LLM成本统计、用户消费排行 | 成本优化 |
| **数据报表** | 用户活跃度、功能使用率 | 运营决策 |
| **业务数据管理** | 文献项目、知识库等业务数据查看 | 运营支持 |
| **审核管理** | 稿件审查任务管理（RVW模块） | 业务支持 |
| **系统监控** | 服务健康度、API响应时间 | 技术运维 |
| **备份管理** | 数据备份、恢复 | 数据安全 |
---
### P2优先级（3个）
| 模块 | 功能 |
|------|------|
| **租户管理** | SaaS多租户管理（高级功能） |
| **公告管理** | 系统公告发布 |
| **帮助文档** | 在线帮助文档管理 |
---
## 🏗️ 技术架构
### 前端（React）
```
src/pages/Admin/
├── Dashboard/ # 首页仪表盘
├── Users/ # 用户管理 ⭐ P0
│ ├── UserList.tsx
│ ├── UserDetail.tsx
│ └── UserEdit.tsx
├── FeatureFlags/ # Feature Flag管理 ⭐ P0
│ ├── FlagList.tsx
│ └── FlagConfig.tsx
├── LLM/ # LLM模型管理 ⭐ P0
│ ├── ModelList.tsx
│ ├── ModelConfig.tsx
│ └── CostAnalysis.tsx
├── Prompts/ # Prompt管理 P1
├── Logs/ # 日志查询 P1
├── Reports/ # 数据报表 P1
└── Settings/ # 系统配置 ⭐ P0
```
### 后端（Node.js）
```
backend/src/modules/admin/
├── controllers/
│ ├── userController.ts # 用户管理 ⭐
│ ├── featureFlagController.ts # Feature Flag ⭐
│ ├── llmController.ts # LLM模型管理 ⭐
│ ├── promptController.ts
│ ├── logController.ts
│ └── reportController.ts
├── services/
│ ├── userService.ts
│ ├── featureFlagService.ts
│ ├── llmService.ts
│ └── reportService.ts
└── routes/
└── adminRoutes.ts
```
### 数据库（platform_schema）
```sql
-- 已有表
- users # 用户基础信息
- roles # 角色
- permissions # 权限
- feature_flags # Feature Flag配置
- user_feature_flags # 用户Feature Flag关联
- llm_usage # LLM使用记录
- llm_quotas # LLM配额
- admin_logs # 管理员操作日志
-- 需要新增
- llm_models # LLM模型配置 ⭐ P0
- prompt_templates # Prompt模板 P1
- system_configs # 系统配置 ⭐ P0
- announcements # 系统公告 P2
```
---
## 💡 核心业务流程
### 1. Feature Flag配置流程 ⭐⭐⭐⭐⭐
```
1. ADMIN在管理端配置Feature Flag
- 功能名称：claude_access
- 描述：是否可以使用Claude模型
- 默认值：false
↓
2. 为不同套餐配置不同的Feature Flag
- 专业版：只有 deepseek_access
- 高级版：deepseek_access + qwen3_access
- 旗舰版：全部模型访问权限
↓
3. 用户升级套餐时，自动更新Feature Flag
↓
4. 业务模块（ASL、AIA等）调用LLM网关时，自动检查Feature Flag
```
**关键表结构：**
```sql
-- Feature Flag定义
CREATE TABLE platform_schema.feature_flags (
id SERIAL PRIMARY KEY,
flag_key VARCHAR(100) UNIQUE NOT NULL, -- 'claude_access'
flag_name VARCHAR(200) NOT NULL, -- 'Claude模型访问权限'
description TEXT,
default_value BOOLEAN DEFAULT FALSE,
created_at TIMESTAMP DEFAULT NOW()
);
-- 用户Feature Flag（覆盖默认值）
CREATE TABLE platform_schema.user_feature_flags (
id SERIAL PRIMARY KEY,
user_id INTEGER REFERENCES platform_schema.users(id),
flag_id INTEGER REFERENCES platform_schema.feature_flags(id),
value BOOLEAN NOT NULL,
created_at TIMESTAMP DEFAULT NOW(),
UNIQUE(user_id, flag_id)
);
```
---
### 2. LLM模型管理流程 ⭐⭐⭐⭐
```
1. ADMIN配置LLM模型
- 模型名称：DeepSeek-V3
- API Key
- 价格：¥1/百万tokens
- 是否启用
↓
2. LLM网关根据配置调用模型
↓
3. 记录每次调用的成本
↓
4. ADMIN查看成本分析报表
- 总成本
- 各模型成本占比
- 用户消费排行
```
**关键表结构：**
```sql
CREATE TABLE platform_schema.llm_models (
id SERIAL PRIMARY KEY,
model_key VARCHAR(50) UNIQUE NOT NULL, -- 'deepseek-v3'
model_name VARCHAR(100) NOT NULL, -- 'DeepSeek-V3'
provider VARCHAR(50), -- 'deepseek', 'openai', 'anthropic'
api_endpoint TEXT,
api_key_encrypted TEXT, -- 加密存储
price_per_million_tokens DECIMAL(10, 6), -- 每百万tokens价格
is_enabled BOOLEAN DEFAULT TRUE,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
```
---
### 3. 用户管理流程
```
1. ADMIN创建用户
- 基础信息（姓名、邮箱等）
- 选择套餐（professional/premium/enterprise）
- 自动配置对应的Feature Flag
↓
2. ADMIN管理用户
- 修改套餐（Feature Flag自动更新）
- 禁用/启用账号
- 重置密码
- 调整LLM配额
↓
3. ADMIN查看用户详情
- 基础信息
- LLM使用统计
- 功能使用记录
- 文献项目、知识库等业务数据
```
---
## 📋 核心API端点
### 用户管理 ⭐ P0
```
GET /api/v1/admin/users # 用户列表（分页、筛选）
GET /api/v1/admin/users/:id # 用户详情
POST /api/v1/admin/users # 创建用户
PUT /api/v1/admin/users/:id # 更新用户
DELETE /api/v1/admin/users/:id # 删除用户
POST /api/v1/admin/users/:id/disable # 禁用用户
POST /api/v1/admin/users/:id/enable # 启用用户
PUT /api/v1/admin/users/:id/plan # 修改套餐
```
### Feature Flag管理 ⭐ P0
```
GET /api/v1/admin/feature-flags # Feature Flag列表
POST /api/v1/admin/feature-flags # 创建Feature Flag
PUT /api/v1/admin/feature-flags/:id # 更新Feature Flag
DELETE /api/v1/admin/feature-flags/:id # 删除Feature Flag
GET /api/v1/admin/users/:id/flags # 查询用户Feature Flag
PUT /api/v1/admin/users/:id/flags # 更新用户Feature Flag
```
### LLM模型管理 ⭐ P0
```
GET /api/v1/admin/llm/models # 模型列表
POST /api/v1/admin/llm/models # 添加模型
PUT /api/v1/admin/llm/models/:id # 更新模型
DELETE /api/v1/admin/llm/models/:id # 删除模型
GET /api/v1/admin/llm/usage # LLM使用统计
GET /api/v1/admin/llm/cost-analysis # 成本分析
```
### Prompt管理 P1
```
GET /api/v1/admin/prompts # Prompt模板列表
POST /api/v1/admin/prompts # 创建Prompt
PUT /api/v1/admin/prompts/:id # 更新Prompt
DELETE /api/v1/admin/prompts/:id # 删除Prompt
```
### 日志查询 P1
```
GET /api/v1/admin/logs # 日志列表（分页、筛选）
GET /api/v1/admin/logs/errors # 错误日志
GET /api/v1/admin/logs/operations # 操作日志
```
### 数据报表 P1
```
GET /api/v1/admin/reports/overview # 总览数据
GET /api/v1/admin/reports/users # 用户活跃度
GET /api/v1/admin/reports/features # 功能使用率
GET /api/v1/admin/reports/llm # LLM使用统计
```
---
## 📊 核心页面设计
### 1. 仪表盘（Dashboard）
**核心指标：**
- 总用户数 / 活跃用户数
- 本月LLM调用次数 / 成本
- 各模块使用率
- 错误日志数量
### 2. 用户管理
**功能：**
- 列表：搜索、筛选（套餐、状态）、排序
- 详情：基础信息 + 使用统计 + 业务数据
- 编辑：修改套餐、调整配额、禁用/启用
### 3. Feature Flag管理 ⭐
**核心界面：**
```
┌─────────────────────────────────────────┐
│ Feature Flag管理 │
├─────────────────────────────────────────┤
│ [+ 新增Flag] │
│ │
│ Flag Key | 描述 | 默认值 │
│─────────────────────────────────────────│
│ claude_access | Claude访问 | ❌ │
│ qwen3_access | Qwen3访问 | ❌ │
│ deepseek_access | DeepSeek访问| ✅ │
│─────────────────────────────────────────│
│ │
│ 套餐配置： │
│ 专业版：deepseek_access │
│ 高级版：deepseek_access, qwen3_access │
│ 旗舰版：全部模型 │
└─────────────────────────────────────────┘
```
### 4. LLM成本分析 ⭐
**核心图表：**
- 成本趋势图（按天）
- 模型成本占比（饼图）
- 用户消费排行（柱状图）
- 模块使用分布（饼图）
---
## ⚠️ 关键技术难点
### 1. API Key安全存储
**解决方案：** AES-256加密
```typescript
import crypto from 'crypto';
const ENCRYPTION_KEY = process.env.ENCRYPTION_KEY; // 32字节
const IV_LENGTH = 16;
function encrypt(text: string): string {
const iv = crypto.randomBytes(IV_LENGTH);
const cipher = crypto.createCipheriv('aes-256-cbc', Buffer.from(ENCRYPTION_KEY), iv);
let encrypted = cipher.update(text);
encrypted = Buffer.concat([encrypted, cipher.final()]);
return iv.toString('hex') + ':' + encrypted.toString('hex');
}
function decrypt(text: string): string {
const parts = text.split(':');
const iv = Buffer.from(parts[0], 'hex');
const encrypted = Buffer.from(parts[1], 'hex');
const decipher = crypto.createDecipheriv('aes-256-cbc', Buffer.from(ENCRYPTION_KEY), iv);
let decrypted = decipher.update(encrypted);
decrypted = Buffer.concat([decrypted, decipher.final()]);
return decrypted.toString();
}
```
---
### 2. 权限控制
**ADMIN角色：**
- 超级管理员：全部权限
- 运营管理员：用户管理、报表查看
- 技术管理员：LLM模型管理、日志查询
```typescript
// 权限检查中间件
async function checkAdminPermission(req, reply, permission: string) {
const user = req.user;
if (!user.isAdmin) {
throw new UnauthorizedError('需要管理员权限');
}
const hasPermission = await permissionService.check(user.id, permission);
if (!hasPermission) {
throw new ForbiddenError('权限不足');
}
}
// 使用
app.get('/api/v1/admin/users', {
preHandler: checkAdminPermission('user:read')
}, userController.list);
```
---
### 3. 数据报表性能优化
**问题：** 大数据量查询慢
**解决方案：**
- Redis缓存（5分钟）
- 数据预聚合（定时任务）
- 分页查询
```typescript
// 缓存报表数据
async function getOverviewReport() {
const cacheKey = 'admin:report:overview';
// 先查缓存
const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);
// 查询数据库
const data = await db.query(`
SELECT
COUNT(DISTINCT user_id) as total_users,
SUM(total_tokens) as total_tokens,
SUM(cost) as total_cost
FROM platform_schema.llm_usage
WHERE created_at >= date_trunc('month', NOW())
`);
// 缓存5分钟
await redis.set(cacheKey, JSON.stringify(data), 'EX', 300);
return data;
}
```
---
## 📅 开发计划
### Phase 1：P0核心功能（Week 1-2）
- **用户管理**（3天）
- Day 1: 后端API（CRUD）
- Day 2: 前端列表和详情
- Day 3: 套餐管理、禁用/启用
- **Feature Flag管理**（2天）
- Day 1: 后端API + 数据库
- Day 2: 前端配置界面
- **LLM模型管理**（2天）
- Day 1: 后端API + 加密存储
- Day 2: 前端配置界面
- **系统配置**（1天）
### Phase 2：P1功能（Week 3-4）
- Prompt管理（2天）
- 日志查询（2天）
- 成本分析报表（3天）
- 数据报表（3天）
### Phase 3：P2功能（Week 5）
- 租户管理
- 公告管理
- 帮助文档
---
## ✅ 开发检查清单
**开始前确认：**
- [ ] ADMIN角色和权限已配置
- [ ] 数据库表已创建（llm_models, system_configs等）
- [ ] Redis已部署（用于报表缓存）
- [ ] ENCRYPTION_KEY环境变量已配置
**P0功能完成标准：**
- [ ] ADMIN可以创建/编辑/删除用户
- [ ] ADMIN可以配置Feature Flag
- [ ] ADMIN可以配置LLM模型
- [ ] ADMIN可以查看LLM成本统计
- [ ] 所有敏感操作都记录到admin_logs
---
## 🔗 相关文档
**依赖：**
- [用户与权限中心(UAM)](../../01-平台基础层/01-用户与权限中心(UAM)/README.md)
- [LLM大模型网关](../../02-通用能力层/01-LLM大模型网关/README.md)
- [监控与日志](../../01-平台基础层/04-监控与日志/README.md)
**详细设计：**
- [运营管理端完整设计](./README.md)
---
**最后更新：** 2025-11-06
**维护人：** 技术架构师
**优先级：** P1