核心设计：不做余额字段#

最直接的做法是在用户表放一个 balance，扣费时 balance = balance - cost。这个方案在单一余额、无过期、无并发的场景下够用，但一旦出现“每日免费额度当天过期”“VIP 月度额度按周期过期”“管理员赠送不过期”并存，单字段就表达不了。

系统的选择是：只做额度批次和流水，余额在查询时聚合计算。

• 每一次发放都是一行记录，带 granted_credits 和 remaining_credits；
• 扣费就是原地减少 remaining_credits，减到 0 把状态改成 EXHAUSTED；
• 过期不是删除，而是把状态改成 EXPIRED，同时写一条负数流水；
• 所有资金变动都追加到一张只增不改的流水表。

好处是任何时刻的余额都能从批次表推导出来，流水可以独立复算；代价是每次读余额都要做聚合查询，后面会看到它对性能的影响。

数据模型#

1
UNIQUE INDEX uq_free_daily_credit_grants_user_date
2
  ON free_daily_credit_grants(user_id, local_date);
3

4
CREATE INDEX idx_free_daily_credit_grants_user_status_expire
5
  ON free_daily_credit_grants(user_id, status, expires_at);
6

7
CREATE INDEX idx_free_daily_credit_grants_status_expire
8
  ON free_daily_credit_grants(status, expires_at);

1
CREATE UNIQUE INDEX uq_vip_credit_grants_subscription_period
2
  ON vip_credit_grants(subscription_id, grant_period_start_at);

余额如何计算#

可用余额等于三张批次表的聚合并求和：

1
SELECT COALESCE(SUM(remaining_credits), 0)
2
FROM free_daily_credit_grants
3
WHERE user_id = ?
4
  AND status = 'ACTIVE'
5
  AND remaining_credits > 0
6
  AND expires_at > now();
7

8
SELECT COALESCE(SUM(remaining_credits), 0)
9
FROM manual_credit_grants
10
WHERE user_id = ?
11
  AND status = 'ACTIVE'
12
  AND remaining_credits > 0;
13

14
SELECT COALESCE(SUM(remaining_credits), 0)
15
FROM vip_credit_grants
16
WHERE user_id = ?
17
  AND status = 'ACTIVE'
18
  AND remaining_credits > 0
19
  AND expires_at > now();

系统没有缓存、没有物化余额，所以直接改批次行余额会立刻变化。代价是每次读余额固定 3 条 SQL；一次扣费前后各算一次，加上预检，一次扣费会算三遍余额。

status = 'ACTIVE' 和 expires_at > now() 是双重保险：定时任务会把过期批次标成 EXPIRED，但即使任务延迟，查询也不会把过期额度算进来。

索引 (user_id, status, expires_at) 正好覆盖过滤条件，remaining_credits > 0 是回表后的过滤。

一次扣费在事务里做了什么#

扣费方法是声明式事务，传播级别为默认的 REQUIRED。聊天链路本身没有事务，所以扣费是一个独立事务，和保存回复不在同一个事务里。

事务内的顺序：

1. 补发当天免费额度：先用 SELECT ... FOR UPDATE 查当天是否已有批次；没有则插入；并发插入冲突时由唯一约束兜底。

2. 计算扣前余额：执行三张表的聚合。

3. 锁用户行：SELECT ... FROM users WHERE id = ? FOR UPDATE。

4. 按顺序扣三个额度桶，每桶都先对候选行加行锁：

   • 免费额度：ORDER BY expires_at ASC, granted_at ASC
   • 管理员赠送：ORDER BY granted_at ASC
   • VIP 额度：ORDER BY expires_at ASC, granted_at ASC

   固定顺序是免费、赠送、VIP，因为免费额度当天过期，要先消耗过期最快的。

5. 累加 users.credit_spent_total。

6. 计算扣后余额：再次执行三张表聚合。

7. 插入一条流水，写入 token、单价快照、扣减明细和 balance_after。

一次扣费大约 12 到 20 条 SQL。一条用户消息可能触发 3 到 5 次模型调用，对应 50 到 100 条 SQL，这是整个系统最主要的数据库压力来源。

并发控制#

系统没有使用乐观锁，全部依赖数据库悲观锁。

• 用户行锁是同一用户并发扣费的串行化点。
• 额度行锁保证同一批次不会被两个事务同时扣减。
• 锁顺序在所有扣费路径上保持一致，正常情况下不会死锁。

数据库隔离级别是 PostgreSQL 默认的 READ COMMITTED。第二个事务在等待 FOR UPDATE 期间，第一个事务提交后会重新检查行是否仍满足 remaining_credits > 0，已扣完的行会被跳过。因此不会出现两个请求各扣一遍同一份额度。

每个批次的扣减量是 min(remaining, remainingCost)，扣到 0 就停止，不会把单行扣成负数。

余额不足的两种处理#

1. 如果事务开始时总余额已经小于等于 0，直接返回 402 INSUFFICIENT_CREDITS，不产生任何扣减。
2. 如果余额大于 0 但不足以支付本次费用，不报错，而是能扣多少扣多少，剩余部分记为减免。

流水里会记录：

• requestedCost：本次应收；
• chargedCost：实际扣减；
• waivedCost：减免；
• chargeMode：FULL_CHARGE 或 CAP_TO_ZERO_LAST_USE。

也就是说，系统没有“预留”或“冻结”机制，预检只判断余额是否大于 0，所以最后一笔超额是设计允许的行为。实际日志中能看到“应收 2114、实收 645、减免 1469”的记录，用户回复照常返回，余额归零，下一条消息才被拦截。

额度发放与过期#

计费输入：token 从哪里来#

• 非流式调用：直接从响应体的 usage 字段读取。
• 流式调用：请求里带 stream_options.include_usage = true，模型服务会在最后一个 chunk 返回 usage，客户端边收流边保存最后拿到的值。
• 三个 token 字段都会做非负清洗，null 按 0 处理。
• 如果模型服务完全不返回 usage（部分兼容网关会忽略 include_usage），这次调用会跳过扣费，日志里记录 usageMissing=true。这是目前唯一的系统性漏计费入口。

单价换算规则：

1
cost = ceil(input     × inputRate     / 1000)
2
     + ceil(output    × outputRate    / 1000)
3
     + ceil(reasoning × reasoningRate / 1000)

rate 的单位是 micro-credit 每 1000 token。默认 1 积分每 1000 token 对应 rate = 1000。三段分别向上取整后相加，所以每段至少产生 1 micro-credit。

事务边界与失败语义#

模型调用、保存回复、扣费是三段独立事务：

1. 调用模型，不占数据库事务；
2. 保存 assistant 消息，独立事务；
3. 扣费，独立事务。

由此产生几种行为：

• 扣费失败但不是 402（例如数据库异常）：回复已经保存、token 已经消耗，但没有流水，系统不会补偿。
• 扣费返回 402：调用方显式删除刚保存的 assistant 消息，再把 402 抛给前端。这是唯一的补偿动作。
• 扣费事务内部：额度扣减、用户统计、流水插入在同一事务，流水写失败会整体回滚，不会出现“扣了额度却没记账”。

进程在模型调用完成、扣费之前崩溃，这次调用就是免费的，回复可能已保存也可能没有。批次表是唯一事实源，崩溃不会造成余额漂移，定时任务会在下一轮补发或过期。

配置与缓存#

• 配置只在表为空时用环境变量播种一次。已有数据后会完全忽略环境变量。
• 读路径走 JVM 内存缓存，后台更新后刷新数据库并清除本实例缓存。
• 多实例部署时，其他实例不会失效，会继续使用旧单价，直到重启。
• 流水里保存了每笔的单价快照，所以改价只影响之后的新扣费，历史账目仍可复算。

已知问题#

按影响排序：

1. 推理 token 重复计费。多数模型服务的 completion_tokens 已经包含 reasoning_tokens，代码又在输出和推理上各算一次。只要推理单价大于 0，推理部分就会被收两次。正确做法是把推理单价配置为 0，或者把输出单价定义为“总 completion 单价”。
2. 免费额度流水的 balance_after 漏算管理员赠送。免费额度发放和过期时只累加免费与 VIP 额度，没有加管理员赠送。有赠送的用户会看到流水里的“扣后余额”低于真实余额；账户接口用的是完整三桶求和，所以展示余额是对的，但对账时会对不上。
3. 用户表三个积分列是死字段。从未写入，任何直接查用户表的报表或运维脚本都会得到错误余额。
4. 多实例缓存不失效。后台改价后其他实例继续用旧价，属于静默不一致。
5. 定时任务没有分布式锁，且是全表扫描加单事务循环。用户量增长后既慢又容易互相踩，冲突时可能整轮回滚。
6. 流水幂等完全依赖调用方。(source_type, source_ref_id) 没有唯一约束，任何重试路径都可能产生重复扣费记录。
7. 删除用户会级联删除流水。user_id 是 ON DELETE CASCADE，删用户会丢掉全部计费历史，对账和审计场景要特别注意。
8. 时间类型不统一。多数表使用无时区的 TIMESTAMP，部分新表使用 TIMESTAMPTZ，依赖 JVM 或连接时区设置，跨时区部署时容易出现偏移。

排查用的 SQL#

某个用户的完整账本：

1
SELECT source_type, billing_channel, model_name,
2
       token_input, token_output, token_reasoning,
3
       credits_delta, balance_after, meta_json, created_at
4
FROM credit_ledger_entries
5
WHERE user_id = '<uuid>'
6
ORDER BY created_at DESC
7
LIMIT 50;

某次会话的扣费：

1
SELECT source_type, credits_delta, meta_json
2
FROM credit_ledger_entries
3
WHERE session_id = '<uuid>'
4
ORDER BY created_at;

余额拆分（结果单位是 micro-credit，除以 1000 才是展示值）：

1
SELECT
2
  (SELECT COALESCE(SUM(remaining_credits), 0) FROM free_daily_credit_grants
3
     WHERE user_id = $1 AND status = 'ACTIVE'
4
       AND remaining_credits > 0 AND expires_at > now()) AS free_micro,
5
  (SELECT COALESCE(SUM(remaining_credits), 0) FROM manual_credit_grants
6
     WHERE user_id = $1 AND status = 'ACTIVE'
7
       AND remaining_credits > 0) AS manual_micro,
8
  (SELECT COALESCE(SUM(remaining_credits), 0) FROM vip_credit_grants
9
     WHERE user_id = $1 AND status = 'ACTIVE'
10
       AND remaining_credits > 0 AND expires_at > now()) AS vip_micro;

用流水和余额对账：

1
SELECT COALESCE(SUM(credits_delta), 0) AS ledger_sum_micro
2
FROM credit_ledger_entries
3
WHERE user_id = '<uuid>';

正常情况下，流水求和应该等于当前可用余额。对不上时优先检查：

• 是否存在状态非 ACTIVE 但 remaining_credits 仍大于 0 的脏数据；
• 是否有绕过流水直接更新批次表的操作；
• balance_after 的口径问题只影响单行快照，不影响 credits_delta 求和。

容量与优化方向#

当前的查询特征：

• 每次读余额固定 3 条聚合；
• 一次扣费约 12 到 20 条 SQL，包含 3 次余额聚合、1 次用户行锁、最多 3 次额度行锁查询和若干逐行更新；
• 额度扣减是逐行 UPDATE，没有批量更新。用户积累多个未用完的小批次时，单次扣费会更新多行；
• 每日扫描是全表用户加每人至少 2 条 SQL，分钟级频率，十万用户规模后会明显吃数据库；
• 每条消息 3 到 5 次模型调用，每次都完整走一遍扣费，是写放大的主要来源。

如果要优化，优先级大致是：

1. 合并扣费流程里的多次余额聚合；
2. 在用户表增加物化余额列，用触发器或事务内维护；
3. 定时任务改成游标分页加单用户事务；
4. 引入分布式调度锁，避免多实例重复扫描。

这套设计的核心取舍很明确：用“批次 + 流水”换取可追溯和多种过期策略，代价是读余额和扣费路径上的聚合开销。对账、审计和运营调整都因此变得简单，但性能优化必须围绕这些聚合查询来做。