用途
sumup-debug 用于诊断和修复失败的 SumUp 集成。当出现 SumUp HMAC 签名校验失败、结算会话过期、作用域未激活、组件无法挂载等情况时，可使用该技能进行排查。
快速分诊矩阵
技能建议先对症状进行分类：
- 认证/签名错误
- 结算创建/处理错误
- 组件/客户端挂载或流程错误
- 异步不匹配（界面显示成功，但后端状态失败）
然后采集证据：
- 请求/响应载荷（脱敏处理）、HTTP 状态、错误码/错误消息
- checkout id、merchant code、checkout_reference
- webhook 投递 id 与签名判定结果
在修改生产行为之前，先在沙箱中复现问题。
常见故障与修复
HMAC 签名不匹配（x-payload-signature）
症状：webhook 校验对全部事件失败，或间歇性失败。
可能原因：
- 在验证前 body 解析器已改变了载荷内容
- webhook secret 与环境配置配对错误
- 摘要使用非原始 body 字节计算
修复：
- 基于原始请求体字节进行验证
- 确保使用 HMAC SHA-256 和精确配置的 secret
- 确认 secret 属于同一商户/环境
验证：重放载荷和实时沙箱 webhook 的签名校验均通过。
结算/会话窗口过期
症状：延迟后支付尝试失败、结算状态过期，或进入超时流程。
可能原因：
- 结算在有效窗口之后仍处于待处理状态
- 前端使用已过期的 checkout id 重试
修复：
- 每次重试都创建新的结算
- 添加前端超时处理，请求新的结算
验证：重试流程始终使用新的 checkout id/reference，并在沙箱中成功。
缺少作用域激活或认证不匹配
症状：凭据有效但仍返回 401/403。
可能原因：
- 缺少 payments 或其他必要作用域
- 在需要 OAuth 的场景使用了 API key，或反之
修复：
- 确认集成类型对应的认证模型
- 请求/启用所需作用域，并按需重新签发 token/key
验证：此前失败的端点使用最小权限的有效凭据后成功。
币种与商户不匹配
症状：结算因币种或商户限制被拒绝。
可能原因：
- 结算币种未对商户启用
- 多商户场景中选择了错误的商户
修复：
- 创建结算前校验商户与币种
- 在后端校验层强制执行映射规则
验证：无效组合被提前拦截；有效组合可正常处理。
Affiliate key / 应用标识不匹配
症状：卡在场（card-present）流程失败或无法正确初始化。
可能原因：
- Bundle ID/app ID 与 affiliate key 配置不一致
- 卡在场请求缺少 affiliate 元数据
修复：
- 使应用标识与 affiliate key 设置对齐
- 为终端/云端流程包含所需的 affiliate 数据
验证：设备/读卡器结算路径在沙箱/测试设备中可初始化并完成。
重复的 checkout_reference
症状：结算结果重复或冲突，对账混乱。
可能原因：
- 生成的非唯一引用
- 重试逻辑复用旧引用，且没有幂等保护
修复：
- 为每个逻辑支付意图生成唯一且确定性的引用
- 添加重复检测和安全重试行为
验证：重复尝试被拒绝或对账处理，不会产生重复履约。
Card Widget 被阻止或无法挂载
症状：组件无法渲染，或发出错误/初始化失败。
可能原因：
- 脚本被 CSP 或域名策略阻止
- checkout id 无效或环境不匹配
- 前端初始化存在竞态条件
修复：
- 在 CSP 和 JS origins 配置中允许所需的 SumUp 脚本来源
- 确认 checkout id 的环境与生命周期
- 仅在脚本加载完成且 DOM 就绪后挂载
验证：组件可稳定挂载并完成测试支付。
调试回答的必需响应契约
对每个调试回答，应包含：
- 按置信度排序的最可能根因
- 用于确认或排除各假设的最小可复现检查
- 精确的修复步骤，并附低风险上线建议
- 修复后验证清单
- 任何用于防止复发的监控/日志改进建议
适用场景与限制
该技能适用于排查 SumUp 集成中的上述故障类型，特别是签名、结算生命周期、作用域、币种与商户、应用标识、引用唯一性以及前端组件挂载问题。
其限制在于：资料仅提供了排查流程、常见故障类别与修复方向，未提供具体的 API 请求代码、安装命令、价格或收费信息、平台范围、实际效果数据或详细使用步骤；这些内容暂未提供。