# 算力积分体系设计方案

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

---

## 一、方案概述

### 1.1 背景

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

### 1.2 核心目标

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

---

## 二、业务流程

### 2.1 完整业务链路

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

### 2.2 充值流程

```mermaid
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 消耗流程

```mermaid
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 定价示例

#### 图片生成

```json
{
  "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 积分

#### 视频生成

```json
{
  "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 积分

#### 文字处理

```json
{
  "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 并发控制

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

**解决方案**：

```python
# 使用数据库行锁
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 对账机制

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

**解决方案**：

```python
# 定时任务：每日对账
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 支付回调幂等性

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

**解决方案**：

```python
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 价格调整

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

---

## 九、相关文档

- [用户管理服务](../需求/backend/04-services/user-service.md)
- [算力积分管理服务](../需求/backend/04-services/credit-service.md)
- [充值管理服务](../需求/backend/04-services/recharge-service.md)
- [支付服务](../需求/backend/04-services/payment-service.md)

---

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