用途：帮助开发者端到端实现订阅计费，包括方案选择界面、Stripe Checkout、Webhook 生命周期处理、按方案的访问控制、试用期和取消。不涉及 Stripe 账户设置，假定密钥已存在且产品/价格目录已配置。
主要能力与模式：一是以自有数据库作为访问门禁，通过 Webhook 将订阅状态同步到数据库，避免每次请求调用 Stripe。二是创建 Checkout Session，按用户复用 Stripe Customer，并在 Customer 和订阅上附加 userId 元数据。三是只处理关键 Webhook 事件：checkout.session.completed、customer.subscription.updated、customer.subscription.deleted、invoice.payment_failed、invoice.payment_succeeded，其余可忽略。四是 Webhook 需验证签名、用 event.id 做幂等去重，且即使处理异常也返回 200，以免 Stripe 长期重试。五是处理试用转付费边界，如无支付方式试用结束可能变为 incomplete_expired，而非 past_due。六是按功能而非方案名做权限控制。七是取消采用期末取消（cancel_at_period_end），并可用 Stripe Billing Portal 自助管理。
使用方式：产出 api/billing.ts、api/webhooks/stripe.ts、lib/subscription.ts、SubscriptionGate.tsx 等文件，并在注释中标注 past_due 宽限期决策、unix 时间戳转 Date、billing_reason 判断和幂等与 200 返回原因。
适用场景：需要为 SaaS 应用接入 Stripe 订阅计费的团队。
限制：仅以 Stripe 为默认示例，未提供其他计费商的完整实现；不包含 Stripe 账户与价格目录设置；具体界面与产品细节暂未提供。