1

docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md

@@ -19,7 +19,7 @@
 生成页步骤固定为：
 
 ```text
-生成物品名称 -> 生成素材图 -> 切割独立图片 -> 生成 3D 模型 -> 上传图片与模型资产 -> 写入草稿页
+生成游戏名称 -> 生成物品名称 -> 生成素材图 -> 切割独立图片 -> 上传图片资产 -> 写入草稿页
 ```
 
 生成页只展示题材和物品数量，不展示玩法规则说明。
@@ -32,15 +32,17 @@
 
 1. 读取 session config。
 2. 将本次 MVP 的 `clearCount` 固定为 `3`，并同步用于草稿编译。
-3. 调用文本模型生成 `3` 个题材下的短物品名称。
-4. 调用项目当前图片链路 VectorEngine `gpt-image-2-all` 生成一张 `1:1` 素材图，提示词必须合入入口页选择的 `assetStylePrompt`。历史 `nanobanana2` 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
-5. 将素材图按 `n*n` 网格切割成独立图片。当前 `3` 件物品使用 `2*2` 网格，取前 `3` 格。
-6. 将素材图和每张独立图片上传到 OSS，其中独立图片作为 Rodin 图生模型参考图。
-7. 对每张独立图片调用 Hyper3D Rodin Gen-2 图生模型，等待任务完成，读取 GLB 下载文件并转存到 `generated-match3d-assets`。
-8. 调用现有 SpacetimeDB compile procedure 写入草稿，并把本次生成的独立物品图片与模型文件引用序列化写入 `match3d_work_profile.generated_item_assets_json`。这一步对标拼图的 `save_puzzle_generated_images`：生成资产不能只挂在本次 HTTP response 上，否则退出结果页后从草稿架读取 `getMatch3DWorkDetail` 会丢失素材列表。
-9. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息，模型生成成功时状态为 `model_ready`；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 恢复同一批素材。
+3. 基于入口页题材设定文本调用文本模型生成作品元信息。模型固定请求 `gpt-4o`，只返回 JSON，其中 `gameName` 为 4 到 12 个中文字符的游戏名称，`tags` 为 3 到 6 个中文短标签；`summary` 首版必须保持空字符串，结果页 `作品描述` 默认留给用户填写。
+4. 调用文本模型生成 `3` 个题材下的短物品名称。
+5. 调用项目当前图片链路 VectorEngine `gpt-image-2-all` 生成一张 `1:1` 素材图，提示词必须合入入口页选择的 `assetStylePrompt`。历史 `nanobanana2` 图片选项当前按项目统一决策回落到 VectorEngine，不重新接入 APIMart 图片网关。
+6. 将素材图按 `n*n` 网格切割成独立图片。当前 `3` 件物品使用 `2*2` 网格，取前 `3` 格。
+7. 将素材图和每张独立图片上传到 OSS，其中独立图片作为草稿页素材预览和后续 Rodin 图生模型参考图。
+8. 调用现有 SpacetimeDB compile procedure 写入草稿，并把本次生成的独立物品图片列表序列化写入 `match3d_work_profile.generated_item_assets_json`。这一步对标拼图的 `save_puzzle_generated_images`：生成资产不能只挂在本次 HTTP response 上，否则退出结果页后从草稿架读取 `getMatch3DWorkDetail` 会丢失素材列表。
+9. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息，独立图片状态为 `image_ready`，模型字段保持为空；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 恢复同一批素材。
 
-草稿生成阶段会调用 Hyper3D Rodin，并等待 GLB 模型文件可下载；不得把上游下载 URL 直接写入 Match3D profile，必须先转存 OSS，再保存 `/generated-match3d-assets/...` 引用。结果页 `3D素材` Tab 的重新生成按钮仍可手动触发 Rodin 任务，但正式持久化仍以后端草稿生成链路写入的模型文件为准。
+若文本模型不可用或返回无法解析，后端必须降级为 `{themeText}抓大鹅` 与本地标签兜底，不阻断素材生成；但描述仍保持空字符串。
+
+草稿生成阶段不调用 Hyper3D Rodin，不等待 `subscriptionKey`，也不下载模型文件；Rodin 生成只在结果页 `3D素材` Tab 由用户手动触发。手动生成得到的上游下载 URL 仍不得直接写入 Match3D profile，后续正式资产绑定以独立技术方案为准。
 
 ## 4. 图片提示词
 
@@ -82,12 +84,11 @@ generated-match3d-assets
 ```text
 generated-match3d-assets/{sessionId}/{profileId}/material-sheet/{taskId}/sheet.png
 generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/image.png
-generated-match3d-assets/{sessionId}/{profileId}/items/{itemSlug}/model/{taskUuid}/model.glb
 ```
 
 `itemSlug` 必须带 `itemId` 前缀，例如 `match3d-item-1-item`。中文物品名清洗后可能都退回 `item`，不能只用物品名做路径，否则多张切割图会写到同一个 object key，导致草稿页预览图全部一致。
 
-HTTP DTO 同时返回 `imageSrc`、`imageObjectKey`、`modelSrc`、`modelObjectKey`、`modelFileName`、`taskUuid`、`subscriptionKey` 和 `status = model_ready`。前端模型预览不得直接请求裸 `/generated-match3d-assets/...` 路径；需要通过 `/api/assets/read-bytes` 读取模型字节，转成 Blob URL 后交给 Three.js GLTFLoader 加载，以绕开私有 bucket CORS。
+HTTP DTO 同时返回 `imageSrc`、`imageObjectKey`、空的 `modelSrc`、空的 `modelObjectKey` 和 `status = image_ready`。前端预览图片继续走 `ResolvedAssetImage` 换签；后续手动生成的模型文件也必须通过 `useResolvedAssetReadUrl` / `/api/assets/read-url` 换签后打开，不直接请求裸 `/generated-match3d-assets/...` 路径。
 
 ## 6. 自动保存与草稿恢复
 
@@ -101,6 +102,13 @@ HTTP DTO 同时返回 `imageSrc`、`imageObjectKey`、`modelSrc`、`modelObjectK
 
 因此 `map_match3d_work_summary_response` / `map_match3d_work_profile_response` 需要从 work profile snapshot 反序列化 `generated_item_assets_json` 并输出 `generatedItemAssets`。前端 `Match3DResultView` 仍保持现有优先级：本次生成流程内有 `draft.generatedItemAssets` 时用 draft；从草稿架重进没有 draft 时，用 `profile.generatedItemAssets`；两者都没有才回退到默认 3D 素材占位。
 
+结果页 `作品信息` Tab 字段命名对齐拼图草稿：
+
+1. `作品名称` 对应 Match3D `gameName`。
+2. `作品描述` 对应 Match3D `summary`，草稿生成默认空。
+3. `作品标签` 对应 Match3D `tags`，可由 AI 首次生成并允许用户继续编辑。
+4. 封面图与作品名称不再拆成左右两个大模块；封面只作为同一 Tab 内的可选上传入口，避免和作品基础信息割裂。
+
 `3D素材` 详情页只保留：
 
 1. 模型预览区：优先加载 `modelSrc` 对应 GLB，支持拖动旋转；没有模型时展示空预览。
@@ -127,4 +135,4 @@ cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml
 cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml
 ```
 
-真实草稿生成需要本地私密环境配置 `VECTOR_ENGINE_API_KEY`、`HYPER3D_API_KEY` 和 OSS 访问变量。后端改动后使用 `npm run api-server` 启动，并检查 `/healthz`。
+真实草稿生成需要本地私密环境配置 `VECTOR_ENGINE_API_KEY` 和 OSS 访问变量；`HYPER3D_API_KEY` 只在结果页手动生成 3D 模型时需要。后端改动后使用 `npm run api-server` 启动，并检查 `/healthz`。