用途:Stripe Connect 用于让平台通过 OAuth 连接各应用(如 Total TypeScript、Pro Tailwind 等)各自的 Stripe 账户,并查询其支付与订阅数据。
架构原则为“查询而非执行”:平台是编排者,不执行财务操作。平台通过 Connect 查询支付历史、订阅状态、客户详情、争议信息;应用通过 SDK 主动通知退款已处理、访问被撤销、许可证转移、购买创建等事件。平台不处理退款、不创建扣款、不修改订阅、不做任何财务变更,原因是应用拥有其财务操作,平台只提供上下文与智能。
OAuth 流程(标准账户):先构建授权 URL,参数含 response_type、client_id、scope、redirect_uri、state(用于防 CSRF);回调中校验 state,用 code 换取账户 ID(stripe_user_id,形如 acct_xxx),并写入 apps 表。
查询能力:可按客户邮箱查支付历史(先查客户再查 charges),查订阅状态(列出全部状态订阅,返回 id、状态、当前周期结束、是否期末取消、套餐名),以及用 refundId 核验退款状态(返回 id、status、amount、chargeId)。
Webhook 监控极简,仅处理需要平台感知的事件:account.application.deauthorized(清除 stripe_account_id),charge.dispute.created(告警并标记会话)。不监控 charge.refunded、customer.subscription.、payment_intent.,这些由应用通知或按需查询。
环境变量:STRIPE_SECRET_KEY、STRIPE_CONNECT_CLIENT_ID、STRIPE_WEBHOOK_SECRET。数据库 apps 表含 stripe_account_id 与 stripe_connected 字段。OAuth 错误包括 access_denied、invalid_grant、invalid_redirect_uri。
限制:仅查询、不执行财务变更;查询需指定已连接的 stripeAccountId;回调需校验 state;实际部署需按官方文档配置回调白名单等,资料未提供完整配置细节。