# 管理端 - AI积分与模型配置 API 接口文档

## 📋 目录

1. [概述](#概述)
2. [认证说明](#认证说明)
3. [积分配置管理](#积分配置管理)
4. [系统配置管理](#系统配置管理)
5. [AI任务监控](#ai任务监控)
6. [业务流程说明](#业务流程说明)
7. [常见问题](#常见问题)

---

## 概述

本文档描述了管理员如何通过后台接口管理AI模型的积分价格、系统参数配置以及监控所有用户的AI任务。

### 基础信息

- **Base URL**: `https://your-domain.com`
- **接口前缀**: `/admin`
- **认证方式**: JWT Token (需要 ADMIN 角色)
- **数据格式**: JSON

### 积分与人民币兑换标准

根据系统设计，积分兑换标准如下：

```
1 元人民币 = 100 积分
```

**定价策略：** 在第三方API成本的基础上加价 50%

---

## 认证说明

### 获取管理员Token

**接口**: `POST /admin/auth/login`

**请求示例**:
```json
{
  "username": "admin",
  "password": "your_password"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userId": 1,
    "username": "admin",
    "role": 1
  }
}
```

### 后续请求认证

所有管理端API请求都需要在HTTP Header中携带Token：

```
Authorization: Bearer <your_token_here>
```

---

## 积分配置管理

管理员可以动态调整每个AI模型的积分消费价格。

### 1. 获取所有积分配置

**接口**: `GET /admin/configs/points`

**描述**: 获取所有AI模型的积分配置列表

**请求示例**:
```bash
curl -X GET "https://your-domain.com/admin/configs/points" \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 1,
      "modelName": "sora_image",
      "pointsCost": 11,
      "description": "Sora高质量图片生成",
      "isEnabled": 1,
      "createTime": "2025-10-19T10:00:00",
      "updateTime": "2025-10-19T10:00:00"
    },
    {
      "id": 2,
      "modelName": "sora_video2",
      "pointsCost": 160,
      "description": "Sora视频生成 (竖屏10秒)",
      "isEnabled": 1,
      "createTime": "2025-10-19T10:00:00",
      "updateTime": "2025-10-19T10:00:00"
    }
  ]
}
```

### 2. 创建新的积分配置

**接口**: `POST /admin/configs/points`

**描述**: 为新的AI模型添加积分配置

**请求示例**:
```json
{
  "modelName": "dalle-3",
  "pointsCost": 50,
  "description": "DALL-E 3图片生成",
  "isEnabled": 1
}
```

**字段说明**:
- `modelName` (必填): 模型唯一标识，需与第三方API的模型名称一致
- `pointsCost` (必填): 调用一次该模型需要消耗的积分数
- `description` (可选): 模型的描述信息
- `isEnabled` (必填): 是否启用 (1=启用, 0=禁用)

**响应示例**:
```json
{
  "code": 200,
  "message": "配置创建成功",
  "data": {
    "id": 8,
    "modelName": "dalle-3",
    "pointsCost": 50,
    "description": "DALL-E 3图片生成",
    "isEnabled": 1
  }
}
```

### 3. 更新积分配置

**接口**: `PUT /admin/configs/points/{id}`

**描述**: 修改现有模型的积分价格或其他配置

**请求示例**:
```bash
curl -X PUT "https://your-domain.com/admin/configs/points/1" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "pointsCost": 15,
    "description": "Sora高质量图片生成（已调价）",
    "isEnabled": 1
  }'
```

**响应示例**:
```json
{
  "code": 200,
  "message": "配置更新成功",
  "data": {
    "id": 1,
    "modelName": "sora_image",
    "pointsCost": 15,
    "description": "Sora高质量图片生成（已调价）",
    "isEnabled": 1
  }
}
```

### 4. 删除积分配置

**接口**: `DELETE /admin/configs/points/{id}`

**描述**: 删除指定的积分配置（逻辑删除）

**请求示例**:
```bash
curl -X DELETE "https://your-domain.com/admin/configs/points/8" \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "配置删除成功"
}
```

---

## 系统配置管理

管理员可以调整AI队列、任务超时等系统级参数。

### 1. 获取所有系统配置

**接口**: `GET /admin/configs/system`

**描述**: 获取所有系统配置项

**请求示例**:
```bash
curl -X GET "https://your-domain.com/admin/configs/system" \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "id": 1,
      "configKey": "ai.queue.max_concurrent",
      "configValue": "50",
      "description": "每个AI模型的最大并发处理数",
      "createTime": "2025-10-19T10:00:00",
      "updateTime": "2025-10-19T10:00:00"
    },
    {
      "id": 2,
      "configKey": "ai.queue.max_user_concurrent",
      "configValue": "3",
      "description": "单个用户的最大并发任务数",
      "createTime": "2025-10-19T10:00:00",
      "updateTime": "2025-10-19T10:00:00"
    },
    {
      "id": 3,
      "configKey": "ai.task.timeout_minutes",
      "configValue": "10",
      "description": "任务处理超时时间（分钟）",
      "createTime": "2025-10-19T10:00:00",
      "updateTime": "2025-10-19T10:00:00"
    }
  ]
}
```

### 2. 创建系统配置

**接口**: `POST /admin/configs/system`

**请求示例**:
```json
{
  "configKey": "ai.queue.scan_interval",
  "configValue": "3000",
  "description": "队列扫描间隔（毫秒）"
}
```

### 3. 更新系统配置

**接口**: `PUT /admin/configs/system/{id}`

**描述**: 修改系统配置值

**请求示例**:
```json
{
  "configValue": "100",
  "description": "每个AI模型的最大并发处理数（已调整）"
}
```

**⚠️ 重要提示**: 
- 修改 `ai.queue.max_concurrent` 等配置后，系统会**立即生效**（通过缓存刷新机制）
- 但 `application.yml` 中的配置（如 `ai.queue.scan-interval`）需要**重启服务**才能生效

### 4. 删除系统配置

**接口**: `DELETE /admin/configs/system/{id}`

---

## AI任务监控

管理员可以查看和管理所有用户的AI生成任务。

### 1. 获取任务列表（分页）

**接口**: `GET /admin/ai/tasks/list`

**描述**: 分页查询所有AI任务，支持多条件筛选

**查询参数**:
- `page` (可选): 页码，默认 1
- `size` (可选): 每页数量，默认 10
- `userId` (可选): 按用户ID筛选
- `status` (可选): 按状态筛选 (created, queued, processing, completed, failed, cancelled)
- `modelName` (可选): 按模型名称筛选
- `taskNo` (可选): 按任务编号模糊搜索

**请求示例**:
```bash
curl -X GET "https://your-domain.com/admin/ai/tasks/list?page=1&size=20&status=completed" \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 156,
    "pages": 8,
    "pageNum": 1,
    "pageSize": 20,
    "list": [
      {
        "taskNo": "TASK20251019143022ABC123",
        "userId": 1001,
        "modelName": "sora_image",
        "taskType": "image",
        "prompt": "一只可爱的猫咪在花园里玩耍",
        "status": "completed",
        "progress": 100,
        "progressMessage": "任务已成功完成。",
        "pointsFrozen": 11,
        "pointsConsumed": 11,
        "resultUrl": "https://cdn.example.com/generated/abc123.jpg",
        "queueTime": "2025-10-19T14:30:25",
        "startTime": "2025-10-19T14:30:30",
        "completeTime": "2025-10-19T14:31:15",
        "createTime": "2025-10-19T14:30:22",
        "updateTime": "2025-10-19T14:31:15"
      }
    ]
  }
}
```

### 2. 获取单个任务详情

**接口**: `GET /admin/ai/tasks/{taskNo}`

**描述**: 查询指定任务的详细信息

**请求示例**:
```bash
curl -X GET "https://your-domain.com/admin/ai/tasks/TASK20251019143022ABC123" \
  -H "Authorization: Bearer <token>"
```

### 3. 强制取消任务

**接口**: `POST /admin/ai/tasks/{taskNo}/cancel`

**描述**: 手动取消一个处于排队中（queued）的任务，并退还用户积分

**请求示例**:
```bash
curl -X POST "https://your-domain.com/admin/ai/tasks/TASK20251019143022ABC123/cancel" \
  -H "Authorization: Bearer <token>"
```

**响应示例**:
```json
{
  "code": 200,
  "message": "任务 TASK20251019143022ABC123 已成功取消。"
}
```

**⚠️ 注意**: 
- 只有状态为 `queued` 的任务可以被取消
- 已经在 `processing` 状态的任务无法取消
- 取消后，冻结的积分会全额退还给用户

---

## 业务流程说明

### 1. 积分定价流程

以 Sora Image 为例，完整的定价计算过程：

```
第三方API成本: $0.01/张
↓
人民币成本: 0.01 × 7.3 (汇率) = 0.073 元
↓
加价50%: 0.073 × 1.5 = 0.1095 元
↓
向上取整: 0.11 元
↓
转换为积分: 0.11 × 100 = 11 积分
```

**当前系统中的定价标准**:

| 模型名称 | 第三方成本 | 我方定价 | 积分价格 |
|---------|----------|---------|---------|
| sora_image | $0.01 | ¥0.11 | 11积分 |
| gpt-4o-image | $0.01 | ¥0.11 | 11积分 |
| sora_video2 | $0.15 | ¥1.60 | 160积分 |
| sora_video2-landscape | $0.15 | ¥1.60 | 160积分 |
| sora_video2-15s | $0.25 | ¥2.60 | 260积分 |
| sora_video2-landscape-15s | $0.25 | ¥2.60 | 260积分 |
| sora-2-pro-all | $0.40 | ¥4.20 | 420积分 |

### 2. 用户调用AI模型的完整流程

```
1. 用户提交任务
   ↓
2. 系统检查用户积分是否充足
   ↓
3. 冻结所需积分 (points_frozen)
   ↓
4. 创建任务记录 (status: created)
   ↓
5. 将任务放入Redis队列 (status: queued)
   ↓
6. 调度器检测到可用槽位
   ↓
7. 从队列取出任务，开始处理 (status: processing)
   ↓
8. 异步调用第三方API
   ↓
9a. 成功: 标记任务为completed，记录result_url，消耗积分
9b. 失败: 标记任务为failed，全额退还积分
   ↓
10. 通过WebSocket实时推送进度给用户
```

### 3. 任务超时保护机制

系统有完善的超时保护机制，防止任务卡死：

- **超时检查间隔**: 每60秒检查一次（可在 `application.yml` 中配置 `ai.task.timeout-scan-interval`）
- **超时判定标准**: 任务在 `processing` 状态下超过10分钟（可在数据库 `system_config` 表中修改 `ai.task.timeout_minutes`）
- **超时处理**: 自动标记为 `failed`，全额退还积分

### 4. 并发控制说明

**模型级并发控制**:
- 每个AI模型独立计数
- 默认最大并发数: 50（在 `application.yml` 中配置为 `ai.queue.max-concurrent: 50`）
- 当前正在处理的任务数达到上限时，新任务会在队列中等待

**用户级并发控制** (可选，已在 `system_config` 中预留配置):
- 单个用户最多同时处理3个任务（`ai.queue.max_user_concurrent`）
- 防止单个用户占用过多资源

---

## 常见问题

### Q1: 如何修改某个模型的积分价格？

**A**: 使用 `PUT /admin/configs/points/{id}` 接口更新 `pointsCost` 字段。修改后立即生效，影响所有后续创建的任务。

### Q2: 积分配置修改后，正在处理的任务会受影响吗？

**A**: 不会。每个任务在创建时就已经记录了 `points_frozen`（冻结的积分数），这个值不会因为后续的价格调整而改变。

### Q3: 如何临时禁用某个AI模型？

**A**: 将该模型的 `isEnabled` 字段设置为 `0`。禁用后，用户提交该模型的任务时会收到错误提示，但不影响已经在队列中或正在处理的任务。

### Q4: 如何提高系统的处理能力？

**A**: 有两种方式：
1. **修改 `application.yml`**: 增加 `ai.queue.max-concurrent` 的值（需要重启服务）
2. **修改数据库**: 更新 `system_config` 表中 `ai.queue.max_concurrent` 的配置值（立即生效，无需重启）

**推荐使用方式2**，因为它更加灵活，可以根据服务器负载动态调整。

### Q5: 用户的积分是如何退款的？

**A**: 系统在以下情况会自动退还积分：
- 任务失败（`status: failed`）
- 任务超时
- 管理员手动取消任务
- API调用异常

退款会记录在 `points_consumption_log` 表中，`change_type` 为 `refund`。

### Q6: WebSocket推送是如何工作的？

**A**: 
1. 用户连接到 WebSocket 端点: `wss://your-domain.com/ws`
2. 用户订阅自己的进度频道: `/user/queue/tasks-progress`
3. 任务状态变化时（创建、开始处理、完成、失败），系统自动推送JSON格式的进度数据
4. 前端接收数据并更新UI（如进度条、状态文本）

### Q7: 如何查看系统当前的运行状态？

**A**: 可以通过以下方式监控：
1. 使用 `GET /admin/ai/tasks/list?status=processing` 查看当前正在处理的任务数量
2. 使用 `GET /admin/ai/tasks/list?status=queued` 查看队列中等待的任务数量
3. 检查 Redis 中的队列长度（技术手段）

### Q8: 如何备份和恢复积分配置？

**A**: 
- **备份**: 导出 `points_config` 和 `system_config` 表的数据
- **恢复**: 使用 SQL 的 `INSERT ... ON DUPLICATE KEY UPDATE` 语句批量导入

系统在 `V2__add_ai_task_and_points_schema.sql` 中已经提供了初始化数据的示例。

---

## 附录：数据库表结构

### points_config 表

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | bigint | 主键 |
| model_name | varchar(64) | 模型名称（唯一） |
| points_cost | int | 积分消耗 |
| description | varchar(255) | 模型描述 |
| is_enabled | tinyint(1) | 是否启用 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| is_deleted | tinyint(1) | 逻辑删除标识 |

### system_config 表

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | bigint | 主键 |
| config_key | varchar(64) | 配置键（唯一） |
| config_value | varchar(512) | 配置值 |
| description | varchar(255) | 配置说明 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |

### ai_task 表

| 字段 | 类型 | 说明 |
|-----|------|------|
| id | bigint | 主键 |
| task_no | varchar(64) | 任务编号（唯一） |
| user_id | bigint | 用户ID |
| model_name | varchar(64) | 模型名称 |
| task_type | varchar(32) | 任务类型 |
| prompt | text | 提示词 |
| status | varchar(32) | 任务状态 |
| progress | int | 进度百分比 |
| progress_message | varchar(255) | 进度描述 |
| points_frozen | int | 冻结积分 |
| points_consumed | int | 实际消耗积分 |
| result_url | varchar(512) | 结果URL |
| error_message | text | 错误信息 |
| queue_time | datetime | 入队时间 |
| start_time | datetime | 开始处理时间 |
| complete_time | datetime | 完成时间 |
| create_time | datetime | 创建时间 |
| update_time | datetime | 更新时间 |
| is_deleted | tinyint(1) | 逻辑删除标识 |

---

## 技术支持

如有任何问题，请联系技术团队。

**文档版本**: v1.0  
**最后更新**: 2025-10-19