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

18 lines
1.8 KiB
Markdown
Raw 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 路并发同键请求、重放、请求冲突、完成后路由下线重放、键摘要规范化与风控顺序。
## 接续项
接续修复提交响应丢失、进程中断、轮询超时以及结算数据库失败的语义。未知结果不得自动重发生成请求或释放冻结余额;只有已证实的拒绝或终态失败才能进入正常释放流程。核账操作必须有证据和审计,不允许用直接修改钱包余额替代结算事务。