[Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00
commit 0f7bc05697
587 changed files with 103215 additions and 0 deletions
--- a/ADMIN_AI_POINTS_API_GUIDE.md
+++ b/ADMIN_AI_POINTS_API_GUIDE.md
@@ -0,0 +1,587 @@
+# 管理端 - 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
+