Billing & Credits (Stripe) 是 vstorm-co/full-stack-ai-agent-template 中的计费模块,代码位于 backend/app/services/billing/。该模块把 Stripe 计费能力集中在一个较厚的服务层中,路由不直接接触 Stripe,所有调用都经过 BillingService(facade.py 中的门面,并从 init.py 重新导出)。
一、用途 用于在 AI Agent 应用中处理 Stripe 计费相关事务,包括订阅、套餐/价格、客户门户、积分、用量计量、发票和 Webhook 事件。当需要变更套餐、管理订阅、发放或扣减积分、记录 token 用量时使用。
二、主要能力与文件职责
- facade.py:BillingService,路由和 worker 唯一导入的入口。
- checkout_service.py:结账会话(座位数可配置)。
- subscription_service.py:订阅 CRUD、变更套餐、取消/重新激活。
- credit_service.py:积分账本与用量聚合。
- stripe_client.py:Stripe API 的薄封装。
- webhook_handler.py 与 handlers/:事件处理(customer / invoice / payment / subscription)。
- pricing.py:静态套餐/价格数据。
- exceptions.py:计费领域错误(扩展 core/exceptions)。
三、数据模型 plan / price 镜像 Stripe 产品;subscription 每个组织一条;stripe_event 是幂等日志;credit_transaction 是不可变账本;usage_event 记录每条消息的 token 消耗,并汇总到 mv_usage_daily 物化视图。
四、常见任务
- 处理新的 Webhook 事件:在 services/billing/handlers/ 下新增 handler 模块或函数,从 webhook_handler.py 分发,并记录到 stripe_event 以实现幂等(若已处理则跳过)。必须验证签名,绝不信任未签名的负载。
- 新增/调整套餐:更新 pricing.py 及对应的 Stripe 产品/价格;sync-stripe-plans 命令({{ cookiecutter.project_slug }} cmd sync-stripe-plans)将 Stripe 镜像到本地 plan/price 表。
- 充值/发放积分:通过 credit_service,使每次变更都写入 credit_transaction 行(发放、购买、扣减),保持余额一致。绝不直接修改余额。
- 计量用量:写入 usage_event(输入/输出/缓存 token、模型、提供商、扣减积分)——每日汇总和仪表盘图表读取 mv_usage_daily(由后台任务刷新)。
五、本地测试 使用 Stripe CLI 转发 Webhook:stripe listen --forward-to localhost:8000/api/v1/billing/webhook。使用 Stripe 测试密钥/测试模式。Webhook 端点不鉴权,但会验证签名。
六、规则
- 路由调用 BillingService;绝不从路由直接导入 stripe_client 或子服务。
- 每个 Webhook 通过 stripe_event 实现幂等——重复投递必须是无操作。
- 积分变更始终经过账本;余额是派生值,不是可覆盖的权威状态。
- Stripe 密钥保存在 settings / .env 中,绝不内联。
七、适用场景与限制 适用于需要 Stripe 订阅计费、积分账本和用量计量的 AI Agent 全栈项目。限制方面:资料未提供具体收费、价格、平台支持范围或效果数据;该模块依赖 Stripe 服务与项目自身的服务层结构,需按上述规则集成。