端到端接通的 Stripe 计费

VibeShip 用 NextAuth 管理账号、用 Stripe 管理付费订阅、用 Cloudflare D1 保存会话与订阅状态。定价页是示例产品界面：Starter $0、Pro $39/月、Scale $99/月 是用模板搭建的产品示例套餐，不是模板本身的授权价格。

Checkout 是服务端路由，不是客户端价格表单。套餐由服务端 plan id 决定；客户端不提交金额、币种或已支付标记。客户门户是独立路由，登录用户可以在不找员工的情况下变更或取消订阅。

付费状态的权威来源是 webhook。跳转到成功页不等于付款成功；只有验签事件处理完成后才会写入订阅，避免取消的 Checkout 或被刷新的 URL 获得权益。

正常路径是：登录、打开某个套餐的 Checkout、在 Stripe 付款、收到验签 webhook、把订阅写入 D1，然后在账号中显示权益。同一账号可以打开客户门户管理订阅。

webhook 按事件和 provider 对象幂等处理。重投应该更新同一条记录，而不是创建第二个订阅。本地示例不会真实扣卡；在声称计费可用之前，需要 test mode 的 Checkout 和 webhook 投递证据。

• Checkout 路由使用服务端拥有的 plan id。
• 客户门户要求已登录账号。
• webhook 在读取状态前验证 Stripe 签名。
• 订阅状态存 D1，不存在浏览器 cookie 里。

在部署环境中设置 `BILLING_PROVIDER=stripe`、`STRIPE_SECRET_KEY`、`STRIPE_WEBHOOK_SECRET` 以及 Pro/Scale 的 price id。保持 `DATABASE_DRIVER=d1`，并在上线前把 Worker 指向自己的 D1 数据库。

webhook 端点必须能被 Stripe 访问，并订阅路由用到的事件。`npm run doctor` 会报告哪些配置存在且不打印 secret，但它不证明 Stripe 已接受付款。开启 live 付款前，先跑 test mode Checkout、重放 webhook，并检查 D1 订阅行。

周边设置见[上手指南](/docs/getting-started)，订阅周期与积分授予如何分离见[积分与计费](/docs/credits-and-billing)。

示例不会真实扣卡，配置存在也不等于支付成功。缺少 price id、webhook secret 不匹配或 D1 不可达时应 fail closed；请修配置，不要把成功跳转当作证据。

退款与积分调整是分开的记账事件。退款不会静默扣回已授予的积分。模板不保存卡信息，卡数据由 Stripe 处理。

克隆模板时请使用自己的 plan id 和价格。不要把 VibeShip 示例的 $39/$99 当作授权价，也不要把示例套餐当作你的商业条款。

定价页是用模板搭出来的示例产品。它展示 Checkout 和账号界面，但不会真实扣卡。访客应该能看出套餐只是示例，模板授权是另一件事。

模板也不替你做商业条款。套餐、价格和取消政策由你的产品决定。模板提供的是接线：服务端 plan id、验签 webhook 和 D1 记录。把示例数字复制到授权页，是产品决策，不是模板功能。

订阅写入后，客户门户是变更或取消套餐的正常入口。取消是 provider 事件；webhook 会更新记录，避免账号继续保留 provider 已结束的权益。退款不是取消事件，积分调整又是第三类事件。

支持人员应该通过读取 D1 行和 Stripe 事件来解释订阅，而不是重放浏览器会话。把事件历史、订阅行和积分账本分开，退款就不会静默改写已授予的余额。