批量任务的部分失败处理
批量处理要接受一个事实：一定会有部分条目失败。设计重点是让失败可控可追：每条记录状态（成功、待重试、失败、跳过），失败项设重试上限后归入死信，批次结束给出总量与失败原因分布，重放时按批次号与条目键做幂等，不重复写入。
基本信息
| 条目状态 | ok、retry、failed、skipped 四类，状态落库 |
|---|---|
| 重试上限 | 每条有限次数，超限转 failed 并进死信 |
| 批次报告 | 总数、成功数、重试数、失败数、原因分布 |
| 死信 | 可导出、可人工处理后重放 |
| 重放 | 带批次号与条目键，写入前去重 |
典型使用场景
- 批量抽取：少数文档格式异常导致失败，不影响其余条目
- 批量发信或写库：失败的单独落死信，成功的不需要重跑
- 数据回填：按批次号重放，保证重复执行不产生重复数据
- 夜间跑批：早上看批次报告就能判断要不要补跑
- 对外交付：给客户一份条目级结果清单，而不是一句“部分失败”
状态与报告示例
状态与报告示例
条目状态: ok | retry | failed | skipped
批次报告:
总数 1000 / 成功 962 / 重试 21 / 失败 17
失败原因: 429 共 9 条，超时 5 条，校验失败 3 条
死信: 17 条导出为文件，人工处理后可按批次号重放
重放: 写入前按条目键去重，重复执行结果一致
# 重试与失败要分开统计，否则看不到上游是否在劣化错误类型与处置
| 错误类型 | 处置 | 原因 |
|---|---|---|
| 限流与超时 | 安排重试，带退避 | 多为瞬时问题，重试有效 |
| 校验失败 | 直接进死信 | 重试不会改变结果 |
| 权限或参数错误 | 整批停止并报错 | 继续跑只会产生成批无效请求 |
| 内容策略拒绝 | 标记跳过 | 重试无意义，需换策略 |
批次报告要能回答两个问题：这批到底成了多少、没成的都是什么原因。缺了原因分布，报告只是一串数字。
批次规模要拆得小一些：单批太大时中途中断就得整批重来，单批几千条既便于重放，也便于把失败原因归到同一类。