积分账本
积分如何以只追加账本加余额快照的方式存储,以及冻结、扣除与退还如何让计量计费保持准确。
积分是产品为 AI 任务等计量型工作计费的单位。每一次变动都是只追加账本中的一条记录,余额是一份可以从账本重建的快照。配置积分见按积分计费。
两个余额
每个用户有两个余额。
| 余额 | 含义 |
|---|---|
| 可用 | 用户当前可以花费的积分 |
| 冻结 | 为已开始但尚未结束的工作而冻结的积分 |
每个用户有一行快照,同时保存这两个余额,以及累计购买和累计使用两个总数。新用户从零开始,除非在 /admin/config/auth 开启了注册奖励。
每次变动都是一条账本记录
所有写入都经过同一个函数,对每条记录它会:
- 拒绝非正数的金额。
- 把这条记录的变动应用到可用和冻结余额上。
- 如果任一余额会变为负数,拒绝写入。
- 追加这条记录,包含变动量和变动后的余额。
- 更新快照:发放和购买增加累计购买,扣除增加累计使用。
- 写入一条审计日志。
记录不会修改或删除,所以账本保留了用户积分的完整历史。
| 操作 | 记录类型 | 可用 | 冻结 |
|---|---|---|---|
| 管理员发放 | grant | +amount | 0 |
注册奖励(来源 signup.bonus) | grant | +amount | 0 |
| 管理员扣减 | adjustment | -amount | 0 |
| 购买(方案积分) | purchase | +amount | 0 |
| 冻结 | reserve | -amount | +amount |
| 扣除 | capture | 0 | -amount |
| 退还 | refund | +amount | -amount |
先冻结,再扣除或退还
计量型工作先冻结价格,再扣除或退还:
| 冻结状态 | 何时进入 | 账本效果 |
|---|---|---|
reserved | 工作开始,且可用余额足以覆盖价格 | 可用转为冻结 |
captured | 工作成功 | 冻结部分被消耗 |
refunded | 工作失败 | 冻结部分退回可用 |
一笔冻结只会结算一次。对已结算、不存在或属于其他用户的冻结执行扣除或退还都会抛错,所以重试不会重复扣费。可用余额不足时工作不会开始,用户会跳转到 /system/insufficient-credits。
AI 工作如何使用它
- 任务在调用服务商之前冻结解析出的渠道价格,成功时扣除,失败时退还。异步任务在最终状态经 Webhook 或轮询到达时结算。
- 对话在调用模型前冻结一个预估金额。流结束后退还这笔预冻结,按实际 Token 用量计算的金额重新冻结并立即扣除。扣除失败则退还。
价格如何解析,见 AI 渠道、场景与任务生命周期。
注册奖励每个用户只发放一次
注册奖励开启时,Better Auth 的用户创建钩子为每个新用户发放,无论通过哪种方式注册。账本记录 id 按用户固定(credit_entry_signup_<userId>),重复调用会发现已有记录,并发的重复写入会在余额变动前失败。发放失败只记日志,不会阻断注册。开关和数量是后台设置,不是环境变量,见按积分计费。
方案积分每个订单只发放一次
已支付订单结算时,方案附带的积分以 purchase 记录的形式加入,来源为 billing.order.<orderId>。如果同一用户已有该来源的记录,就跳过发放,因此 Webhook 和回调结算同一订单时积分只会加一次。见支付生命周期。
重算与修复
账本是事实来源,所以快照随时可以核对。重算会累加每条记录的变动量,并报告是否与快照一致。用户可以对自己的余额执行这项只读检查。修复需要 credits.write 权限,它把重算结果写回快照、重建累计总数,并在审计日志中记录修复前后的值。
尚未实现过期
schema 接受 expire 记录类型,后台账本也可以按它筛选,但没有任何代码写入 expire 记录,发放也不带过期日期。积分不会过期。要加入过期机制,需要为每次发放保存过期时间(两种方言下的 schema 变更),并通过同一个账本函数写入 expire 记录。