# 积分与AI任务系统设计文档

## 1. 项目概述

### 1.1 背景与目标

为集成第三方AI模型（如Sora Image/Video），并建立一套商业化积分体系，本项目旨在设计并开发一个稳定、可扩展、安全的积分消费与AI任务管理系统。

**核心目标:**

- **商业化闭环:** 建立用户充值、积分兑换、模型消费的完整商业流程。
- **任务持久化:** 保证用户提交的AI生成任务不因刷新或关闭页面而丢失，可随时查看历史记录。
- **高效队列管理:** 解决API并发限制问题，通过队列机制保证服务稳定性和用户体验。
- **实时反馈:** 为用户提供任务的实时进度更新，提升交互体验。
- **安全可靠:** 保证积分和交易数据的安全，防止恶意攻击和滥用。

### 1.2 设计原则

- **高内聚低耦合:** 各模块（积分、任务、队列、API调用）职责清晰，易于维护和扩展。
- **异步化处理:** 核心AI任务采用异步处理，避免长时间阻塞，提高系统吞吐量。
- **状态驱动:** 任务和积分为状态驱动，保证数据一致性和流程可追溯性。
- **用户为中心:** 优化从提交任务到获取结果的全流程体验。
- **安全第一:** 在设计、开发、部署各环节贯彻安全思想。

---

## 2. 系统架构

系统采用微服务化的思想，将核心功能模块化，通过API和消息队列进行通信。

```mermaid
graph TD
    subgraph 用户端 (Web/App)
        A[用户界面]
    end

    subgraph 服务端 (Backend)
        B[API网关]
        C[积分服务 PointsService]
        D[AI任务服务 AiTaskService]
        E[队列管理器 QueueManager]
        F[定时任务 Scheduler]
        G[WebSocket服务]
    end

    subgraph 第三方服务
        H[中转站AI API]
    end

    subgraph 基础设施
        I[MySQL数据库]
        J[Redis缓存/队列]
    end

    A -- REST API --> B
    B -- 调用 --> C
    B -- 调用 --> D
    
    D -- 操作任务 --> I
    D -- 添加任务到 --> E
    D -- 更新积分 --> C
    
    C -- 操作积分 --> I

    E -- 使用 --> J
    E -- 触发 --> D

    F -- 扫描 --> E
    F -- 清理 --> D

    D -- 推送进度 --> G
    G -- WebSocket --> A
    
    D -- 调用 --> H
```

**核心流程:**
1. 用户通过**API网关**提交AI任务。
2. **AI任务服务**接收请求，调用**积分服务**冻结相应积分。
3. 任务服务将任务信息持久化到**MySQL**，并交给**队列管理器**。
4. **队列管理器**基于**Redis**实现任务排队，并根据并发限制（50个）决定是否立即处理。
5. **定时任务**周期性扫描队列，将排队的任务交给任务服务处理。
6. 任务服务异步调用**中转站AI API**，并通过**WebSocket**向用户实时推送进度。
7. 任务完成后，更新数据库状态，并调用积分服务进行最终的扣除或退款。

---

## 3. 核心功能设计

### 3.1 积分体系设计

#### 3.1.1 兑换与定价

- **兑换比例:** `1 元人民币 = 100 积分`
- **模型定价:** 在中转站价格基础上加价50%。

**图片模型定价 (示例)**
| 模型名称 | 中转站价格 | 我方价格 (USD) | 我方价格 (CNY) | 积分消耗 |
|---|---|---|---|---|
| sora_image | $0.01 | $0.015 | ~¥0.11 | **11 积分/张** |
| gpt-4o-image | $0.01 | $0.015 | ~¥0.11 | **11 积分/张** |

**视频模型定价 (示例)**
| 模型名称 | 中转站价格 | 我方价格 (USD) | 我方价格 (CNY) | 积分消耗 |
|---|---|---|---|---|
| sora_video2 | $0.15 | $0.225 | ~¥1.6 | **160 积分/次** |
| sora_video2-15s | $0.25 | $0.375 | ~¥2.6 | **260 积分/次** |
| sora-2-pro-all | $0.40 | $0.60 | ~¥4.2 | **420 积分/次** |
*(注: CNY价格按汇率7.2估算，最终积分以CNY价格为准，取整)*

#### 3.1.2 充值与会员

- **充值档位:** 设计多档位充值套餐，提供不同比例的积分赠送。
- **会员体系:** VIP/SVIP会员可享受每日免费积分、生成任务折扣等权益。

### 3.2 AI任务管理

#### 3.2.1 任务生命周期

```mermaid
stateDiagram-v2
    [*] --> created: 用户提交
    created --> queued: 进入队列
    created --> processing: 队列有空位
    queued --> processing: 轮到处理
    processing --> completed: 生成成功
    processing --> failed: 生成失败
    queued --> cancelled: 用户取消
    processing --> cancelled: 用户取消(不支持)
    failed --> processing: 系统重试
    completed --> [*]
    failed --> [*]
    cancelled --> [*]
```
- **created:** 任务已创建，积分已冻结。
- **queued:** 系统繁忙，任务在队列中等待。
- **processing:** 任务正在被AI模型处理。
- **completed:** 任务成功，结果已生成。
- **failed:** 任务失败，积分将退还。
- **cancelled:** 用户主动取消（仅排队中可取消）。

#### 3.2.2 队列管理

- **系统并发限制:** 每个模型最多同时处理50个任务。
- **用户并发限制:** 每个用户最多同时进行3个任务。
- **优先级策略:** SVIP > VIP > 普通用户 > 等待时间。
- **超时机制:** `processing`状态超过10分钟的任务将被标记为失败，并自动退款。

---

## 4. 数据库设计

为支持以上功能，需新增以下核心表：

```sql
-- AI生成任务表 (核心)
CREATE TABLE IF NOT EXISTS `ai_task` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `task_no` varchar(64) UNIQUE NOT NULL COMMENT '任务编号',
  `user_id` bigint NOT NULL,
  `model_name` varchar(64) NOT NULL,
  `task_type` varchar(32) NOT NULL COMMENT '任务类型 (image/video)',
  `prompt` text NOT NULL,
  `status` varchar(32) NOT NULL DEFAULT 'created' COMMENT '任务状态 (created, queued, processing, completed, failed, cancelled)',
  `progress` int DEFAULT 0 COMMENT '进度百分比',
  `progress_message` varchar(255) DEFAULT NULL,
  `points_frozen` int NOT NULL COMMENT '冻结积分',
  `points_consumed` int DEFAULT 0 COMMENT '实际消耗积分',
  `result_url` varchar(512) DEFAULT NULL,
  `error_message` text DEFAULT NULL,
  `queue_time` datetime DEFAULT NULL,
  `start_time` datetime DEFAULT NULL,
  `complete_time` datetime DEFAULT NULL,
  `expire_time` datetime DEFAULT NULL COMMENT '结果过期时间',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  `is_deleted` tinyint(1) NOT NULL DEFAULT 0,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_task_no` (`task_no`),
  KEY `idx_user_status` (`user_id`, `status`),
  KEY `idx_status_time` (`status`, `create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='AI生成任务表';

-- 积分消费配置表
CREATE TABLE IF NOT EXISTS `points_config` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `model_name` varchar(64) UNIQUE NOT NULL COMMENT '模型名称',
  `points_cost` int NOT NULL COMMENT '积分消耗',
  `description` varchar(255) DEFAULT NULL,
  `is_enabled` tinyint(1) NOT NULL DEFAULT 1,
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='积分消费配置表';

-- 积分消费记录表
CREATE TABLE IF NOT EXISTS `points_consumption_log` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `user_id` bigint NOT NULL,
  `task_no` varchar(64) DEFAULT NULL,
  `change_type` varchar(32) NOT NULL COMMENT '(consume, refund)',
  `change_amount` int NOT NULL,
  `balance_before` int NOT NULL,
  `balance_after` int NOT NULL,
  `description` varchar(255) DEFAULT NULL,
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='积分消费记录表';

-- 系统配置表
CREATE TABLE IF NOT EXISTS `system_config` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `config_key` varchar(64) UNIQUE NOT NULL,
  `config_value` varchar(512) NOT NULL,
  `description` varchar(255) DEFAULT NULL,
  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统配置表';
```

---

## 5. 安全设计

安全是本系统的重中之重，需在多个层面进行防御。

### 5.1 防滥用与攻击

- **接口频率限制:** 对任务提交、状态查询等核心接口进行IP和用户级别的双重限流，防止CC攻击。
- **图形验证码:** 在登录、充值、提交任务等关键操作前，引入图形验证码，防止机器人批量操作。
- **输入校验:** 对所有用户输入（特别是`prompt`）进行严格的XSS和SQL注入过滤，防止恶意脚本和敏感信息泄露。
- **API密钥保护:** 中转站的API Key必须存储在安全的环境变量或配置中心，绝不能硬编码在代码中。所有对外的API调用需在服务端完成，严禁在前端暴露密钥。

### 5.2 数据与交易安全

- **事务一致性:** 积分的冻结、扣除、退款操作必须与任务状态变更在同一个数据库事务中完成，保证数据原子性，防止出现"钱扣了任务没创建"等问题。
- **防并发竞争 (Race Condition):** 在扣减积分、更新任务状态等操作时，使用乐观锁（增加`version`字段）或悲观锁（`SELECT ... FOR UPDATE`），防止并发请求导致的数据错乱（如一笔积分被消费两次）。
- **敏感数据加密:** 数据库中存储的密码、API密钥等敏感信息必须使用强哈希算法（如Argon2, bcrypt）进行加密存储。
- **日志审计:** 对所有积分变更、管理员操作进行详细的日志记录，便于审计和问题追溯。

### 5.3 访问控制

- **权限分离:** 严格区分用户和管理员的API接口，使用基于角色的访问控制（RBAC）。普通用户不能访问任何管理接口。
- **水平越权防护:** 所有查询和操作用户数据的接口，必须严格校验当前登录用户ID与要操作的数据归属ID是否一致，防止用户A操作用户B的任务或积分。
- **CSRF防护:** 对所有状态变更的POST/PUT请求（如取消任务、修改配置）启用CSRF Token验证。

---

## 6. 开发功能清单

### 第一阶段：核心后台 (15人日)
- [ ] 数据库表结构设计与创建
- [ ] 实体类与Mapper层代码生成
- [ ] 积分核心服务 (查询、冻结、扣除、退款)
- [ ] AI任务核心服务 (创建、状态更新)
- [ ] 积分与任务的事务性保证
- [ ] 中转站API客户端封装

### 第二阶段：队列与异步 (10人日)
- [ ] 基于Redis的队列管理器实现
- [ ] 任务优先级算法实现
- [ ] 异步处理任务的`@Async`配置
- [ ] 队列扫描、超时检查、过期清理的定时任务
- [ ] WebSocket服务基础搭建

### 第三阶段：API与前端 (12人日)
- [ ] 用户端API接口开发 (提交、查询、列表、取消)
- [ ] WebSocket实时进度推送实现
- [ ] 管理端API接口开发 (任务监控、队列配置)
- [ ] 详细的API文档编写 (Swagger/OpenAPI)
- [ ] 前端任务提交与结果展示页面
- [ ] 前端任务历史列表与状态展示

### 第四阶段：安全与测试 (8人日)
- [ ] 单元测试与集成测试编写
- [ ] 安全加固 (限流、输入校验、权限检查)
- [ ] 压力测试 (模拟高并发提交任务)
- [ ] 部署脚本编写与上线

---

## 7. 任务进度计划 (甘特图)

| 阶段 | 任务 | 负责人 | 预估工时 | W1 | W2 | W3 | W4 | W5 | 状态 |
|:---|:---|:---|:---:|:---:|:---:|:---:|:---:|:---:|:---|
| **P1: 核心后台** | 数据库设计与创建 | 后端A | 2d | ██ | | | | | ✅ |
| | 核心服务开发 | 后端A | 8d | ████ | ████ | | | |  진행중 |
| | API客户端封装 | 后端B | 3d | ███ | | | | | ✅ |
| | 单元测试(P1) | 后端A/B | 2d | | | ██ | | | 대기 |
| **P2: 队列与异步** | 队列管理器实现 | 后端B | 5d | | ███ | ██ | | | 대기 |
| | 定时任务开发 | 后端A | 3d | | | | ███ | | 대기 |
| | WebSocket搭建 | 后端B | 2d | | | | | ██ | 대기 |
| **P3: API与前端** | 用户端API开发 | 后端A | 4d | | | ████ | | | 대기 |
| | 管理端API开发 | 后端B | 2d | | | | ██ | | 대기 |
| | 前端页面开发 | 前端C | 6d | | | ██ | ████ | | 대기 |
| **P4: 测试与部署** | 集成与压力测试 | 测试D | 5d | | | | | █████ | 대기 |
| | 安全加固与部署 | 运维E | 3d | | | | | | ███ |

*(注: d=人日, 一个█代表1人日)*