docs/v1.0/server/rfcs/015-credit-system-design.md

算力积分体系设计方案

文档版本：v1.0
创建时间：2025-01-14
作者：系统架构师

---

一、方案概述

1.1 背景

原有的订阅制（免费版/专业版/企业版）改为纯算力积分体系。用户通过充值获得算力积分，使用积分消耗生成 AI 素材（图片、视频、文字处理等）。

1.2 核心目标

• 灵活的按需付费模式
• 透明的积分消耗机制
• 完善的充值和退款流程
• 详细的积分流水记录
• 支持多种支付方式

---

二、业务流程

2.1 完整业务链路

用户注册登录 → 查看积分余额 → 选择充值套餐 → 支付充值 → 获得积分
→ 使用 AI 功能 → 预扣积分 → AI 生成任务 → 成功：确认扣减 / 失败：退还积分
→ 查看积分流水 → 继续使用或充值

2.2 充值流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端
    participant Backend as 后端
    participant Payment as 支付平台

    User->>Frontend: 选择充值套餐
    Frontend->>Backend: POST /api/v1/recharge/create
    Backend->>Backend: 创建充值订单
    Backend->>Payment: 调用支付接口
    Payment-->>Backend: 返回支付参数
    Backend-->>Frontend: 返回二维码/支付链接
    Frontend-->>User: 展示支付二维码

    User->>Payment: 扫码支付
    Payment->>Backend: 支付回调
    Backend->>Backend: 验证签名
    Backend->>Backend: 更新订单状态
    Backend->>Backend: 增加用户积分
    Backend->>Backend: 记录积分流水
    Backend-->>Payment: 返回成功

    Backend->>Frontend: WebSocket 通知
    Frontend-->>User: 充值成功提示

2.3 消耗流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端
    participant Backend as 后端
    participant AI as AI 服务

    User->>Frontend: 发起生成任务
    Frontend->>Backend: POST /api/v1/generate/image
    Backend->>Backend: 计算所需积分
    Backend->>Backend: 检查余额
    Backend->>Backend: 预扣积分（冻结）
    Backend->>Backend: 创建消耗记录
    Backend->>AI: 调用 AI 生成

    alt 生成成功
        AI-->>Backend: 返回生成结果
        Backend->>Backend: 确认扣减积分
        Backend->>Backend: 更新消耗记录
        Backend-->>Frontend: 返回生成结果
    else 生成失败
        AI-->>Backend: 返回失败
        Backend->>Backend: 退还积分
        Backend->>Backend: 更新消耗记录
        Backend-->>Frontend: 返回失败信息
    end

    Frontend-->>User: 展示结果

---

三、数据模型设计

3.1 核心表关系

users (用户表)
  ├── ai_credits_balance (当前余额)
  ├── total_recharged_amount (累计充值金额)
  ├── total_credits_earned (累计获得积分)
  └── total_credits_consumed (累计消耗积分)

recharge_orders (充值订单表)
  ├── order_no (订单号)
  ├── amount (充值金额)
  ├── credits (获得积分)
  ├── bonus_credits (赠送积分)
  └── payment_status (支付状态)

credit_transactions (积分流水表)
  ├── transaction_type (交易类型)
  ├── amount (变动金额)
  ├── balance_before (变动前余额)
  ├── balance_after (变动后余额)
  └── related_order_id (关联订单)

credit_consumption_logs (消耗记录表)
  ├── feature_type (功能类型)
  ├── credits_consumed (消耗积分)
  ├── task_id (任务ID)
  ├── task_status (任务状态)
  └── resource_id (生成资源ID)

credit_packages (积分套餐表)
  ├── name (套餐名称)
  ├── price (价格)
  ├── credits (积分数量)
  └── bonus_credits (赠送积分)

credit_pricing (定价配置表)
  ├── feature_type (功能类型)
  └── pricing_rules (定价规则 JSON)

3.2 表设计要点

用户表调整

• 移除 subscription_tier、subscription_expires_at
• 新增 ai_credits_balance（当前余额，冗余字段提高查询性能）
• 新增 total_recharged_amount（累计充值金额）
• 新增 total_credits_earned（累计获得积分）
• 新增 total_credits_consumed（累计消耗积分）

积分流水表

• 记录所有积分变动
• 包含变动前后余额快照
• 支持多种交易类型（充值、消耗、退款、赠送等）

消耗记录表

• 详细记录每次 AI 生成任务
• 关联具体的资源 ID
• 支持任务状态追踪（pending、success、failed、refunded）

---

四、积分定价策略

4.1 定价原则

• 透明化：用户清楚知道每个功能消耗多少积分
• 差异化：不同质量、不同模型有不同价格
• 灵活性：支持动态调整定价规则

4.2 定价示例

图片生成

{
  "feature_type": "image_generation",
  "pricing_rules": {
    "base": 10,
    "hd_multiplier": 2,
    "model_multipliers": {
      "dall-e-3": 1.5,
      "stable-diffusion": 1.0
    }
  }
}

计算示例：

• 标清 + DALL-E 3：10 × 1.5 = 15 积分
• 高清 + DALL-E 3：10 × 2 × 1.5 = 30 积分

视频生成

{
  "feature_type": "video_generation",
  "pricing_rules": {
    "per_second": 5,
    "hd_multiplier": 3,
    "resolution_multipliers": {
      "720p": 1.0,
      "1080p": 2.0,
      "4k": 4.0
    }
  }
}

计算示例：

• 5秒 720p 标清：5 × 5 × 1.0 = 25 积分
• 10秒 1080p 高清：10 × 5 × 3 × 2.0 = 300 积分

文字处理

{
  "feature_type": "text_processing",
  "pricing_rules": {
    "per_1000_chars": 2,
    "min_credits": 1
  }
}

计算示例：

• 500 字：1 积分（最低消费）
• 3000 字：6 积分

---

五、充值套餐设计

5.1 套餐示例

套餐名称	价格	基础积分	赠送积分	总积分	性价比
入门套餐	¥9.9	100	0	100	10.1 积分/元
标准套餐	¥29.9	350	50	400	13.4 积分/元
超值套餐	¥49.9	600	100	700	14.0 积分/元 ⭐
豪华套餐	¥99.9	1300	300	1600	16.0 积分/元
至尊套餐	¥199.9	2800	800	3600	18.0 积分/元

5.2 套餐设计原则

• 阶梯定价：充值越多，单价越低
• 赠送激励：大额充值赠送更多积分
• 推荐标记：标记性价比最高的套餐
• 灵活自定义：支持用户自定义充值金额

---

六、技术实现要点

6.1 并发控制

问题：多个请求同时扣减积分，可能导致余额为负。

解决方案：

# 使用数据库行锁
async with self.db.begin():
    user = await self.db.get(User, user_id, with_for_update=True)
    if user.ai_credits_balance < amount:
        raise InsufficientCreditsError()
    user.ai_credits_balance -= amount

6.2 积分冻结机制

问题：AI 生成任务耗时较长，如何防止重复扣款？

解决方案：

1. 任务开始时预扣积分（状态：pending）
2. 任务成功：确认扣减（状态：success）
3. 任务失败：退还积分（状态：refunded）

6.3 对账机制

问题：如何确保积分流水与余额一致？

解决方案：

# 定时任务：每日对账
async def reconcile_credits(user_id: int):
    user = await get_user(user_id)

    # 计算流水总和
    transactions = await get_all_transactions(user_id)
    calculated_balance = sum(t.amount for t in transactions)

    # 对比实际余额
    if calculated_balance != user.ai_credits_balance:
        # 记录差异，发送告警
        log_discrepancy(user_id, calculated_balance, user.ai_credits_balance)

6.4 支付回调幂等性

问题：支付平台可能重复发送回调。

解决方案：

async def handle_payment_callback(order_no: str):
    order = await get_order(order_no)

    # 检查订单状态
    if order.payment_status == 'paid':
        return {'success': True, 'message': '订单已支付'}

    # 使用事务确保原子性
    async with db.begin():
        order.payment_status = 'paid'
        await add_credits(order.user_id, order.credits)

---

七、安全考虑

7.1 支付安全

• 验证支付回调签名
• 记录所有回调日志
• 订单金额二次验证
• 防止订单篡改

7.2 积分安全

• 余额不能为负
• 所有操作记录流水
• 敏感操作需要二次验证
• 异常变动告警

7.3 防刷机制

• 限制单用户充值频率
• 限制单用户消耗频率
• 异常行为检测
• IP 黑名单

---

八、运营支持

8.1 积分赠送

支持多种赠送场景：

• 新用户注册赠送
• 邀请好友奖励
• 活动赠送
• 补偿赠送
• 管理员手动调整

8.2 数据统计

• 用户充值统计
• 积分消耗统计
• 功能使用统计
• 收入报表
• 用户留存分析

8.3 价格调整

• 支持动态调整定价规则
• 历史价格记录
• 价格变更通知

---

九、相关文档

• 用户管理服务
• 算力积分管理服务
• 充值管理服务
• 支付服务

---

文档版本：v1.0
创建时间：2025-01-14