如何集成 Stripe 等收费系统

flowchart LR
  user["用户"]
  frontend["前端页面"]
  backend["你的后端"]
  checkout["Stripe Checkout"]
  webhook["Stripe Webhook"]
  db["Supabase / 业务数据库"]

  user -->|"点击购买"| frontend
  frontend -->|"请求创建支付会话"| backend
  backend -->|"按后端价格创建 Session"| checkout
  frontend -->|"跳转到支付页"| checkout
  checkout -->|"支付完成后发送事件"| webhook
  webhook -->|"校验签名并更新状态"| backend
  backend -->|"写入 orders / subscriptions"| db
  db -->|"前端刷新后读取最新状态"| frontend

sequenceDiagram
  autonumber
  actor User as 用户
  participant Frontend as 前端页面
  participant Backend as 后端 API
  participant Stripe as Stripe Checkout

  User->>Frontend: 点击"升级"或"购买"
  Frontend->>Backend: POST /api/billing/create-checkout-session
  Note right of Frontend: 前端传 plan / userId / email\n不传最终收费金额
  Backend->>Backend: 校验套餐并映射 priceId
  Backend->>Stripe: 创建 Checkout Session
  Stripe-->>Backend: 返回 session.url
  Backend-->>Frontend: 返回支付链接
  Frontend-->>User: 跳转到 Stripe 支付页
  User->>Stripe: 完成付款

我现在是第一次用 Stripe，你先不要改代码，先带我在 Stripe 后台把最基本的付费配置做好。

请基于这些官方文档给我一步一步的操作说明：
- https://docs.stripe.com/products-prices/manage-prices
- https://docs.stripe.com/checkout/quickstart?lang=node

我的情况是：
- 我想做一个最简单的会员付费
- 只有两个套餐：月付和年付
- 我现在还不懂 Product、Price 这些词

请你：
1. 先用最简单的话告诉我 Product 和 Price 分别是什么。
2. 再按"先打开哪个页面 -> 点哪里 -> 填什么"的顺序教我操作。
3. 最后提醒我，做完以后我需要从后台复制哪些内容给后端使用。
4. 如果我容易走错，请顺便提醒我应该一直在测试模式里操作。

请你先看看我这个项目现在是怎么放环境变量的，然后帮我把 Stripe 需要的环境变量整理出来。

请参考这些文档：
- https://docs.stripe.com/keys
- https://docs.stripe.com/webhooks

我的情况是：
- 我是零基础
- 我分不清哪些变量应该放前端，哪些应该放后端
- 我也不确定当前项目应该改 `.env`、`.env.local` 还是别的文件

请你：
1. 先搜索当前项目里环境变量通常写在哪。
2. 帮我列出 Stripe 接入最少需要哪些变量。
3. 用最简单的话告诉我每个变量是干什么的。
4. 告诉我每个变量应该去哪一个 Stripe 页面复制。
5. 如果项目里有示例环境变量文件，请直接帮我补上变量名。

请你先看看我当前项目的后端代码是怎么组织的，然后帮我把 Stripe 支付接进去。

请参考这些官方文档：
- https://docs.stripe.com/checkout/quickstart?lang=node
- https://docs.stripe.com/api/checkout/sessions/create
- https://docs.stripe.com/payments/subscriptions

我的目标很简单：
- 用户点购买按钮后，能跳到 Stripe 的付款页面
- 套餐只有月付和年付两种
- 不要让我自己决定代码该放在哪，你先看项目再帮我放到合适的位置

请你：
1. 先搜索项目，弄清楚后端入口文件、路由文件、环境变量写法分别在哪里。
2. 再参考官方文档，帮我把"创建 Stripe 支付链接"这一步接进去。
3. 不要让我自己传金额，价格请用后端环境变量来决定。
4. 做完后告诉我你改了哪些文件。
5. 最后告诉我，我还需要去 Stripe 后台补哪些配置。

帮我把项目里的"购买"按钮接上 Stripe。

要求：
- 不动现有页面，只改按钮点击后的逻辑
- 点击后调用后端接口获取支付链接，然后跳转到 Stripe
- 如果出错，给用户一个简单提示（比如"支付暂时不可用，请稍后再试"）

参考文档：https://docs.stripe.com/payments/checkout/build-integration

请继续帮我把 Stripe 的"付款成功后自动生效"这一步接好。

请参考这些官方文档：
- https://docs.stripe.com/webhooks
- https://docs.stripe.com/stripe-cli
- https://docs.stripe.com/stripe-cli/use-cli

我的目标是：
- 用户付完钱后，不只是跳转到成功页面
- 而是真的把我数据库里的会员状态改成已开通

请你：
1. 先搜索当前项目里数据库相关代码和用户状态是怎么存的。
2. 再帮我加 Stripe webhook。
3. 支付成功后，把对应用户改成 active，或者更新成项目里现在已经在用的会员状态字段。
4. 如果项目里已经有订阅表、订单表、用户表，请优先沿用现有结构。
5. 做完后告诉我你改了哪些文件。
6. 顺便告诉我本地怎么测试这一步有没有真的生效。

请你帮我把当前项目接上 Stripe 支付，我希望做一个最简单能跑起来的会员收费功能。

我的要求：
1. 我是零基础，请你先自己看项目，再决定代码应该改哪里。
2. 不要让我自己判断目录结构、路由结构、数据库结构。
3. 我只想先做最简单版本：月付和年付两个套餐。
4. 用户点击购买后，能跳到 Stripe 付款页面。
5. 付款成功后，我数据库里的会员状态能变成已开通。
6. 不要一开始加太多复杂功能，比如优惠券、升级降级、复杂发票。

输出要求：
1. 先给我一个改动计划。
2. 然后直接修改代码。
3. 最后告诉我怎么一步一步本地测试。
4. 如果有哪个步骤还需要我去 Stripe 后台操作，请直接把链接和要点告诉我。

请继续帮我把 Stripe 支付真正跑通，我想一步一步照着做，不想自己猜。

请参考官方文档：
- https://docs.stripe.com/webhooks
- https://docs.stripe.com/stripe-cli
- https://docs.stripe.com/stripe-cli/use-cli

我的目标：
1. 告诉我先打开哪些 Stripe 页面。
2. 告诉我如何拿到 STRIPE_WEBHOOK_SECRET。
3. 告诉我如何使用 stripe login 和 stripe listen。
4. 告诉我怎样验证 checkout.session.completed 已经成功打到本地 webhook。
5. 如果当前项目需要先启动前端和后端，也请顺带告诉我具体命令。
6. 不要只讲原理，请按实际操作步骤输出。
7. 如果我某一步做错了，也请告诉我最常见的报错会长什么样。

flowchart TB
  pay["用户在 Stripe 完成支付"]

  subgraph unreliable["❌ 不可靠路径：只看 success 页面"]
    success["浏览器跳到 success 页面"]
    fake["前端代码认为已开通"]
    risk["风险：关页 / 断网 / 伪造 URL / 根本没付钱"]
    success --> fake --> risk
  end

  subgraph reliable["✅ 可靠路径：以后端 Webhook 为准"]
    event["Stripe 服务器发送 Webhook"]
    verify["后端校验签名"]
    active["数据库正式更新为已付费"]
    event --> verify --> active
  end

  pay --> success
  pay --> event

sequenceDiagram
  autonumber
  actor User as 用户
  participant Frontend as 你的网页
  participant Stripe as Stripe
  participant Webhook as 你的后端接口
  participant DB as 数据库

  User->>Stripe: 在 Stripe 页面完成付款
  Note over Stripe: 钱真的到了 Stripe 账户

  Stripe-->>Frontend: 浏览器跳转到 success 页面
  Note over Frontend: ⚠️ 这步只是跳转<br/>不代表系统已确认

  Stripe->>Webhook: 发送 Webhook 通知<br/>"checkout.session.completed"
  Note over Webhook: ✅ 这才是正式通知

  Webhook->>Webhook: 校验签名<br/>（确保是 Stripe 发的，不是黑客）

  Webhook->>DB: 更新用户状态为"已付费"
  DB-->>Webhook: 保存成功
  Webhook-->>Stripe: 返回 200 OK

  Frontend->>DB: 用户刷新页面，查询状态
  DB-->>Frontend: 返回"已付费"
  Note over Frontend: 这时候才显示会员功能

// 错误：在 success 页面直接开通
// success.html
if (window.location.pathname === '/success') {
  // 危险！任何人都能访问 /success
  activateMembership();
}

// 正确：每次刷新都查后端
// success.html
async function checkStatus() {
  const response = await fetch('/api/user/status');
  const data = await response.json();
  
  if (data.paymentStatus === 'paid') {
    showMemberFeatures();
  } else {
    showPendingMessage();
  }
}

stateDiagram-v2
  [*] --> NotStarted: 用户未购买
  NotStarted --> Active: checkout.session.completed
  Active --> Active: invoice.paid
  Active --> PastDue: invoice.payment_failed
  PastDue --> Active: 用户补款成功
  Active --> Canceled: customer.subscription.deleted
  PastDue --> Canceled: 到期未恢复
  Canceled --> [*]

  state "未开通" as NotStarted
  state "会员有效" as Active
  state "扣费失败 / 待恢复" as PastDue
  state "已取消 / 到期回收" as Canceled

sequenceDiagram
  autonumber
  participant Stripe as Stripe
  participant Webhook as 你的 Webhook 接口
  participant DB as 订阅表 / 订单表
  participant App as 你的应用
  actor User as 用户

  rect rgb(235, 248, 255)
    Stripe->>Webhook: invoice.paid
    Webhook->>DB: 延长 current_period_end
    DB-->>Webhook: 更新成功
    Webhook-->>Stripe: 200 OK
    App-->>User: 继续保持会员有效
  end

  rect rgb(255, 247, 237)
    Stripe->>Webhook: invoice.payment_failed
    Webhook->>DB: 标记 past_due
    DB-->>Webhook: 更新成功
    Webhook-->>Stripe: 200 OK
    App-->>User: 提醒更新支付方式
  end

  rect rgb(254, 242, 242)
    Stripe->>Webhook: customer.subscription.deleted
    Webhook->>DB: 标记 canceled
    DB-->>Webhook: 更新成功
    Webhook-->>Stripe: 200 OK
    App-->>User: 停止高级权限
  end