修复账号场景生成的幂等与结果返回协议

站内场景入口读取并透传可选幂等键，复用既有队列去重逻辑场景配方保留 AGC 来源标记，恢复可下载的队列完成结果补充非法幂等键、场景结果序列化和幂等命名空间回归测试同步 OpenAPI、技术方案、实施计划及排障记录
2026-09-24 16:18:40 +00:00
parent bb69e09b8d
commit 2370dc509b
8 changed files with 134 additions and 7 deletions
@@ -18,7 +18,7 @@ AGC 美术包背景阶段（结构化场景意图）

 ## 非目标

- 不改动站内 `/api/editor/scenes/generations` 的请求字段、Prompt 组装结果与计费语义。
+- 保持站内 `/api/editor/scenes/generations` 的场景字段、Prompt 和计费规则；补齐 AGC 账号模式所需的可选幂等键与队列结果协议。
 - 不放松通用 `/api/editor/images/generations` 与 `/api/external/v1/editor/images/generations` 对 `kind = scene` / `assetKind = scene` 的拒绝。
 - 不新增场景 Worker、任务表、计费档位或 SpacetimeDB schema。
 - 不改变美术包背景图的出图风格与尺寸（16:9 / 1K）。
@@ -40,6 +40,7 @@ AGC 美术包背景阶段（结构化场景意图）
 4. 受理响应与现役外部生成入口同形（operationId 异步受理信封），轮询继续走 `/api/external/v1/generations/{operation_id}`。
 5. 入队后 `kind = scene`、`assetKind = scene`，队列类型、Worker、计费与持久化与站内场景路由一致；队列标题与任务摘要口径不变。
 6. AGC 美术包背景阶段以 `stylePreset = custom` + `customStyle` 承载现有风格描述，`sceneContent` 承载 brief 衍生的画面内容，出图风格与比例不因迁移改变。
+7. 普通账号自动映射到 `/api/editor/scenes/generations`，该入口读取可选 `Idempotency-Key` 并传给现有队列；未提供时保留站内按请求 ID 入队的行为。场景组装仅保留 `generationInputs.source = ai-game-creator-client` 这一精确标记，其余配方字段仍由服务端重建。该标记让账号任务沿用 AGC 幂等命名空间和包含可下载 `result` 的队列结果，轮询走 `/api/runtime/external-generation/jobs/{operation_id}`。

 ### 失败、重试与幂等

@@ -47,6 +48,7 @@ AGC 美术包背景阶段（结构化场景意图）
 2. 缺少或非法幂等键、越权 scope 的拒绝语义与现役外部生成入口一致。
 3. 同一幂等键 + 同一请求重放返回原任务，不新建任务、不重复扣费；同键不同请求返回 409。
 4. Provider 失败、取消与 lease 耗尽沿用现有扣退费语义。
+5. 账号场景入口拒绝非法幂等键（400）；同键重放复用现有队列幂等实现。来源标记不参与权限授予，任务归属仍来自已认证用户。

 ### 权限、归属与数据边界

@@ -64,6 +66,7 @@ AGC 美术包背景阶段（结构化场景意图）

 | 条款 | 验收方式 | 证据 |
 | ---- | -------- | ---- |
+| 账号入口幂等键校验与 AGC 下载结果 | 非法键路由测试、场景来源到结果序列化测试、共享队列幂等命名空间测试 | `cargo test --locked -p api-server scene`（18 项）、`editor_generation_queue::tests`（19 项）、`external`（158 项）通过；本地启动因 SpacetimeDB 连接拒绝未通过健康检查，真实 Provider 出图与账号同键重放尚未联调 |
 | 新路由受理/参数校验/鉴权/幂等重放 | api-server 契约测试与单测 | 待补 |
 | 与站内路由同一 Prompt 组装结果 | 共享实现的单测对照 | 待补 |
 | OpenAPI 与实现一致 | 契约测试 + `check:openapi` 类门禁 | 待补 |