技能介绍

订阅计费从来不是 stripe.charges.create 一行代码能解决的。一旦引入试用期、升降级按比例折算（proration）、按量计费，Webhook 又会因 500 重试而重复投递——状态机、幂等、防薅，踩坑成本极高。

核心能力

订阅生命周期管理：创建、升级、降级、取消、暂停，覆盖 trialing / active / past_due / canceled / cancel_pending / paused / unpaid 全部状态
试用与转化追踪：数据库记录 hasHadTrial: true，防止反复试用薅羊毛
按比例折算：升降级前通过 Stripe API 预览 proration，确认前先向用户展示金额
按量 / 按席位计费：metered pricing 的用量上报与结算
幂等 Webhook 处理器：签名校验 + 幂等表，重复投递只处理一次
客户门户与发票：自助管理订阅、生成发票并获取 PDF

关键实现路径

文档针对 Next.js App Router、Express、Django 三种技术栈给出实现范式：创建 Checkout Session → 处理订阅生命周期变更 → 校验 Stripe-Signature 后写入幂等表 → 再更新数据库。更新前永远从 Stripe API 重新拉取数据，不直接信任事件 payload。

适用边界与注意点

Webhook 投递顺序不保证，数据库更新前必须回查 Stripe API
Checkout 必须传 userId 到 metadata，否则订阅无法关联用户
客户门户功能需在 Stripe 后台 Billing → Customer portal 显式开启
简诗 AI 安全边界：不自动安装依赖、修改系统权限、创建持久化任务；涉及付款、部署等外部写入前需展示目标与影响并取得明确确认；凭据只用于指定官方服务，不回显、不记录、不转发