Files

62 lines
6.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 异步任务幂等与执行安全
## 阶段一:创建幂等(2026-10-21)
- 公网 `/v1/{3d|video|image|audio}/tasks` 与 Playground 创建入口支持可选 `Idempotency-Key`。
- 键为 1–128 个可见 ASCII 字符;只保存 SHA-256,不保存原始键。幂等命名空间为用户,不局限于单个 API Key。
- 请求摘要包括任务类型和完整请求体,递归排序 JSON 对象键、规范化数值,保留数组顺序及文本内容;不忽略未知字段或悄悄修剪提示词。
- 相同用户、相同键、相同请求返回原任务的当前状态,包括成功或失败后的重放;相同键和不同请求返回 HTTP 409 / `IDEMPOTENCY_CONFLICT`。
- 有效凭据校验、基础 RPM 检查先执行;幂等重放不再进入生成流程,因此不受后来变更的模型价格、队列容量、余额或路由下线影响。这与同一用户查询历史任务的权限范围一致。
- 同键创建在数据库事务中取得用户/键摘要 advisory lock;部分唯一索引提供最终约束。检查原任务发生在队列计数、预算占用、钱包冻结之前。
- 不提供键失效后自动重用,避免客户端晚到重试再次生成。无幂等键的调用保持原有语义。
验证:Java 21 / Maven,隔离 PostgreSQL 15.18(不连接业务数据库),26 项针对性测试通过,0 失败、0 跳过。包含 8 路并发同键请求、重放、请求冲突、完成后路由下线重放、键摘要规范化与风控顺序。
## 阶段二:未知受理与可恢复结算(2026-10-21)
### 模块边界
- `provider.transport.ProviderRequestException` 只描述 HTTP 边界事实:`NOT_SENT`、`REJECTED`、`UNKNOWN`,保留可安全展示的错误码及 HTTP 状态,不附带上游响应体、凭据或异常原文;不决定重试和退款。
- `task.TaskOutcomeJournal` 持久化已观察的终态和待核账状态,不发送请求、不修改钱包、不制定退款策略。
- `AsyncTaskService` 编排提交、只读轮询和本地结算。收到生成结果后先提交日志,再在原有钱包/任务/审计事务中结算;账本失败不能被提交请求异常处理器误认为上游生成失败。
### 状态与账务
| 观察到的事实 | 任务状态 / 后续动作 | 钱包与预算 |
| --- | --- | --- |
| 本地输入/配置校验失败、请求尚未发出 | `failed` | 原子释放预留,不扣费 |
| HTTP 400/401/402/403/404/405/413/415/422/429 明确拒绝 | `failed` | 原子释放预留,不自动重发 |
| HTTP 408/409、5xx、网络异常、成功响应不可解析 | `reconciling`,不自动重发 | 保留冻结及预算占用,等待证据核账 |
| 回执缺少合法任务 ID,或回执无法保存 | `reconciling` | 保留冻结,不假定生成失败 |
| worker 已认领、两分钟后仍无 ID 且无终态日志 | `reconciling` | 保留冻结,不重新派发 |
| 已受理任务的轮询期限到期,或原凭据已移除 | `reconciling`,停止自动轮询 | 保留冻结,不将查询失败视为生成失败 |
| 已收到上游终态,但本地结算失败 | 保存 `completion_status` 和归一化结果,下轮只重试本地结算 | 保留冻结,成功后只扣一次 |
| 已确认上游失败/取消 | 原子提交终态与审计 | 释放预留,只执行一次 |
兼容视频路径的备用接口只在可结构化识别的 HTTP 404/405 拒绝后尝试,不再解析错误文案判断重试;5xx 或结果未知不换接口。轮询是只读操作,瞬时鉴权/限流/网络异常可继续尝试至持久化期限,但不能由此推导退款。
`V46` 扩展 `model_tasks` / `usage_events` 状态约束并增加终态观察日志。生成内容复用已有 `result` 列,不重复存两份。日志一旦观察到终态,晚到的冲突状态不能覆盖它;过期认领检查也不能覆盖已经保存的任务编号。
`reconciling` 仍计入异步模型/API Key/用户的数据库并发与队列容量,避免未知任务被无限替换为新任务。用户任务页展示“待核账”,提示额度仍冻结、勿重复提交;使用记录可筛选,管理员容量分组保留待核账计数,即使渠道已停用也不隐藏。
状态解析改为明确白名单:`success` / `succeeded` / `completed` 才能结算;不再把 `unsuccessful` 当成功,也不把 `cancelling` 当取消完成。其他未知状态继续只读查询,期限到后进入核账状态。
### 上线与核账边界
1. 本阶段只验证隔离测试数据库,没有迁移业务数据库或部署线上服务。发布时先停旧 worker,再迁移 `V45` / `V46` 并启新 worker,避免混跑旧的自动退款逻辑。
2. 不回溯改写历史失败任务或重新冻结曾经释放的资金。历史的提交中断、超时、凭据丢失记录须独立审计,不能自动扣款。
3. 待核账状态不会按 TTL 自动退款,不会自动重发。收集本地任务 ID、用户、时间、模型路由、预留金额、上游任务/账单记录;不要把完整凭据放进工单或日志。
4. 后续 V47/V48 已补受审计的人工核账入口:恢复只读查询、确认失败释放原冻结、按原快照确认成功,详见 `23-audited-task-reconciliation.md`。不提供无证据一键退款、重新生成、任意改余额或追扣已释放资金。
5. 成功的 token 图片任务缺少可核验用量时,仍沿用既有 `TASK_USAGE_PENDING` 规则:保留结果、暂不扣费、释放该次预留并标记待核账。本阶段没有把“已知完成但计量缺失”与“是否受理未知”混为一类。
6. HTTP 受理至观察日志提交之间仍有无法跨外部系统原子提交的窗口。数据库完全不可用时也不能承诺保存回执;恢复后转入待核账,而非声称精确恢复所有生成结果。
后续人工核账与 provider/model 执行绑定已在 V47/V48 完成,范围及剩余限制见 `23-audited-task-reconciliation.md`。继续重点处理共享有界 HTTP Transport、媒体下载安全、完整配置版本绑定与上游有证明的幂等能力适配。
### 最终验证
2026-10-21:Docker / Java 21 / Maven 3.9.9 执行 `mvn -B -o clean verify`,后端 190 项测试全部通过(0 失败、0 错误、0 跳过),Spring Boot JAR 构建成功。使用独立 PostgreSQL 15.18,Maven 容器共享测试数据库的 network namespace;未访问业务数据库或真实供应商 API。
前端 `npm run build`(含 `vue-tsc --noEmit`)和 `npm test` 通过,22 项测试全部通过。前端“待核账”提示已通过类型检查和构建,未将这些测试描述为完整浏览器交互验收。`git diff --check` 无错误。
重点回归覆盖:8 路同键并发、终态/失败后重放、不同请求冲突、HTTP 408/409/5xx、收到 POST 后断开响应且不重发、成功响应 JSON 无法解析、无任务 ID、旧认领检查竞态、凭据丢失、轮询期限、待核账并发占位、审计事务回滚、成功结果先保存后结算、晚到失败不得退款、结算恢复一次扣费,以及模糊状态白名单。