lth/1818web-hoduan

Fork 0

Files

Claude Workbench 0f7bc05697 [Claude Workbench] Initial commit - preserving existing code

2025-11-14 17:41:15 +08:00

12 KiB

Raw Blame History

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

1. 项目概述

1.1 背景与目标

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

核心目标:

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

1.2 设计原则

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

2. 系统架构

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

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

核心流程:

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

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 任务生命周期

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. 数据库设计

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

-- 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人日)

12 KiB Raw Blame History Unescape Escape