300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
# 积分与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人日)*
|