Merge branch 'master' into fix/agc-rust-staging-idempotency

2026-09-28 12:12:59 +08:00
parent 0b19df467e 8f59c034f5
commit 55b881de49
20 changed files with 947 additions and 112 deletions
@@ -1493,6 +1493,9 @@ game-project/

 ## 2026-08-23 Direct Codex 美术包显式重生成与切片投影

+- 标准美术包在客户端将规范图、背景图和主图集统一保存为 PNG：下载仍校验来源、声明类型与文件签名，随后按真实内容接受 PNG/JPEG/WebP，在已有 20 MiB、4096 像素单边和 64 MiB 解码内存限制内完整解码。有效 PNG 原样保留，JPEG/WebP 编码成 PNG，最终内容也不得超过 20 MiB；本地媒体类型固定为 `image/png`。转码不补造透明度，主图集与独立切片继续执行真实 alpha、可见像素、尺寸和唯一性合同；平台独立切片仍须为 PNG。此行为仅属于美术包，普通图片工具的指定扩展名合同不变。
+- 美术包的转码在项目提交锁和本地写入之前完成，文件摘要、已安装结果识别、替换恢复和 manifest 登记均使用最终 PNG。转码失败保留原生成账本与平台身份，同冻结意图重试重新读取已有结果，不提交新的付费生成；不改变请求快照、幂等身份、固定资源路径或旧 PNG 包的复用方式，无数据迁移。验收覆盖 JPEG/WebP 转码、PNG 字节不变、损坏/超限拒绝、真实透明度以及已有结果重复恢复零生成 POST；客户端真实 Provider 的整包验证单独记录。
+- 转码自动化验收由 `canvas_generation_tests` 的格式/边界用例和 `retained_runtime_generation_retries_a_completed_stage_without_posting_again` 本地 HTTP 夹具覆盖：PNG/JPEG/WebP 均先下载损坏内容，再从同一已完成账本恢复两次，核对最终 PNG、稳定本地 asset ID、Canvas 来源身份、账本保留/清理及零生成 POST；替换与补偿继续由现有图集事务和 Direct 重生成用例覆盖。真实 Provider 的客户端整包效果不由这些夹具替代。
 - `agc_tools.taonier_prepare_game_art` 的请求模式固定为 `reuse-or-create | regenerate`。缺省使用 `reuse-or-create`，完整且可信的本地包继续零付费复用；只有用户显式要求重做、替换或切换视觉风格时使用 `regenerate`，并绕过完整包短路，按规范图、背景图、透明图集顺序生成和原位替换。`regenerate` 的旧包前置门只要求规范图和背景图已经可下载、可解码、来源一致且存在可信 manifest 登记，使两项旧字节与登记可以完整 rollback；历史主图集、私有回执、公开清单或 canonical 切片可以缺失。客户端必须把八个严格路径的实际存在性和摘要，以及其中受管顶层 asset identity，逐项冻结为 `Present/Some` 或 `Missing/None`，不能把缺失状态伪造成空文件或虚假登记。规范图或背景图任一缺失或身份无效时才失败关闭并提示先用 `reuse-or-create` 修复基础素材。
 - 显式重生成不放宽 External Editor 幂等与未知态边界。固定阶段已有 `prepared / accepted` 账本时，本次生成 prompt 必须与账本冻结 prompt 一致才可恢复；不一致返回 `platform-generation-result-unknown` 并保留原 `Idempotency-Key / operationId` 对账，禁止把旧结果解释为新意图，也禁止另起付费 POST。
 - 整包重生成在首个付费阶段前建立客户端私有 v4 workflow，状态固定为 `resetting / in-progress / compensating / completed`，并同时绑定意图摘要和客户端稳定 `clientTurnId`。专用 `direct-codex-art` 跨进程执行锁覆盖整个付费重生成生命周期，但不持有通用项目写锁等待网络。规范图和背景图替换后立即持久化旧字节、旧 manifest entry 与本轮双 CAS 锚点；任一后续阶段失败时进入 `compensating`，可在进程重启后继续恢复旧文件及旧登记。已成功阶段的生成账本继续保留；`completed` 持久化经脱敏和数量 / 长度限制的完整工具结果，同一 `clientTurnId` 回包丢失时必须等值重放且零新 POST。新的显式用户回合先持久化目标回合所有的 `resetting` workflow，再清理上一轮三阶段账本并转回 `in-progress`，任一崩溃点都不得出现无 workflow 窗口。只有尚无任何阶段账本且无替换锚点的孤立 `in-progress` 空壳允许被新回合原子接管；其余身份冲突、未知版本以及缺少新恢复字段的旧 v2/v3 workflow 均失败关闭，不能用 serde 缺省值把旧状态升级成可执行状态。
@@ -0,0 +1,78 @@
+# 【技术方案】External v1 游戏场景生成路由
+
+更新时间：`2026-09-24`
+
+## 目标
+
+为 `/api/external/v1` 补齐游戏场景生成的结构化专用路由，使 AGC 客户端（陶泥儿美术包背景阶段）在平台收紧 `kind = scene` / `assetKind = scene` 边界校验后仍有合规的场景生成入口：
+
+```text
+AGC 美术包背景阶段（结构化场景意图）
+-> POST /api/external/v1/editor/scenes/generations
+-> 后端确定性组装场景 Prompt（与站内场景路由同一实现）
+-> 现有 editor_image_generation 队列与 Worker
+-> 现有计费、幂等、失败、资源持久化与 canvasCompletion
+```
+
+同时修复 AGC 客户端背景阶段保留账本匹配口径与实际请求不一致的既有隐患。
+
+## 非目标
+
+- 保持站内 `/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）。
+- 不处理 issue #495 的抠图重放 409 与动画 compact 字段问题（独立排期）。
+
+## 入口与边界
+
+- 系统入口：AGC 客户端 Direct 美术包流程的背景阶段（`reuse-or-create` 与 `regenerate` 均经过）。
+- 涉及模块：`api-server`（external v1 路由与场景 Prompt 组装）、`shared-contracts`（DTO 复用）、AGC `src-tauri`（请求构造、保留账本、身份对账与恢复扫描常量）。
+- 正式状态来源：`external_generation_job` 队列记录与项目 manifest 登记，与现役外部生成入口一致。
+
+## 必须成立的行为
+
+### 正常路径
+
+1. 新路由 `POST /api/external/v1/editor/scenes/generations` 接受与站内场景路由相同的 `EditorSceneGenerateRequest` 字段（`sceneContent`、`stylePreset`、`customStyle?`、`model?`、`aspectRatio?`、`imageSize?`、`referenceImageSrcs?`、`projectId?`、`generationInputs?`、`assetFolderId?`、`assetLabel?`、`canvasCompletion?`），不接受调用方组装后的完整 `prompt`。
+2. 场景 Prompt 由后端经与站内路由完全相同的组装实现生成；两路由只共享这一份组装逻辑。
+3. 鉴权复用现有 `editor:image-generate` scope；与现役外部生成入口一样强制 `Idempotency-Key` 请求头。
+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}`。
+
+### 失败、重试与幂等
+
+1. 缺少 `sceneContent`、非法 `stylePreset`、自定义风格缺少 `customStyle` 等参数错误返回 400，与站内路由同语义。
+2. 缺少或非法幂等键、越权 scope 的拒绝语义与现役外部生成入口一致。
+3. 同一幂等键 + 同一请求重放返回原任务，不新建任务、不重复扣费；同键不同请求返回 409。
+4. Provider 失败、取消与 lease 耗尽沿用现有扣退费语义。
+5. 账号场景入口拒绝非法幂等键（400）；同键重放复用现有队列幂等实现。来源标记不参与权限授予，任务归属仍来自已认证用户。
+
+### 权限、归属与数据边界
+
+1. 资源归属、项目绑定与素材文件夹解析沿用现役外部生成入口的 owner 口径。
+2. 任务摘要只展示 `generationInputs.fields` 的「画面内容」，不把后端完整 Prompt 暴露到任务侧栏。
+3. 场景产物以 `assetKind = scene` 持久化并保存 `scene.generate` V2 配方，与站内产物口径一致。
+
+## 契约与迁移
+
+- API / DTO / OpenAPI：新增 external v1 场景路由，DTO 复用 `shared-contracts` 的 `EditorSceneGenerateRequest`；同一次变更同步 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试（路由矩阵、鉴权、参数 400、幂等重放）。
+- SpacetimeDB schema / migration / bindings：不变。
+- 兼容与迁移策略：AGC 客户端背景阶段的路由、manifest 身份登记、保留账本匹配与恢复扫描常量整圈迁移到新路由；历史已登记的背景身份（旧通用路由 + `kind = spec`）保持可读，不做数据迁移。
+
+## 验收标准与证据
+
+| 条款 | 验收方式 | 证据 |
+| ---- | -------- | ---- |
+| 账号入口幂等键校验与 AGC 下载结果 | 非法键路由测试、场景来源到结果序列化测试、共享队列幂等命名空间测试 | `cargo test --locked -p api-server scene`（18 项）、`editor_generation_queue::tests`（19 项）、`external`（158 项）通过；本地启动因 SpacetimeDB 连接拒绝未通过健康检查，真实 Provider 出图与账号同键重放尚未联调 |
+| 新路由受理/参数校验/鉴权/幂等重放 | api-server 契约测试与单测 | 待补 |
+| 与站内路由同一 Prompt 组装结果 | 共享实现的单测对照 | 待补 |
+| OpenAPI 与实现一致 | 契约测试 + `check:openapi` 类门禁 | 待补 |
+| 美术包背景端到端（reuse-or-create / regenerate） | 客户端定向测试 + 本地真实栈 smoke | 待补 |
+| 中断恢复：保留账本匹配与身份对账 | 客户端定向测试 | 待补 |
+
+## 未决问题与决策
+
+- `stylePreset` 取舍：已决策——AGC 美术包背景固定 `custom` + `customStyle` 承载现有风格文案，不绑定预设风格（2026-09-24，与用户确认）。