上线检查清单

生产上线前逐项确认。每一条都对应一个曾经在联调中出过问题的点。

凭据与配置

• [ ] API Key 与 Callback Secret 保存在服务端，前端不接触凭据。
• [ ] 测试与生产使用各自独立的 API Key、Callback Secret、端点配置和订单号空间。
• [ ] 从测试切生产只替换域名和凭据，不修改接口路径、请求 Schema 或签名算法。
• [ ] 生产回调地址与返回地址已提交平台配置。

地址安全

• [ ] success_url、exit_url、callback_url 均为完整的公网 HTTPS 地址。
• [ ] success_url 和 exit_url 不指向平台自身的管理端或授权入口。
• [ ] 前端直接打开平台返回的 authorization_url，没有自行拼接授权页地址。

回调

• [ ] 接收端先验签（基于原始字节），再解密，再解析 JSON。
• [ ] 按 event_id 幂等去重，回调记录与业务状态在同一事务中保存。
• [ ] 事务提交后才返回 2xx；处理耗时控制在 10 秒内。
• [ ] 已验证重复投递、非顺序到达两种场景。

状态与取数

• [ ] 状态查询作为回调的补充，间隔不低于 15 秒。
• [ ] 取数前确认产品 state == "SUCCEEDED" 且 available == true。
• [ ] 已处理 SUCCESS/SUCCEEDED 同时出现 qualityStatus=WARNING、 collectionResult=COMPLETED_WITH_WARNINGS 的情况，并保存质量明细。
• [ ] 没有用页面进度百分比作为业务判断依据。
• [ ] 成功判定统一使用 success === true，未硬编码 code == 200 （发票 ALL 成功码是 0）。

数据范围

• [ ] 已明确选择 ALL / STANDARD（或两者），以及发票 LEGACY / CURSOR / PACKAGE。
• [ ] 税务 ALL 无需选择版本；所有渠道均使用 V2 并包含两张扩展表。
• [ ] 税务 ALL 结果连同 job_id、attempt_id 和质量摘要保存；未自行传入或猜测映射版本。
• [ ] 未再发送已废弃的模块筛选字段（会被忽略）。
• [ ] 原始发票解析器允许未知字段；STANDARD 按 schemaVersion 处理。

大批量与文件

• [ ] 分页、游标和分片下载均支持断点续传与幂等落库。
• [ ] 分页以 orderNo + pageNum 幂等；某页失败只重试该页。
• [ ] 下载 PDF / 分片 / 原始文件后校验 SHA-256。
• [ ] 直接使用返回的 downloadUrl，未自行拼接；分片与 PDF 下载未附加渠道请求头。
• [ ] 需长期留存原始表格时，已在保留期内转存到自有存储。

安全

• [ ] 签名请求每次使用新的 Nonce（UUID v4 或等强度随机数）。
• [ ] 服务器时钟已与 NTP 同步（签名时间戳容差 300 秒）。
• [ ] 若启用 SM4，已在目标语言验证解密可用，且实现了「先验签后解密」。
• [ ] HTML 报告 accessUrl 按敏感凭据保护，未写入公开日志或分析参数。

联调覆盖

• [ ] 成功
• [ ] 处理中（PROCESS / 60003）
• [ ] 失败（含 retryable 与不可重试两类）
• [ ] 部分税务项目未取得但已有数据继续交付（COMPLETED_WITH_WARNINGS）
• [ ] 税局会话失效后从原授权链接重新录入凭据，确认 job_id 不变、attempt_id 更新
• [ ] 重复回调
• [ ] 签名错误
• [ ] 链接过期

可观测性

• [ ] 每笔业务记录 external_order_id、authorization_code、job_id、attempt_id。
• [ ] 记录每次请求的 Nonce 与响应 code，回调的 event_id 与 X-RPA-Delivery。
• [ ] 对 60003 长时间不结束、回调长时间未到达设置告警。

生产验证

• [ ] 在生产环境用一笔真实订单完成端到端验证。
• [ ] 确认生产订单与测试订单数据相互隔离，未复用测试订单号。