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

[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）

-- 已有表
- 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

关键表结构：

-- 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查看成本分析报表
   - 总成本
   - 各模型成本占比
   - 用户消费排行

关键表结构：

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加密

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模型管理、日志查询

// 权限检查中间件
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分钟）
• 数据预聚合（定时任务）
• 分页查询

// 缓存报表数据
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)
• LLM大模型网关
• 监控与日志

详细设计：

• 运营管理端完整设计

---

最后更新： 2025-11-06
维护人： 技术架构师
优先级： P1