# 算力积分体系实施计划

> **文档版本**：v1.0  
> **创建时间**：2025-01-14  
> **预计工期**：5-7 个工作日

---

## 一、实施概述

### 1.1 目标

将现有的订阅制改造为纯算力积分体系，实现用户充值、积分消耗、流水记录等完整功能。

### 1.2 涉及模块

- 用户管理服务（调整）
- 算力积分管理服务（新增）
- 充值管理服务（新增）
- 支付服务（新增）
- 数据库表结构（调整 + 新增）
- API 接口（新增）
- 前端页面（新增）

---

## 二、实施步骤

### 阶段一：数据库设计（1 天）

#### 任务清单

- [ ] 调整 `users` 表结构
  - 移除 `subscription_tier`、`subscription_expires_at`
  - 新增 `ai_credits_balance`、`total_recharged_amount` 等字段
- [ ] 创建 `recharge_orders` 表（充值订单）
- [ ] 创建 `credit_transactions` 表（积分流水）
- [ ] 创建 `credit_consumption_logs` 表（消耗记录）
- [ ] 创建 `credit_packages` 表（积分套餐）
- [ ] 创建 `credit_pricing` 表（定价配置）
- [ ] 创建 `payment_callbacks` 表（支付回调日志）
- [ ] 创建 `credit_gifts` 表（积分赠送记录）

#### 数据迁移

```sql
-- 迁移现有用户数据
UPDATE users SET
  ai_credits_balance = ai_credits_remaining,
  total_credits_earned = ai_credits_total,
  total_credits_consumed = ai_credits_total - ai_credits_remaining,
  total_recharged_amount = 0.00;

-- 删除旧字段（谨慎操作）
ALTER TABLE users DROP COLUMN subscription_tier;
ALTER TABLE users DROP COLUMN subscription_expires_at;
ALTER TABLE users DROP COLUMN ai_credits_remaining;
ALTER TABLE users DROP COLUMN ai_credits_total;
```

---

### 阶段二：后端服务开发（3 天）

#### Day 1: 基础服务

- [ ] 创建 `CreditService` 类
  - 积分查询
  - 积分增加
  - 积分消耗
  - 积分退还
  - 积分流水查询

- [ ] 创建 `CreditRepository` 类
  - 数据库操作封装

- [ ] 创建数据模型
  - `CreditTransaction`
  - `CreditConsumptionLog`
  - `CreditPackage`
  - `CreditPricing`

#### Day 2: 充值服务

- [ ] 创建 `RechargeService` 类
  - 创建充值订单
  - 订单查询
  - 订单取消
  - 订单超时处理

- [ ] 创建 `RechargeRepository` 类

- [ ] 创建数据模型
  - `RechargeOrder`
  - `PaymentCallback`

#### Day 3: 支付集成

- [ ] 创建 `PaymentService` 类
  - 统一支付接口

- [ ] 集成微信支付
  - Native 扫码支付
  - 支付回调处理
  - 签名验证

- [ ] 集成支付宝支付
  - 扫码支付
  - 支付回调处理
  - 签名验证

- [ ] 支付回调处理
  - 验证签名
  - 更新订单状态
  - 增加用户积分
  - 记录回调日志

---

### 阶段三：API 接口开发（1 天）

#### 积分相关接口

- [ ] `GET /api/v1/credits/balance` - 查询积分余额
- [ ] `GET /api/v1/credits/transactions` - 查询积分流水
- [ ] `GET /api/v1/credits/consumption` - 查询消耗记录
- [ ] `POST /api/v1/credits/calculate` - 计算所需积分
- [ ] `GET /api/v1/credits/packages` - 获取充值套餐

#### 充值相关接口

- [ ] `POST /api/v1/recharge/create` - 创建充值订单
- [ ] `GET /api/v1/recharge/orders/{order_id}` - 查询订单详情
- [ ] `GET /api/v1/recharge/orders` - 查询订单列表
- [ ] `POST /api/v1/recharge/orders/{order_id}/cancel` - 取消订单

#### 支付回调接口

- [ ] `POST /api/v1/recharge/callback/wechat` - 微信支付回调
- [ ] `POST /api/v1/recharge/callback/alipay` - 支付宝支付回调

#### 用户接口调整

- [ ] `GET /api/v1/users/me` - 调整返回字段
- [ ] `GET /api/v1/users/me/credits` - 查询积分信息

---

### 阶段四：前端开发（2 天）

#### Day 1: 充值页面

- [ ] 充值套餐展示
  - 套餐卡片设计
  - 推荐标记
  - 性价比展示

- [ ] 支付流程
  - 选择支付方式
  - 展示支付二维码
  - 支付状态轮询
  - 支付成功提示

- [ ] 自定义充值
  - 输入金额
  - 计算获得积分

#### Day 2: 积分管理页面

- [ ] 积分余额展示
  - 当前余额
  - 累计充值
  - 累计消耗

- [ ] 积分流水
  - 流水列表
  - 筛选功能
  - 分页加载

- [ ] 消耗记录
  - 消耗列表
  - 关联资源
  - 任务状态

- [ ] 充值记录
  - 订单列表
  - 订单详情
  - 取消订单

---

### 阶段五：测试与优化（1 天）

#### 功能测试

- [ ] 充值流程测试
  - 微信支付
  - 支付宝支付
  - 支付回调
  - 积分到账

- [ ] 消耗流程测试
  - 积分预扣
  - 任务成功确认
  - 任务失败退款

- [ ] 并发测试
  - 多个请求同时扣款
  - 余额不为负

- [ ] 异常测试
  - 余额不足
  - 订单超时
  - 支付失败
  - 重复回调

#### 性能优化

- [ ] 数据库索引优化
- [ ] 查询性能优化
- [ ] 缓存策略

#### 安全测试

- [ ] 支付签名验证
- [ ] 订单金额验证
- [ ] 防重放攻击
- [ ] SQL 注入测试

---

## 三、风险控制

### 3.1 数据迁移风险

**风险**：现有用户数据迁移可能出错。

**应对**：

- 先在测试环境验证迁移脚本
- 生产环境迁移前备份数据
- 迁移后进行数据校验

### 3.2 支付安全风险

**风险**：支付回调可能被伪造。

**应对**：

- 严格验证签名
- 记录所有回调日志
- 订单金额二次验证

### 3.3 并发扣款风险

**风险**：多个请求同时扣款导致余额为负。

**应对**：

- 使用数据库行锁
- 事务保证原子性
- 余额检查

### 3.4 支付回调延迟

**风险**：支付成功但回调延迟，用户看不到积分。

**应对**：

- 前端轮询订单状态
- 提供手动刷新按钮
- 后台定时同步订单状态

---

## 四、上线计划

### 4.1 灰度发布

1. **内测阶段**（1-2 天）
   - 开放给内部测试用户
   - 小额充值测试
   - 收集反馈

2. **小范围公测**（2-3 天）
   - 开放给部分用户
   - 监控系统稳定性
   - 优化用户体验

3. **全量发布**
   - 全部用户可用
   - 持续监控
   - 快速响应问题

### 4.2 回滚方案

如果出现严重问题，准备回滚方案：

- 数据库备份恢复
- 代码版本回退
- 用户数据补偿

---

## 五、后续优化

### 5.1 功能增强

- [ ] 积分有效期管理
- [ ] 积分转赠功能
- [ ] 积分兑换礼品
- [ ] 会员等级体系
- [ ] 积分抽奖活动

### 5.2 运营支持

- [ ] 充值优惠活动
- [ ] 新用户赠送积分
- [ ] 邀请好友奖励
- [ ] 每日签到送积分
- [ ] 节日活动

### 5.3 数据分析

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

---

## 六、相关文档

- [算力积分体系设计方案](../方案/算力积分体系设计.md)
- [用户管理服务](../需求/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  
**预计工期**：5-7 个工作日