到账与余额

为什么 Stripe 服务不能直接改余额，以及它和 balance 服务的职责分工。

Stripe 服务真正影响产品运行时的地方，不是在 AI 调用前 gating，而是在“到账动作怎么收口”。

为什么不能直接改余额

如果 Stripe 服务自己直接去改余额表，会很快出现这些问题：

充值单状态和余额变动不同步
ledger 流水可能缺失或重复
后续排障时找不到统一到账入口

所以更稳定的方式是：

Stripe 服务只判断“支付是否成功”，真正到账统一走 balance.finishTopup()。

它和 balance 的关系

可以先这么理解：

balance：钱包、充值单、流水
payment.stripe：Checkout、webhook、支付同步

所以两个服务不是互相替代，而是前后相接。

一个最常见的完整场景

先创建 topup 并发起支付

const topup = await user.service("balance").action("topups/create").invoke({
  amount: 500,
});

const checkout = await user.service("payment.stripe").action("checkout/create").invoke({
  topup_id: topup.topup_id,
});

支付成功后自动到账

当 Stripe 发送 checkout.session.completed 到 webhook 后，服务会自动：

找到对应 payment 记录
找到对应 topup
调 balance.finishTopup()
把 payment 标记成 paid

常见误解

Stripe 服务不是钱包服务

它不维护余额主表，也不维护 ledger。

到账越统一越好

只要还有多个地方可以直接改余额，后面排障和对账都会变得很麻烦。

town 只适合做归因，不适合做钱包归属

如果你想记录“这笔充值最初来自哪个 town 页面”，更适合写在 metadata 里，而不是拆成多份钱包。

目录