integrate-stripe

集成 Stripe

构建 Stripe 集成时，应与现有应用、业务模式、币种、国家/地区以及付款归属相匹配。规划或编写 Stripe 代码前，务必先检查项目。

首先：检测现有集成

在代码仓库中搜索 Stripe 程序包、导入、配置、环境变量名称、API 客户端、Checkout 或 PaymentIntent 的创建逻辑、Webhook 路由、数据库字段、迁移、测试以及前端 Stripe.js 的用法。检查程序包清单和锁定文件，以确定已安装的 Stripe SDK 版本。识别固定的账户、请求或 Webhook API 版本，但不要泄露机密值。

• 如果已存在 Stripe 集成，请追踪完整的付款流程并保留兼容的架构。找出不完整、过时、不安全或已损坏的行为，并做出最小且安全的修复。没有明确理由时，不要创建第二个 Stripe 客户端、Webhook 端点、Customer 模型或付款流程。
• 如果不存在 Stripe 集成，请使用项目现有的语言、框架、数据库、验证、错误处理、日志记录和测试模式，从头设计集成。
• 如果 SDK 或 API 版本较旧，请先查看官方变更日志和迁移指南。谨慎升级并进行测试；切勿在处理无关工作时悄悄更改 Stripe 版本。

Stripe 会不断变化，因此编写代码前，请根据 Stripe 最新官方文档核实 API 选型。除非项目有意固定版本，否则优先使用最新受支持的 SDK 和 API 版本；升级时应做好规划并进行测试，切勿悄悄更改版本。

工作流

1. 说明是否发现现有 Stripe 集成，并列出相关 SDK/API 版本和已实现的流程。
2. 确定产品需要一次性购买、订阅、按用量计费、发票、保存付款方式、市场平台付款，还是这些方式的组合。
3. 明确谁是登记商户，谁拥有客户关系，资金结算到哪里，由谁处理争议，以及是否收取平台费用。
4. 选择最简单且合适的方案：无代码销售使用 Payment Links，大多数集成使用 Checkout Sessions，嵌入式 UI 使用带有 Payment Element 的 Checkout Sessions，仅在需要定制付款状态控制时使用 PaymentIntents。
5. 由服务器负责确定产品、Price ID、金额、币种、折扣、税务行为、身份、权益、资金目的地和费用。绝不要信任客户端提供的这些值。
6. 在重定向到付款页面前，先持久化内部待处理订单或订阅。使用不敏感的元数据关联 Stripe 对象。
7. 将经过验证的 Webhook 视为事实来源。确保履约和状态更改具备幂等性，并能安全处理重试或乱序事件。
8. 实现失败、取消、重试、退款、争议和对账流程，而不只是成功流程。
9. 在沙盒中测试，覆盖身份验证和失败场景，重放 Webhook，并完成上线审核。

不可妥协的规则

• 绝不要在源代码、客户端、日志、错误信息或示例中暴露密钥、受限密钥或 Webhook 密钥。每个服务都应优先使用遵循最小权限原则的受限密钥。
• 除非业务已完成所需的 PCI 流程，否则绝不要在服务器端处理原始卡号。请使用 Checkout 或 Stripe.js Elements。
• 绝不要根据成功重定向或客户端报告的状态履约。
• 验证 Webhook 签名时，必须使用未经修改的原始请求正文。
• 使用唯一约束对事件 ID 去重，并尽可能以事务方式执行更改。
• 对重试的金融类 POST 操作使用稳定的幂等键。
• 新开发中不要使用旧版 Charges、Sources、Tokens、Plans 或 Card Element。
• 除非当前官方 Terminal 指南明确要求，否则不要指定 payment_method_types，以使用动态付款方式。
• 未经明确批准，绝不要执行真实扣款、退款、转账或账户更改。

参考资料路由

• Checkout、Payment Element、PaymentIntents、SetupIntents、客户、退款、争议、SCA 和测试，请阅读 references/payments.md。
• 订阅、发票、试用期、按比例计费、客户门户、用量计费和权益，请阅读 references/billing.md。
• 实现或审查 webhook 端点前，请阅读 references/webhooks.md。
• 平台、市场、关联账户、入驻、费用、收费模式和责任，请阅读 references/connect.md。
• 密钥、PCI 范围、财务完整性、可观测性、对账、迁移和上线，请阅读 references/security-and-production.md。
• 可调整的实现示例，请阅读 references/implementation-patterns.md。
• 有关作为此扩展技能基础而致谢的上游技能，请阅读 references/source.md。

验证与输出

运行相关的格式化、lint、类型检查和测试。说明 Stripe 是修复完善的，还是从头添加的；检查或更改了哪些版本；选择了哪些 Stripe 对象和 webhook 事件；内部状态如何映射到 Stripe；如何防止重复操作；以及还需要进行哪些 Dashboard 设置。将沙盒验证与实时验证分开说明。