积分系统
积分模块(src/modules/credits/service.ts)提供 grant、consume、revoke、getBalance、getHistory 等方法。
积分发放
| 场景 | 触发条件 | 配置 |
|---|---|---|
| 注册赠送 | 注册完成后自动发放 | 管理后台 Settings:initial_credits_enabled、initial_credits_amount、initial_credits_valid_days(0 = 永不过期)、initial_credits_description |
| 支付发放 | 订单变为 PAID | src/config/pricing.ts 中商品的 credits + creditsValidDays;订阅类按周期结束时间过期 |
| 手动发放 | 管理后台 → Credits | 以 GIFT / REWARD 场景发放 |
积分消耗(FIFO)
- 最先过期的积分最先消耗(按
expiresAt升序,永不过期的排最后) - 消耗在数据库事务中执行,分批处理(每批最多 1000 积分)
- 只有有效积分计入余额:状态 ACTIVE、未过期、未删除
import { consume } from '@/modules/credits/service';
const result = await consume({
userId,
credits: 10,
scene: 'ai_generation',
description: 'Generate image',
});
// 余额不足时 result.success === false过期机制
- 每笔发放可带
expiresAt(null= 永不过期) - 一次性购买:
当前时间 + creditsValidDays - 订阅:在
currentPeriodEnd过期——续费时发放新一批积分
记录与审计
每笔发放/消耗都是 credit 表中的一行,包含 transactionType(GRANT/CONSUME)、transactionScene、remainingCredits、expiresAt 以及 consumedDetail JSON 明细——余额与历史完全可审计。