SuperAPI AI 工具集

billing-stripe

编程与开发

查看项目

更新于 10-16 07:29

技能介绍

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 服务与项目自身的服务层结构,需按上述规则集成。