长任务的三个必备能力
生成一份长报告、批量处理上千条数据、跑多轮工具调用——这类**长任务**失败是常态。
要让用户敢用，必须具备三件事：**可恢复、幂等、进度可见**。
一、可恢复（断点续跑）
把任务拆成**可独立完成的步骤**，每步产出一个可持久化的中间结果；
记录"已完成到第几步"（检查点），失败后从检查点继续，而不是从头再来；
**中间结果要落盘**（数据库/对象存储），不要只留在内存里；
检查点要带**输入指纹**：输入变了就不能复用旧中间结果，否则会错。
实践上最有价值的一条：**让每一步都能单独重跑**（本地也能重跑），调试与恢复都靠它。
二、幂等（重复执行不出错）
长任务必然遇到重试与并发，幂等是底线：
每步用**业务唯一键**（不是随机 id）作为幂等键；
写操作采用 upsert 语义；
外部副作用（发信、扣费、调用第三方）放到最后，或用"先记录意图、再执行、再确认"的两阶段方式；
允许"至少执行一次"，但保证"结果一致"。
三、进度可见
对外暴露**阶段**（准备 → 处理 12/50 → 汇总）而不是一个转圈；
阶段名称要**人话**（"正在解析第 3 份文件"比 "processing" 有用）；
提供已用时与预计剩余（粗一点没关系，关键是"在动"）；
失败时给出**明确的失败点**与可执行的建议（重试 / 跳过 / 人工处理）。
常见的四个错
全部放在一个 HTTP 请求里跑（超时、断连就全丢）；
中间结果只存内存（进程一重启前功尽弃）；
无幂等键 → 重试后数据翻倍；
进度只写日志不返回给前端（用户不知道在动，只好反复点重试 → 加重负载）。
落地顺序
1. 先把任务**拆步**并落盘中间结果（这一步收益最大）；
2. 加幂等键与 upsert；
3. 暴露阶段进度与失败点；
4. 加一个"从检查点恢复"的按钮，并演练一次真恢复。