Files
moyi-model-intelligence-hub/docs/22-async-task-safety.md
T

6.9 KiB
Raw Blame History

异步任务幂等与执行安全

阶段一:创建幂等(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. 暂不提供“无证据一键退款/重新生成”的管理接口。受审计的人工核账入口、关联上游任务编号、人工确认终态以及差额结算是下一阶段产品工作;在该入口完成前,只允许按受控运维流程核对证据,不直接修改钱包余额替代结算事务。
  5. 成功的 token 图片任务缺少可核验用量时,仍沿用既有 TASK_USAGE_PENDING 规则:保留结果、暂不扣费、释放该次预留并标记待核账。本阶段没有把“已知完成但计量缺失”与“是否受理未知”混为一类。
  6. HTTP 受理至观察日志提交之间仍有无法跨外部系统原子提交的窗口。数据库完全不可用时也不能承诺保存回执;恢复后转入待核账,而非声称精确恢复所有生成结果。

后续重点:审计化人工核账入口、异步路由/上游模型的执行快照、共享有界 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、旧认领检查竞态、凭据丢失、轮询期限、待核账并发占位、审计事务回滚、成功结果先保存后结算、晚到失败不得退款、结算恢复一次扣费,以及模糊状态白名单。