docs/v1.0/.archive/server/credit-system-plan.md

算力积分体系实施计划

文档版本：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 表（积分赠送记录）

数据迁移

-- 迁移现有用户数据
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 数据分析

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

---

六、相关文档

• 算力积分体系设计方案
• 用户管理服务
• 算力积分管理服务
• 充值管理服务
• 支付服务

---

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