Next.js 订阅计费：真正能用的 Webhook 契约

多数订阅计费教程止步于顺利路径：创建结账会话、跳转、结束。生产级计费恰恰活在那些被跳过的地方。

Webhook 才是真相来源

浏览器跳转会骗人：用户关掉标签页、支付商重试、测试触发两次。数据库必须是唯一真相来源，且只由已验签的 Webhook 更新。

验签契约值得写清楚，因为写反了就是安全漏洞：

• 签名缺失、无效或格式损坏 → 抛错，路由返回 400。
• 合法已验签但无需处理的事件 → 返回空列表，路由返回 200 并标记 ignored。
• 已见过的事件 id → 写库前直接跳过。

本仓库每个适配器都遵守这份契约。早期版本在验签失败时也返回空列表，等于用 200 确认了伪造请求，别再退回去。

权限在服务端，不在界面

永远不要信任客户端。每个受保护路由都从会话或数据库读套餐；套餐未激活时 AI 接口返回 402——哪怕有人在 devtools 里改了 DOM。

预算和配额是两件事

订阅状态不等于用量限制。AI 接口另有每用户每日配额（AI_MESSAGES_PER_DAY，默认 50），由 Supabase RPC 或本地 SQLite 的 ai_usage 表扣减。用尽返回 429，带 X-AI-Quota-Reset 与按真实剩余秒数计算的 Retry-After，不是写死的 86400。

离线也能测

验证这份契约不需要六个沙箱账户。仓库提供离线验签探测（npm run probe:webhook），向运行中的服务发送合法、缺失、篡改、损坏四种请求并断言状态码。上线前仍要跑沙箱端到端，但安全不变量可以在 CI 里守住。四层测试策略见 docs/payment-testing.md。