副作用边界上的幂等

面向 VOZEB PRO。数据流里「处处幂等」不是一个 HTTP 头搞定全站，而是：每一种花得起钱、写得进库、会惊动上游的动作，各自有「再来一次 = 返回上次」的键。 失败则把下一次敲门的时间写进同一行，而不是再开一张新单。

0. 什么时候用这套判断

适合：

不必硬套：

在 VOZEB PRO 中的定位: 任务用 clientRequestId 去重；钱包每笔消费/退款带服务端 idempotencyKey；支付回呼按事件 id 去重；上游只对一条 attempt create 一次，其余只 poll。四件事键不相同，不要混用。

幂等要守的是副作用边界，不是「函数再进一次」。

再做一次会多出什么	本仓库的键	重复时应该怎样
多一张任务 / 多一次调度	`clientRequestId`（进 Route / 调度前）	返回已有 run / 任务，`created: false`
多扣或多退一笔积分	服务端生成的 `idempotencyKey`	`applied: false`，返回上次流水
多付一笔钱 / 多发一次货	供应商事件 id、订单支付幂等	当已处理，不改第二次余额
上游再 create 一次（双倍账单）	attempt 上记下的上游 id	已有 id → 只 query；从未提交才 create；说不清 → `needs_review`

浏览器带来的 Idempotency-Key 不能直接当钱包流水号。用户能改、能重放、能和别人撞。计费键由服务端生成（AGENTS.md）。

这是数据流「处理」段的核，也是和 Worker 篇的接缝。

startGenerationAttempt / finishGenerationAttempt 把「对某一个渠道候选的一次尝试」记下来：渠道、模型、积分流水、成败。runtime 的规矩是：

关标签、热更新、换副本、Worker 再领，走的都是 2，不是 1。
「用户对同一失败结果点重试」才开新的 attempt（新的上游尝试），并沿用原来的会话 / 生成记录 / 结果槽身份——这是产品语义上的第二次，不是网络重试。

不要用提示词文本当去重键。相同文案点两次，本仓库视为两次独立提交。

任务 / Agent run
normalizeCreativeRunRequest → 按用户 + clientRequestId 查找。已存在就不再 schedule。去重发生在建任务之前，不是写完再删。

钱包
consume / credit / refund / 管理员调整都要带 idempotencyKey。Postgres 路径用唯一约束把「同一键第二下」变成读上次结果。返回里有 applied：false 表示这是回放，余额已经动过了。

支付 / 供应商回呼
按事件 id 去重。回呼网络抖动是常态；处理函数必须假设「同一条事件会来三遍」。

三套键不要合并成一个「全局请求 id」：一次用户点击可能对应「一个 clientRequestId + 一笔扣款键 + 若干次 poll（零次新的上游 create）+ 以后可能一笔退款键」。生命周期不同。

非终态任务会写未来的 nextPollAt。恢复批次（页面 after() 和 Worker 共用 runGenerationTaskRecoveryBatch）到期再领同一行。

连续错误指数退避：大约 5s 起，封顶 60s，避免把上游打穿。租约过期后任一 lane / Worker 都能领——领的是同一行，不是 insert 一行「重试任务」。

对照：

网络失败 / 进程死  →  同一任务行，nextPollAt 往后推
用户明确点重试    →  同一记录槽，新 attempt
用户再点一次生成  →  新 clientRequestId，新任务行

三种「再来」看起来都像 retry，键和行完全不同。写补丁前先说清是哪一种。

幂等管的是写。读一张已登记的图、刷新任务状态、打开作品页，不需要再发明一套幂等键。那些请求可以重入，因为它们不 create 上游、不扣积分。

若一个「刷新」接口里偷偷 create 了上游或又扣了一次钱，那是接口分类错了，不是少写了一个头。