外部 Provider 验收清单

本文档用于区分“本地 Provider contract 已闭口”和“真实外部 Provider 已生产验收”。没有真实账号、真实链、真实支付、真实直播厂商、真实广告厂商或真实发布凭据时，只能声明本地 mock / contract smoke 通过，不能把它写成生产验收完成。

验收原则

• Provider SPI、Manager、ConfigResolver、Admin 运维入口和 mock / contract smoke 可以在本地闭口。
• 真实外部验收必须在授权账号、真实凭据、真实网络、真实回调地址和接近生产的配置下执行。
• 所有真实写操作必须有幂等 key、审计记录、状态机、失败补偿和回滚预案。
• 资金、链上交易、短信、邮件、直播推流、广告结算和 AI 真实调用不得使用开发机假数据冒充生产成功。
• 发布说明中要分别写明“本地 contract 通过”和“真实 Provider 验收结果”，不要混写。

通用检查项

类别	检查
凭据	账号、API Key、证书、私钥、Webhook secret、回调 token 不进入 Git；能轮换、能禁用、能脱敏展示
配置	Provider、超时、重试、回调地址、白名单、费率、额度和开关可通过部署环境或配置中心管理
网络	出站域名、入站回调、TLS、Nginx / 网关、IP 白名单和防火墙规则已按厂商要求放通
回调	回调验签、防重放、幂等、TraceId、失败重试和人工补偿入口可用
状态机	创建、处理中、成功、失败、取消、退款 / 回滚 / 冲正等状态不会绕过业务规则
审计	操作人、请求 ID、外部单号、外部交易号、失败原因和原始摘要可追踪
观测	日志、指标、最近失败、重试次数、队列 / 调度任务和告警入口可定位问题
数据一致性	本地账本、外部流水、对账差异、补偿结果和余额 / 权益 / 库存变化可复核
权限	Admin 运维入口有权限码、按钮权限、数据范围和高风险操作二次确认
回滚	凭据撤销、Provider 下线、重试暂停、人工冲正和业务降级路径已记录

分领域验收

能力	最小真实验收
Payment / Cashier	沙箱或小额真实支付、支付回调、退款、重复回调、失败回调、对账拉取和补偿查询；Payment Platform 服务商可用 ./scripts/release provider-smoke-acceptance --domain payment-platform --provider <provider> 生成验收模板
Money 充值提现	法币充值、法币提现、余额冻结 / 解冻、出账、失败退回、手续费和管理员人工调整审计
Web3	只读 RPC、代币元数据、价格查询、签名路线（external-http / KMS / HSM / Vault / 本地 signer 风险确认）、小额充值确认、小额提现广播、Bridge 放款确认、nonce / replay 防护和链上失败解释；发版前可用 ./scripts/release web3-provider-acceptance --chain <chain> --rpc-provider <provider> 生成验收模板，填完后用 ./scripts/release web3-provider-gate --record <file> 校验记录完整性
AI	真实模型调用、流式响应、失败 fallback、用量计量、成本记录、限流、质量评测和超时降级；AI B2B2C 模型商城发版前可用 ./scripts/release ai-b2b2c-acceptance --payout-provider <provider> 生成真实打款、资金四方对账和 Release Gate 终审记录模板，填完后用 ./scripts/release ai-b2b2c-gate --record <file> 做归档前证据完整性检查；money-balance 只证明内部余额结算，不能作为 EXT-2 外部 payment / web3 payout 真实验收通过证据；Release Gate 需 11 项逐项通过，不能只填写总结果。gate 通过后可用 ./scripts/release ai-b2b2c-archive --record <file> 打包记录副本、gate 输出和归档说明，外部证据真伪仍需人工复核
Video	真实推荐 Provider 召回 / 排序、小样本质量复核、外部 Provider 失败回退、创作者收益摘要核验、真实打款或外部财务系统联动记录；发版前可用 ./scripts/release video-provider-acceptance --recommendation-provider <provider> --payout-provider <provider> 生成验收模板，填完后用 ./scripts/release video-provider-gate --record <file> 校验记录完整性
Live	推流授权、播放授权、录制任务、截图 / 转码回调、断流恢复、直播间聊天和违规通知；发版前可用 ./scripts/release provider-smoke-acceptance --domain live --provider <provider> 生成验收模板
Advertising	外部账号连通、素材同步或投放、收益报表拉取、预算扣费、反作弊规则、结算差异复核和真实打款联动记录；发版前可用 ./scripts/release advertising-settlement-acceptance --provider <provider> 生成验收模板，填完后用 ./scripts/release advertising-settlement-gate --record <file> 校验记录完整性
Distribution	小额打款、外部交易号登记、失败补偿、团队收益快照、用户侧结算详情和 Admin 对账
Reading 书源	授权证明、投诉入口、受控小批量导入、重复同步幂等、下架 / 撤稿处理、导入批次留痕和回滚预案；发版前可用 ./scripts/release reading-source-acceptance --source-code <code> 生成验收记录模板，填完后用 ./scripts/release reading-source-gate --record <file> 校验记录完整性
Meeting / RTC	真实房间创建、令牌签发、入会 / 离会、TURN / SFU 连通、录制 / Egress、Webinar / 大会场容量边界；发版前可用 ./scripts/release provider-smoke-acceptance --domain rtc --provider <provider> 生成验收模板
SMS / Mail / Notification	模板审核、发送成功、发送失败、回执、退订 / 黑名单和频率限制
Storage / Media / Document	上传、私有下载、公开访问、临时 URL、文件类型校验、病毒 / 内容安全策略和大文件超时；发版前可用 ./scripts/release provider-smoke-acceptance --domain storage --provider <provider> 生成验收模板
WeChat	公众号 / 小程序账号授权、模板同步、订阅消息发送、登录回调和支付回调边界；发版前可用 ./scripts/release provider-smoke-acceptance --domain wechat --provider <provider> 生成验收模板
Maven Central	central-release effective-pom、sources / javadoc / sign、本地 dry-run、Central token、GPG key 和 Portal 人工确认；发版前可用 ./scripts/release maven-central-dry-run --version <version> 生成本地 dry-run 命令清单

通用 Provider smoke 记录填写完成后，先执行：

./scripts/release provider-smoke-gate --record <file>

该命令只校验记录字段是否具备真实环境、Provider、账号、凭据来源、回调、外部请求 / 对象 / 交易、失败路径、结果和回滚证据；它不会调用厂商，也不能替代人工审查外部证据真实性。若 gate 未通过，不得从 .ai/todo.md 移除对应外部验收项。

Web3 真实链记录使用专用 gate：

./scripts/release web3-provider-gate --record <file>

该命令要求记录包含真实链、chain id、RPC Provider、凭据来源、外部签名 / 托管路线、充值 / 提现 / Bridge / 退款 tx、nonce / replay、扫描 checkpoint、结果和回滚证据；它同样只做字段完整性校验，不会连接 RPC、不签名、不广播交易。

记录模板

发布前把真实验收结果写入发布说明或部署验收记录：

Provider:
Environment:
Credential source:
Callback URL:
Smoke command / operation:
External request id:
External transaction id:
Local audit id:
Result:
Rollback plan:
Known limitations:

如果只完成本地 contract smoke，记录时必须写清：

Local contract: passed
Real external acceptance: not executed
Reason: missing production credential / sandbox account / real chain / vendor approval
Next owner:

发布口径

• ./scripts/release checklist --version <version> 只提醒需要执行外部 Provider 验收，不替代真实厂商环境。
• ./scripts/release maven-central-dry-run --version <version> 只生成本地 Central profile 验证命令，不签名、不上传、不创建 Portal 发布。
• ./scripts/release dry-run 生成的是发布说明草稿，真实 Provider 验收结论需要维护者手工补入。
• ./scripts/release api-compat 只覆盖公共 Java API 兼容，不覆盖外部 Provider 行为。
• Docker / IDEA / Playwright / mock Provider smoke 通过，只能证明本地框架链路正常；真实支付、真实链、真实直播、真实广告和真实 AI 仍按本文档单独验收。