支付Webhook诊断工具 是做什么的？
从证据出发，不要盲目重发。将事件重播到有问题的处理器上可能会重复其副作用。
每次只处理一个任务
| 问题 | 参考文档 |
|---|---|
| 签名失败、密钥错误、解析后的请求体、旧版本投递 | references/signatures.md |
| 重复记账、延迟履约、成功后失败、退款乱序 | references/reconciliation.md |
| 4xx/5xx/超时、恢复、事件丢失、生产环境部署 | references/incident-playbook.md |
| 需要验证的协议事实和版本边界 | references/sources.md |
| 需要非Stripe / M-Pesa适配器 | references/provider-boundary.md |
工作流程
- 确定范围：提供商、快照vs薄事件、测试/生产模式、关联账户、端点框架和API版本。仅询问会改变诊断结果的缺失事实。
- 检查处理器代码、数据库迁移、预期订单金额/币种、服务器创建的PaymentIntent映射以及打码后的投递元数据。将签名密钥保存在本地环境变量中。不要要求用户将密钥或客户请求体粘贴到聊天中。
- 在解析JSON之前验证确切的原始请求字节。对于已部署的处理器，优先使用官方Stripe SDK。内置的无依赖验证器是一个小巧、可检查的诊断参考工具，并非替代SDK。
- 首先使用以下本地工具通过合成测试夹具重现故障。将证据分类为已观察、推断或未验证。有效签名验证了投递的真实性，但不证明订单应被履约。
- 修复最小根因并添加回归测试。将支付绑定到受信任的服务端订单；比较金额、币种、账户作用域和模式。将入站消息处理、账簿更新和副作用意图放在同一个数据库事务中。
- 验证重复事件、同一对象的不同事件、重启、乱序投递、失败事件以及部分/全额退款。不要使用事件时间戳作为全局排序机制。
- 交付诊断结果、补丁、测试证据、未解决的集成需求以及明确的回滚/恢复计划。未经用户授权的工作流，不要部署、重发生产事件、发起退款或转移资金。
本地工具
从技能根目录运行：
npm test
npm run demo
使用文档化的测试时钟检查保存的测试模式夹具：
export DOCTOR_FIXTURE_SECRET='fixture_only_not_a_live_secret'
node scripts/doctor.mjs --body fixtures/payment.json --header fixtures/signature.txt \
--secret-env DOCTOR_FIXTURE_SECRET --fixture-now 1794130000 \
--normalized-out /tmp/payment-doctor-event.json
python3 scripts/ledger.py --db /tmp/payment-doctor-reference.sqlite \
--orders fixtures/orders.json < /tmp/payment-doctor-event.json
导出命令拒绝覆盖已存在的文件。请使用新的输出路径或故意删除你自己生成的合成输出。Python CLI仅写入明确指定的本地SQLite数据库。它期望验证器输出的可信标准化事件；它本身不验证签名。切勿将其暴露为公共webhook端点。
正常诊断报告排除客户数据、原始请求体和签名。明确的标准化导出保留本地对账所需的标识符和整数金额。请将其保密且不纳入版本控制。
--fixture-now仅用于旧的合成测试事件；它拒绝生产模式输入。对于普通当前投递，请省略此参数。参考账簿拒绝生产模式事件，从不调用Stripe，也从不发送出站消息队列行。
必需的报告
- 结果： 发生了什么以及是否已重现。
- 证据： 文件/行号、打码后的投递元数据、精确命令、观察到的输出。
- 根因： 已确认的根因与剩余的假设。
- 修复： 最小补丁以及迁移/回填的影响。
- 回归测试矩阵： 重复、重启、作用域不匹配、金额/币种错误、排序、退款等场景。
- 运维交接： 仍需的测试模式集成证据；安全重播和回滚条件。
边界
支持范围严格限定为Stripe快照事件：payment_intent.succeeded、payment_intent.payment_failed以及退款对象事件。薄事件、订阅权益、Checkout会话、争议、多次捕获支付语义、应用费用、税费和Connect转账需要专用适配器。零发现结果不等于安全认证或资金已到账的证明。在扩展之前请参阅参考文档。