Increase VectorEngine timeouts and add image UI
Add VectorEngine image generation config and raise request timeouts (env + scripts) from 180000 to 1000000ms. Introduce a reusable CreativeImageInputPanel component with tests and wire up mobile keyboard-focus helpers; update generation views and related tests (CustomWorldGenerationView, BarkBattle editor, Match3D, Puzzle flows). Improve API error handling / VectorEngine request guidance (packages/shared http.ts and docs), and apply multiple backend/frontend fixes for puzzle/match3d/prompt handling. Also include extensive docs and decision-log updates describing UI/UX decisions and verification steps.
This commit is contained in:
@@ -27,6 +27,8 @@
|
||||
5. 生成成功后自动进入 `match3d-result`。
|
||||
6. 生成失败时停留在生成过程页，允许重新生成或返回创作中心；重新生成必须复用同一个 session / profile，并从缺失的素材阶段继续，不新建第二份草稿。
|
||||
|
||||
抓大鹅生成过程页不展示“当前批次”模块；移动端只保留“预计等待”和“计时”两张状态卡并排展示，步骤卡进入页面时按顺序从屏幕左侧滑入。
|
||||
|
||||
生成页步骤固定为：
|
||||
|
||||
```text
|
||||
@@ -52,9 +54,9 @@
|
||||
7. 后端从同一份作品生成计划读取当前难度所需数量的短物品名称，并兼容保存历史 `soundPrompt` 字段；当前不生成点击音效。
|
||||
8. 调用 VectorEngine Gemini 原生图片接口生成 `1:1` 素材图，请求模型固定为 `gemini-3-pro-image-preview`，走 `POST {VECTOR_ENGINE_BASE_URL}/v1beta/models/gemini-3-pro-image-preview:generateContent?key={VECTOR_ENGINE_API_KEY}`。请求体使用 `contents[].parts[].text` 和 `generationConfig.responseModalities = ["TEXT", "IMAGE"]`、`generationConfig.imageConfig.aspectRatio = "1:1"`，响应从 `candidates[].content.parts[].inlineData.data` / `inline_data.data` 读取 base64 图片。提示词必须合入入口页选择的 `assetStylePrompt`，并强制每格使用统一纯绿色绿幕背景，避免白底或纹理背景进入运行态素材。该调整只作用于抓大鹅物品素材 sheet；封面和 `9:16` 纯背景图继续使用 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 链路，`1:1` 容器 UI 图必须使用 VectorEngine `/v1/images/edits` multipart 图生图链路，不能再把参考图作为 generations 的 `image` 数组弱参考。
|
||||
9. 每个物品固定需要 `5` 个不同视角。单张素材图固定为 `5*5 = 25` 格，因此单张图承载 `5` 个物品。若用户要求或难度派生的物品种类不是 `5` 的倍数，后端必须向上补齐物品名称和对应图片到最近的 `5` 的倍数；例如标准难度需要 `9` 种玩法物品，实际生成 `10` 个物品名称和对应五视角图片。若草稿物品数超过 `5`，后端按每批 `5` 个物品自动分批，多张素材图并行生成。
|
||||
10. 将每张素材图按固定 `5 行 * 5 列` 切割成独立图片，并按物品顺序连续分配 `5` 张视角图。素材图提示词必须要求 `5*5` 严格均匀排布、每格主体完整居中、统一纯绿色绿幕背景、相邻物体主体至少保留 `1/4` 单格宽度空白间距、不得跨格、贴边或越界，避免裁剪后相邻格内容污染。切割前必须先在整张素材图上做透明背景后处理：连通到 sheet 外边缘的绿幕/近白底要清成 alpha；每格内部未连到外边缘但高置信的纯绿绿幕块也必须清成 alpha；物品边缘的绿幕抗锯齿和近白白边要做透明或去污染处理；不够纯的绿色主体像素不得被当作绿幕误删。随后再在每个理论格子内按透明背景/前景像素做内容边界校准，并带少量安全留白导出；不能做固定内缩裁剪，避免贴近格线但未跨格的樱桃、叶片、把手等主体边缘被切掉。每个物品 JSON 写入 `imageViews[]`，同时把第一个视角兼容写入 `imageSrc/imageObjectKey`。
|
||||
10. 将每张素材图按固定 `5 行 * 5 列` 切割成独立图片，并按物品顺序连续分配 `5` 张视角图。素材图提示词必须要求 `5*5` 严格均匀排布、每格主体完整居中、统一纯绿色绿幕背景、相邻物体主体至少保留 `1/4` 单格宽度空白间距、不得跨格、贴边或越界，避免裁剪后相邻格内容污染。切割前必须先在整张素材图上做透明背景后处理：连通到 sheet 外边缘的绿幕/近白底要清成 alpha；每格内部未连到外边缘但高置信的纯绿绿幕块也必须清成 alpha；物品边缘的绿幕抗锯齿和近白白边要做透明或去污染处理；较厚的半透明或混色软绿边必须沿整张 sheet 透明背景继续清理，不能先裁剪单格再各自去绿，否则裁剪图会残留绿色描边；不够纯的绿色主体像素不得被当作绿幕误删。随后再在每个理论格子内按透明背景/前景像素做内容边界校准，并带少量安全留白导出；不能做固定内缩裁剪，避免贴近格线但未跨格的樱桃、叶片、把手等主体边缘被切掉。每个物品 JSON 写入 `imageViews[]`，同时把第一个视角兼容写入 `imageSrc/imageObjectKey`。
|
||||
11. 将素材图和每张独立视角图片上传到 OSS。每次获得可恢复的图片资产后，都要回写 `match3d_work_profile.generated_item_assets_json`。成功素材状态为 `image_ready`；失败素材保留已成功图片引用并记录 `error`。每个素材 JSON 可继续保存历史 `soundPrompt`；不再写入新的 `backgroundMusicTitle/backgroundMusicStyle/backgroundMusicPrompt`。
|
||||
12. UI 背景生成由 `api-server` 分成两张资产：第一张是 `9:16` 纯背景图，走 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 请求，不传锅参考图，且必须禁止锅、圆盘、托盘、拼图槽、物品槽、HUD、文字、按钮、倒计时、分数和物品；第二张是 `1:1` 题材容器 UI 图，走 VectorEngine `/v1/images/edits` multipart 请求，把 `public/match3d-background-references/pot-fused-reference.png` 作为 `image` part 上传，只生成一个贴合题材设定的圆形或浅盘状竞技容器，不生成整页背景、文字、按钮或物品。容器图必须沿用参考图的大尺寸轻俯视构图：外轮廓接近画布四边，宽度约占 `86%-92%`、高度约占 `82%-90%`，内口为横向椭圆，禁止生成小容器、正俯视圆盘、侧视碗、餐盘或小托盘。纯背景上传到 `generated-match3d-assets/{sessionId}/{profileId}/background/{taskId}/background.png`，容器 UI 图上传到 `generated-match3d-assets/{sessionId}/{profileId}/ui-container/{taskId}/container.png`，两者都作为 `backgroundAsset` 挂在首个 `generatedItemAssets[]` JSON 上；HTTP DTO 同时顶层输出兼容的 `backgroundPrompt`、`backgroundImageSrc`、`backgroundImageObjectKey` 与 `generatedBackgroundAsset`，容器图通过 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey` 返回。若作品尚无用户自定义封面，草稿生成完成后默认把容器 UI 图写入 `coverImageSrc`，作为草稿架和作品信息的默认封面。
|
||||
12. UI 背景生成由 `api-server` 分成两张资产：第一张是 `9:16` 纯背景图，走 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 请求，不传锅参考图，且必须禁止锅、圆盘、托盘、拼图槽、物品槽、HUD、文字、按钮、倒计时、分数和物品；第二张是 `1:1` 题材容器 UI 图，走 VectorEngine `/v1/images/edits` multipart 请求，把 `public/match3d-background-references/pot-fused-reference.png` 作为 `image` part 上传，只生成一个贴合题材设定的圆形或浅盘状竞技容器，不生成整页背景、文字、按钮或物品。容器图必须沿用参考图的大尺寸轻俯视构图：外轮廓接近画布四边，宽度约占 `86%-92%`、高度约占 `82%-90%`，内口为横向椭圆，禁止生成小容器、正俯视圆盘、侧视碗、餐盘或小托盘。容器图入库前必须统一转成带透明 alpha 的 PNG；若上游返回白底、浅色底或抗锯齿底色，`api-server` 在上传 OSS 前清成透明背景。纯背景上传到 `generated-match3d-assets/{sessionId}/{profileId}/background/{taskId}/background.png`，容器 UI 图上传到 `generated-match3d-assets/{sessionId}/{profileId}/ui-container/{taskId}/container.png`，两者都作为 `backgroundAsset` 挂在首个 `generatedItemAssets[]` JSON 上；HTTP DTO 同时顶层输出兼容的 `backgroundPrompt`、`backgroundImageSrc`、`backgroundImageObjectKey` 与 `generatedBackgroundAsset`，容器图通过 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey` 返回。若作品尚无用户自定义封面，草稿生成完成后默认把容器 UI 图写入 `coverImageSrc`，作为草稿架和作品信息的默认封面；草稿架封面解析也应优先使用容器图，其次才是纯背景图和物品图，完全缺失生成图时使用透明参考容器图兜底。
|
||||
13. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息、背景资产信息和默认封面；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 与 `coverImageSrc` 恢复同一批素材、UI 与封面。历史音频字段只做兼容传递。
|
||||
|
||||
若文本模型不可用或返回无法解析，后端必须降级为 `{themeText}抓大鹅`、本地作品描述与本地标签兜底，不阻断素材生成；标签仍通过作品标签生成器优先生成，失败后再用兜底标签补齐。
|
||||
@@ -100,7 +102,7 @@ public/match3d-style-references/painterly-icon.png
|
||||
public/match3d-background-references/pot-fused-reference.png
|
||||
```
|
||||
|
||||
这张图只作为容器 UI 图的 VectorEngine `/v1/images/edits` multipart `image` part，用来锁定“大尺寸轻俯视浅盘容器”的构图。参考图本身是 `1:1` 透明底容器素材，外轮廓接近画布四边，内口为横向椭圆；结果页没有真实生成容器时也只把它作为容器预览兜底，不能再作为 `9:16` 背景预览。每次草稿生成仍会根据 `backgroundPrompt` 生成新的题材化纯背景图；纯背景图不再传入该参考图，也不得生成锅或 UI 元素。
|
||||
这张图只作为容器 UI 图的 VectorEngine `/v1/images/edits` multipart `image` part，用来锁定“大尺寸轻俯视浅盘容器”的构图。参考图本身是 `1:1` 透明底容器素材，外轮廓接近画布四边，内口为横向椭圆；结果页、草稿预览和运行态没有真实生成容器时都把它作为容器兜底，不能再作为 `9:16` 背景预览。每次草稿生成仍会根据 `backgroundPrompt` 生成新的题材化纯背景图；纯背景图不再传入该参考图，也不得生成锅或 UI 元素。
|
||||
|
||||
## 5. OSS 路径
|
||||
|
||||
@@ -140,7 +142,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
|
||||
|
||||
运行态按运行快照中的 `itemTypeId` 稳定排序后，把 `generatedItemAssets` 顺序映射到对应类型。加载某个物品实例时，从该类型素材的 `imageViews[]` 中按实例 id 稳定随机选择一个视角；若历史数据没有 `imageViews[]`，则回退到 `imageSrc/imageObjectKey`。没有生成图片或图片加载失败时，继续使用默认积木图标兜底。
|
||||
|
||||
运行态背景优先读取 `backgroundImageSrc` / 顶层 `generatedBackgroundAsset.imageSrc/imageObjectKey`，为空时从 `generatedItemAssets[].backgroundAsset.imageSrc/imageObjectKey` 兜底。中心容器优先读取顶层 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey`，再读取 `generatedItemAssets[].backgroundAsset.containerImageSrc/containerImageObjectKey`；为空或换签/图片加载失败时继续使用默认圆形容器样式。容器图成功加载后，`Match3DRuntimeShell` 的棋盘容器必须切换为透明、可溢出承载，不再叠加默认 `rounded-full` 圆形锅壳、金色边框和默认径向背景，避免 AI 生成的大尺寸轻俯视容器被裁切或被默认锅视觉覆盖。运行态入口判断是否需要补读作品详情时，只能把 `imageViews[]` 或 `imageSrc/imageObjectKey` 视为“已有物品图片素材”；`backgroundMusic.audioSrc`、`clickSound.audioSrc`、`generatedBackgroundAsset`、`backgroundAsset.image*` 和 `backgroundAsset.containerImage*` 是随物品素材一起传入的附属运行态资产，不能单独证明物品素材已完整。也不能继续只用历史 `modelSrc/modelObjectKey` 判断，否则新 2D 草稿会在试玩或推荐流中被当成“无素材”并回退默认积木。`Match3DRuntimeShell` 只保留顶部返回、倒计时、重开三个控件；这些顶部控件和底部备选栏统一使用题材无关的半透明玻璃组件样式，不能随背景题材改成木质、金属、果园、科幻等主题皮肤，也不能重新烘进 AI 背景图。进度、组数、版本等状态信息不得再作为顶部常驻 UI 出现，避免遮挡生成背景和中心容器。
|
||||
运行态背景优先读取 `backgroundImageSrc` / 顶层 `generatedBackgroundAsset.imageSrc/imageObjectKey`，为空时从 `generatedItemAssets[].backgroundAsset.imageSrc/imageObjectKey` 兜底。中心容器优先读取顶层 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey`，再读取 `generatedItemAssets[].backgroundAsset.containerImageSrc/containerImageObjectKey`；为空或换签/图片加载失败时使用 `public/match3d-background-references/pot-fused-reference.png` 作为透明容器图兜底，不再回退到默认圆形锅壳。容器图成功加载后，`Match3DRuntimeShell` 的棋盘容器必须切换为透明、可溢出承载，不再叠加默认 `rounded-full` 圆形锅壳、金色边框和默认径向背景，避免 AI 生成的大尺寸轻俯视容器被裁切或被默认锅视觉覆盖。移动端棋盘宽度应接近屏幕宽度并居中，容器图片允许略超出棋盘承载盒以保留大尺寸浅盘轮廓。运行态入口判断是否需要补读作品详情时，只能把 `imageViews[]` 或 `imageSrc/imageObjectKey` 视为“已有物品图片素材”；`backgroundMusic.audioSrc`、`clickSound.audioSrc`、`generatedBackgroundAsset`、`backgroundAsset.image*` 和 `backgroundAsset.containerImage*` 是随物品素材一起传入的附属运行态资产，不能单独证明物品素材已完整。也不能继续只用历史 `modelSrc/modelObjectKey` 判断，否则新 2D 草稿会在试玩或推荐流中被当成“无素材”并回退默认积木。`Match3DRuntimeShell` 只保留顶部返回、倒计时、重开三个控件；这些顶部控件和底部备选栏统一使用题材无关的半透明玻璃组件样式，不能随背景题材改成木质、金属、果园、科幻等主题皮肤，也不能重新烘进 AI 背景图。进度、组数、版本等状态信息不得再作为顶部常驻 UI 出现，避免遮挡生成背景和中心容器。
|
||||
|
||||
前端加载规则：
|
||||
|
||||
@@ -184,7 +186,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
|
||||
1. `作品名称` 对应 Match3D `gameName`。
|
||||
2. `作品描述` 对应 Match3D `summary`，草稿生成阶段由同一次作品生成计划自动填入。
|
||||
3. `作品标签` 对应 Match3D `tags`，草稿生成阶段在写入名称和描述后自动调用标签生成器填入；结果页仍允许用户继续编辑或再次 AI 生成。
|
||||
4. 封面图与作品名称不再拆成左右两个大模块；封面只作为同一 Tab 内的可选入口，避免和作品基础信息割裂。旧称“碰面图”统一改为“封面图”。草稿生成默认使用生成出的中心容器 UI 图作为 `coverImageSrc`。点击封面图必须弹出独立编辑面板，不允许在当前作品信息面板下方展开。封面面板布局对齐拼图创作页上传卡：移动端优先，左侧/上方为方形预览卡，预览卡本身就是上传热区；上传图片后，预览卡内出现和拼图入口一致的 `AI重绘` 开关与删除按钮，面板底部不再额外展示旧 `AI重绘` 选项。已有上传图时，右侧/下方输入框标题为 `AI重绘要求`；关闭 AI 重绘时只把上传图 Data URL 写入封面字段，不调用生图模型。没有上传图时，输入框标题为 `封面描述`，可选择多张参考图后调用 VectorEngine `gpt-image-2-all` 文生图链路，参考图通过请求体 `image` 数组传入；参考图来源支持直接引用 `物品素材` / `UI素材` 中已有图片，也支持自定义上传。上传图 AI 重绘与无上传图多参考图生成都通过 `api-server` 的 Match3D 作品封面生成接口完成，生成结果转存到 `generated-match3d-assets/{sessionId}/{profileId}/cover/{taskId}/cover.png` 后再写回 `coverImageSrc`。
|
||||
4. 封面图修改归入发布面板，不再作为 `作品信息` Tab 内的独立入口。结果页底部 `发布` 按钮对齐拼图：非忙碌态始终可点击，点击后打开独立 `发布抓大鹅作品` 面板；面板上方集中展示发布检查和阻断项，面板内承载封面编辑，满足门槛后再点击 `发布到广场`。旧称“碰面图”统一改为“封面图”。草稿生成默认使用生成出的中心容器 UI 图作为 `coverImageSrc`。封面编辑布局对齐拼图创作页上传卡：移动端优先，左侧/上方为方形预览卡，预览卡本身就是上传热区；上传图片后，预览卡内出现和拼图入口一致的 `AI重绘` 开关与删除按钮，面板底部不再额外展示旧 `AI重绘` 选项。已有上传图时，右侧/下方输入框标题为 `AI重绘要求`；关闭 AI 重绘时只把上传图 Data URL 写入封面字段，不调用生图模型。没有上传图时，输入框标题为 `封面描述`，可选择多张参考图后调用 VectorEngine `gpt-image-2-all` 文生图链路，参考图通过请求体 `image` 数组传入；参考图来源支持直接引用 `物品素材` / `UI素材` 中已有图片，也支持自定义上传。上传图 AI 重绘与无上传图多参考图生成都通过 `api-server` 的 Match3D 作品封面生成接口完成，生成结果转存到 `generated-match3d-assets/{sessionId}/{profileId}/cover/{taskId}/cover.png` 后只写回 `coverImageSrc` / `coverAssetId` 相关字段。封面生成或上传后发布面板保持打开，方便继续完成发布。封面生成接口不得复用草稿编译流程，不得重算题材、难度、消除次数或 `generated_item_assets_json`；前端收到封面生成回包时也只能把 `coverImageSrc` 合并到当前结果页 profile，不能用回包中的旧 `generatedItemAssets`、`clearCount` 或 `difficulty` 覆盖当前页面状态。
|
||||
|
||||
结果页 `难度配置` Tab 取代旧 `玩法配置`，不再展示旧的分散输入项。该 Tab 顶部使用横向离散拖动条调整难度，四个刻度分别为 `轻松 / 标准 / 进阶 / 硬核`；拖动条只能落在这四个点上，刻度标签可点击切换。该 Tab 必须与创作入口页使用同一组难度选项，并统一把原“类型素材图片 / 局内类型”等口径归一为 `物品种类`：
|
||||
|
||||
@@ -211,7 +213,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
|
||||
2. 素材名称输入。
|
||||
3. 不展示点击音效提示词输入或点击音效生成入口。
|
||||
|
||||
五视角预览区采用“上方大预览 + 底部缩略图栏”的布局：上方是方形焦点预览区，中间横向排列当前物品的各视角图片，并用内框标出当前焦点；底部缩略图栏固定露出 `4` 个方形槽位，多出的第 `5` 个视角通过横向滚动访问。点击缩略图只切换焦点视角，不在面板内新增说明文案或额外规则区。
|
||||
五视角预览区采用“上方大预览 + 底部缩略图栏”的布局：上方方形焦点预览区只显示当前选中的单张大图，用于详细查看物品形象，图片在方格内放大显示，不再渲染素材自带缩略图框、焦点内框或横向五图带；底部缩略图栏固定露出 `4` 个方形槽位，多出的第 `5` 个视角通过横向滚动访问。点击缩略图只切换焦点视角，不在面板内新增说明文案或额外规则区。
|
||||
|
||||
详情页不再展示参考图、用途、模型提示词、文生/图生切换、状态查询、下载列表、taskUuid 或 subscriptionKey。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user