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