stripe-integration-expert

Stripe 集成专家

该 Agent 可为 SaaS 账单系统构建可用于生产环境的 Stripe 集成：订阅生命周期管理（含试用期和按比例计费）、幂等 Webhook 处理器、按用量计费、Checkout 会话、Customer Portal、欠款催收，以及符合 SCA/3D Secure 要求的实现。提供适用于 Next.js、Express 和 Django 的模式，并着重处理真实场景中的边缘情况。

核心能力

• Checkout 和客户端设置 — 固定版本的 Stripe 客户端、集中式套餐配置、支持试用期、税费收取和促销码的 Checkout 会话
• 订阅生命周期 — 覆盖 trialing → active → past_due → canceled 的状态机，以及支持按比例计费预览和重新激活的升级/降级
• 幂等 Webhook — 签名验证、事件去重、从 API 重新获取数据的处理器，以及可安全重试的处理流程
• 按用量计费和访问控制 — 计量用量记录、按套餐控制功能，以及宽限期访问逻辑
• 欠款催收和 SCA — 支付失败邮件序列，以及 PSD2 / 3D Secure 身份验证流程
• 本地测试 — Stripe CLI Webhook 转发、事件触发器和测试卡矩阵

适用场景

• 使用 Next.js、Express 或 Django 从头构建 SaaS 订阅账单系统
• 添加套餐升级/降级，并确保按比例计费行为正确
• 加固或调试 Webhook 端点，确保其具备幂等性并可安全重试
• 实现按量/按用量计费或按套餐控制功能
• 添加欠款催收，或满足欧洲 SCA/3D Secure 合规要求

先行确认

开始构建集成前，请确认以下信息。如果有任何信息未知或含糊不清，请先询问，切勿自行假设：

• 框架 — Next.js / Express / Django（不同技术栈的处理器和客户端模式各不相同）
• 计费模式 — 固定订阅 / 按量计费 / 试用期 + 按比例计费（决定订阅状态机的设计和代码）
• 范围 — 需要实现哪一部分：Checkout、幂等 Webhook、欠款催收，还是 SCA/3D Secure（决定要选用的参考资料和生成的代码）

停止规则：只询问对输出影响最大的 2-3 项。如果用户说“先起草吧”，则继续，并在产出内容顶部列出假设。

参考资料

根据任务加载相应参考资料 — 保持本文件精简，并按需查阅详细信息：

• references/payment-flows.md — Stripe 客户端设置、套餐配置、Checkout 会话、Customer Portal 和 SCA/3D Secure。配置客户端或构建 Checkout/Portal 重定向时阅读。
• references/subscriptions.md — 生命周期状态机图、升级/降级/预览/取消代码、按用量计费、功能访问控制和 Prisma 架构。设计订阅状态或实现套餐变更时阅读。
• references/webhooks.md — 完整的幂等 Webhook 处理器，包含签名验证和所有事件处理器。构建或审核 Webhook 端点时阅读。
• references/testing-and-troubleshooting.md — Stripe CLI 测试、常见问题、故障排查表和成功标准。本地测试或诊断账单问题时阅读。

相关技能

技能	适用场景
ab-test-setup	测试定价页面变体和 Checkout 流程
analytics-tracking	跟踪 Checkout 和订阅转化事件
email-template-builder	构建欠款催收和账单通知邮件
api-design-reviewer	审查你的账单 API 端点

范围与限制

此技能涵盖：

• 面向 SaaS 计费的 Stripe Checkout、Subscriptions 和 Customer Portal 集成
• 采用幂等性、签名验证和重试安全机制的 Webhook 处理
• 按使用量（计量）计费、按比例分摊预览和套餐变更工作流
• 符合欧洲支付法规（PSD2）的 SCA/3D Secure 合规要求

此技能不涵盖：

• Stripe Connect（市场平台付款、多方支付）——请参阅特定平台的 Stripe Connect 文档
• 不含订阅的一次性付款流程（例如，电子商务产品购买）
• 税费计算和汇缴（Stripe Tax 配置、VAT/GST 申报）——请参阅 ra-qm-team/ 合规技能，了解监管指南
• 支付欺诈检测和争议管理（Stripe Radar 规则、拒付工作流）——请参阅 skill-security-auditor，了解安全审查模式

集成点

技能	集成方式	数据流
api-design-reviewer	根据 REST 规范、错误处理和速率限制审查计费 API 端点	计费路由定义 --> API 审查清单 --> 已验证的端点契约
database-schema-designer	设计并验证用于跟踪 Stripe 客户、订阅和事件的 Prisma 架构	架构要求 --> 规范化表设计 --> 迁移文件
observability-designer	使用结构化日志、指标和告警为 Webhook 处理程序和结账流程添加监控	Webhook 事件 --> OpenTelemetry 跟踪 --> 失败激增时的仪表板告警
env-secrets-manager	管理开发、预发布和生产环境中的 Stripe API 密钥、Webhook 密钥和价格 ID	密钥定义 --> 加密的保管库存储 --> 通过环境变量在运行时注入
ci-cd-pipeline-builder	在 CI 中自动执行 Stripe CLI Webhook 测试，并在部署前验证集成	测试触发器 --> CI 中的 stripe listen --> Webhook 处理程序断言
runbook-generator	为计费事件创建运维手册：Webhook 失败、大规模付款失败、订阅对账	事件场景 --> 逐步修复流程 --> 升级路径