GenarrativeAI/Genarrative
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update Match3D/image-generation docs & code

Browse Source 
Adds/updates documentation, assets and implementation for Match3D and puzzle image generation workflows. Key changes: decision logs and pitfalls updated to prefer VectorEngine Gemini for Match3D material sheets and to require edits (multipart) for 1:1 container reference images; guidance added for when to use APIMart vs VectorEngine. .env.example clarified APIMart/Responses config. Many new public assets and PPT visuals added. Code changes across frontend and backend: updated shared contracts, server-rs match3d/puzzle/image-generation handlers, VectorEngine/OpenAI image generation clients, and multiple React components/tests to handle UI/background/container image signing, edits workflow, and puzzle UI background resolution. Added src/services/puzzle-runtime/puzzleUiBackgroundSource.ts and related test updates. Includes notes about multipart HTTP/1.1 requirement and test/verification commands in docs.
This commit is contained in:
高物
2026-05-14 20:34:45 +08:00
parent d33c937ebc
commit 548db78ca7
103 changed files with 6687 additions and 3270 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md
View File

@@ -18,7 +18,7 @@
1. 入口表单只展示 `画面描述`、参考图和图片模型选择；`画面描述` 是唯一必填字段。
2. 表单自动保存只保存 `pictureDescription`，不再保存入口作品名称、作品描述或推断标签。
3. 点击“生成草稿”后进入生成进度页，步骤固定对齐后端当前编排：“编译首关草稿 -> 生成关卡名称 / 生成首关画面 -> 生成背景音乐 / 生成UI背景 -> 写入正式草稿”。其中关卡名称文本生成与首关画面生成可并行；首关最终名称确定后，背景音乐与 UI 背景必须并行启动。
3. 点击“生成草稿”后进入生成进度页，步骤固定对齐后端当前编排：“编译首关草稿 -> 生成关卡名称与 UI 背景提示词 / 生成首关画面 -> 生成UI背景 -> 写入正式草稿”。其中关卡名称文本生成、UI 背景提示词生成与首关画面生成可并行；首关最终名称确定后生成 UI 背景。背景音乐生成已于 2026-05-14 临时关闭。
4. 生成进度页“当前拼图信息”只展示画面描述；不得展示空作品名称、空作品描述或旧五锚点结构。
5. 结果页打开后，作品名称默认使用首关名称，作品描述与作品标签保持为空，等待用户在作品信息 Tab 补全或触发 AI 标签生成。
@@ -90,8 +90,8 @@
12. `compile_puzzle_draft` 中的图片上游失败不得映射成 `400 BAD_REQUEST`。DashScope 返回 `InvalidParameter` 或任务失败时，api-server 统一按 `502 UPSTREAM_ERROR` 暴露，并在 `details.message` 中保留“拼图图片生成失败：...”的业务原因，避免生成页只显示“请求参数不合法”。
13. `compile_puzzle_draft` 前置泥点预扣失败不得映射成 `400 BAD_REQUEST`。余额不足返回 `409 CONFLICT`，SpacetimeDB procedure 不可用、绑定不匹配、钱包服务异常等统一按 `502 UPSTREAM_ERROR` 暴露，并在 `details.message` 中保留真实钱包错误。
14. 生成拼图作品草稿动作涉及的表单 seed prompt 与首图 prompt 来源选择统一收口在 `server-rs/crates/api-server/src/prompt/puzzle/draft.rs`；`puzzle.rs` 只负责调用 SpacetimeDB、计费、图片服务和持久化，不再直接拼草稿 prompt 文本。
15. `compile_puzzle_draft_with_initial_cover` 中，首关文本名称生成与首关图片生成互不等待：首图 prompt 只读取画面描述，OSS 临时路径使用已有名或确定性兜底名；首图返回后再用图片语义尝试精修最终关卡名。最终关卡名确定后，必须继续生成首关 UI 背景图与背景音乐，并在写入正式草稿前校验 `levels[0].uiBackgroundImageSrc/uiBackgroundImageObjectKey` 与 `levels[0].backgroundMusic.audioSrc` 都不为空；任一资产失败时 `compile_puzzle_draft` 返回上游错误，生成页停留失败态，不能返回一个显示“暂无音乐”或默认 UI 的成功草稿。
16. `compile_puzzle_draft_with_uploaded_cover` 中，上传图解析后，文本名称生成、图片语义名称生成和上传图转存 OSS 可并行；上传图转存失败必须立即返回，不得继续触发背景音乐或 UI 背景生成。上传图转存成功且最终关卡名确定后，同样必须生成并校验首关 UI 背景图与背景音乐。自动草稿阶段先生成 UI 背景，再生成会单独扣费的音乐资产，避免 UI 失败后留下未写入草稿的已扣费音频。
15. `compile_puzzle_draft_with_initial_cover` 中，首关文本名称生成与首关图片生成互不等待：首图 prompt 只读取画面描述，OSS 临时路径使用已有名或确定性兜底名；同一次首关命名 LLM 请求必须返回 `levelName` 与 `uiBackgroundPrompt`，首图返回后再用图片语义尝试精修最终关卡名与 UI 背景提示词。最终关卡名确定后，必须继续用 AI 返回的 `uiBackgroundPrompt` 生成首关 UI 背景图；若命名模型未返回可用提示词，才按作品、关卡和标签拼接确定性兜底提示词。写入正式草稿前校验 `levels[0].uiBackgroundImageSrc/uiBackgroundImageObjectKey` 不为空；UI 背景失败时 `compile_puzzle_draft` 返回上游错误，生成页停留失败态。背景音乐生成临时关闭，不再作为草稿完成门槛。
16. `compile_puzzle_draft_with_uploaded_cover` 中，上传图解析后，文本名称生成、图片语义名称生成和上传图转存 OSS 可并行；上传图转存失败必须立即返回，不得继续触发 UI 背景生成。上传图转存成功且最终关卡名确定后，同样必须生成并校验首关 UI 背景图。自动草稿阶段不再触发音乐资产生成。
## 结果页
@@ -99,22 +99,24 @@
1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、生成或重新生成画面，并在已有正式图后支持关卡测试。
2. 作品信息：展示并编辑作品名称、作品描述、作品标签。
3. 素材配置：对齐抓大鹅草稿页结构，内部包含 `UI` 与 `背景音乐` 子 Tab。
3. 素材配置：对齐抓大鹅草稿页结构，当前只包含 `UI` 子 Tab；`背景音乐` 子 Tab 已临时隐藏。
`素材配置 > UI` 展示并编辑拼图运行态 UI 背景提示词。`compile_puzzle_draft` 草稿编译完成首图和背景音乐后，`api-server` 会基于作品名称、作品描述、标签和首关信息自动生成首关 9:16 纯背景图；结果页继续支持用户修改提示词并通过 `generate_puzzle_ui_background` 重新生成。图片生成调用 VectorEngine `gpt-image-2-all` 的 `9:16` 图片生成链路。生成结果写入首关 `levels_json` 的 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`，不新增 SpacetimeDB 表字段。
`素材配置 > UI` 展示并编辑拼图运行态 UI 背景提示词。`compile_puzzle_draft` 草稿编译完成首图后，`api-server` 会优先使用首关命名 LLM 同次返回的 `uiBackgroundPrompt` 自动生成首关 9:16 纯背景图；只有模型未返回可用提示词时，才基于作品名称、作品描述、标签和首关信息拼接兜底提示词。结果页继续支持用户修改提示词并通过 `generate_puzzle_ui_background` 重新生成。图片生成调用 VectorEngine `gpt-image-2-all` 的 `9:16` 图片生成链路。生成结果写入首关 `levels_json` 的 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`，不新增 SpacetimeDB 表字段。
`素材配置 > 背景音乐` 编辑并生成背景音乐，音乐资产暂存到首关 `levels_json[0].backgroundMusic`。拼图结果页不再保留一级 `UI` 或一级 `音乐` Tab。
历史 `levels_json[0].backgroundMusic` 字段继续兼容读取和运行态播放，但结果页暂不提供编辑或生成入口。拼图结果页不再保留一级 `UI` 或一级 `音乐` Tab。
### 2026-05-12 UI 背景生成补充
1. UI 背景图只生成拼图运行态的题材氛围纯背景，不得把拼图槽、棋盘外框、按钮、HUD 或其它 UI 元素烘进图片。拼图槽位、棋盘边框和空格继续使用运行态默认样式绘制。
2. UI 背景图不得生成文字、水印、按钮文字、数字、拼图碎片、完整拼图图像、教程浮层、拼图槽或物品槽，避免与真实拼图图块和运行态 HUD 混淆。
3. 结果页 UI Tab 支持直接修改提示词并重新生成；点击生成前会把本地首关 `uiBackgroundPrompt` 同步进 `levelsJson`，使自动保存尚未完成时后端仍能拿到最新提示词。
3. 结果页 UI Tab 支持直接修改提示词并重新生成；点击生成前必须先弹出 `确认消耗泥点` 面板并展示 `消耗 2 泥点`，确认后会把本地首关 `uiBackgroundPrompt` 同步进 `levelsJson`，使自动保存尚未完成时后端仍能拿到最新提示词。
4. 草稿编译阶段自动生成 UI 背景失败时必须让 `compile_puzzle_draft` 失败并停留在生成页；不能保留一个成功状态但缺少 UI 背景的草稿。只有结果页内用户主动点击 `生成UI背景` 或 `重新生成` 时，失败才作为当前面板错误展示，由用户手动重试。
5. `api-server` 负责拼接生成 prompt、调用 VectorEngine、下载并转存 OSS；SpacetimeDB 只通过 `save_puzzle_ui_background` procedure 保存结果，不做外部 I/O。
6. 拼图运行态读取 `currentLevel.uiBackgroundImageSrc` 渲染为全屏背景；无 UI 背景图时继续使用原封面模糊背景兜底。棋盘本身仍由正式拼图图生成，不能把 UI 背景当作拼图切块来源。
7. 生成完成后的自动试玩和结果页“试玩”走前端本地运行态兜底时，`startLocalPuzzleRun` 也必须从 `PuzzleWorkSummary.levels[]` 复制 `uiBackgroundImageSrc` 与 `backgroundMusic` 到 `currentLevel`；不得只带 `coverImageSrc`，否则草稿结果页有背景但试玩局内空白。
6. 拼图运行态读取 `currentLevel.uiBackgroundImageSrc` 渲染为全屏背景；若 `uiBackgroundImageSrc` 为空，则必须回退读取 `uiBackgroundImageObjectKey` 并交给 `/api/assets/read-url` 换签；无 UI 背景图时继续使用原封面模糊背景兜底。棋盘本身仍由正式拼图图生成，不能把 UI 背景当作拼图切块来源。
7. 生成完成后的自动试玩和结果页“试玩”走前端本地运行态兜底时，`startLocalPuzzleRun` 也必须从 `PuzzleWorkSummary.levels[]` 复制 `uiBackgroundImageSrc` / `uiBackgroundImageObjectKey` 与 `backgroundMusic` 到 `currentLevel`；不得只带 `coverImageSrc`，否则草稿结果页有背景但试玩局内空白。
8. 结果页在本地关卡处于 `generationStatus = generating` 时合并后端生成完成回包，必须同时合并 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey` 与 `backgroundMusic`。若只合并图片字段而漏掉音乐字段，随后自动保存会把空 `backgroundMusic` 写回 `puzzle_work_profile.levels_json`，导致素材配置显示“暂无音乐”并让自动试玩/试玩局内无音乐。
9. 结果页手动点击 `生成UI背景` / `重新生成` 时，如果目标 SpacetimeDB wasm 尚未发布到包含 `consume_profile_wallet_points_and_return`、`refund_profile_wallet_points_and_return` 或 `save_puzzle_ui_background` 的版本，`api-server` 必须把 `No such procedure` 视为后端版本漂移：泥点预扣阶段降级跳过扣费，UI 背景已经生成但保存失败时返回本次内存合成草稿快照，不能把原始 `No such procedure` 暴露到草稿页。该容错只保证当前页面可见本次图片；刷新后要稳定恢复仍必须重新发布最新 SpacetimeDB module 并重新生成 bindings。
10. 结果页 `UI背景提示词` 文本框只能展示后端已持久化的 `levels[0].uiBackgroundPrompt` 或用户正在编辑的本地值；后端字段为空时不得把前端兜底提示词直接填入文本框，避免把兜底模板误展示成 AI 已生成提示词。点击生成时仍可用同一兜底提示词作为空输入兜底。
### 2026-05-12 草稿生成完成自动试玩补充
@@ -145,7 +147,7 @@
1. 关卡详情页的 `画面图` 与 `画面描述` 模块对齐入口页拼图表单：画面图使用稳定正方形图卡，画面描述使用固定高度输入区并保留图片模型选择。
2. 新建关卡或无正式图关卡也展示 `画面图` 图卡；空图态只保留图标化占位和生成中状态，不追加规则说明文案。
3. 关卡详情页删除手填 `参考图链接或资产ID` 输入框。参考图只能通过本地上传或历史拼图素材选择进入本次生成请求；字段 `levels[].pictureReference` 继续作为后端生成后的复用字段透传，不作为用户可手填表单项。
4. 单关生成等待估算从 `30` 秒调整为 `90` 秒；生成按钮内展示小字 `等待时间可以制作更多关卡哦~`，不得另起说明面板。
4. 单关生成等待估算从 `30` 秒调整为 `90` 秒；生成按钮内展示小字 `等待时间可以制作更多关卡哦~`，不得另起说明面板。点击 `生成画面` / `重新生成画面` 前必须先弹出 `确认消耗泥点` 面板并展示 `消耗 2 泥点`。
5. 触发某一关生成时，前端必须立即把该关 `generationStatus` 标为 `generating` 并随当前 `levelsJson` 写入草稿自动保存链路；后端生成完成后再写回 `ready`。
6. `generationStatus = generating` 的关卡在详情弹窗关闭后仍保留进度展示，再次打开同一关详情能继续看到生成进度；关卡列表卡片也必须展示生成中的轻量状态。
7. 单关图片生成必须作为后台 action 执行，不占用拼图结果页全局 busy 状态；生成期间仍允许编辑作品信息、编辑关卡、新增关卡、删除其他关卡、关卡测试和继续触发其他可并行动作。
@@ -157,9 +159,9 @@
## 验收
1. 从拼图创作入口只能看到作品名称、作品描述、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择、背景音乐生成和首关 UI 背景图生成。
2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择和首关 UI 背景图生成。
3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图；作品详情页展示玩家作品描述。
4. 结果页包含“拼图关卡”“作品信息”“素材配置”三个一级 Tab；`素材配置` 内包含 `UI` 和 `背景音乐` 子 Tab。关卡列表默认至少一关，支持新增、删除和进入关卡详情。
4. 结果页包含“拼图关卡”“作品信息”“素材配置”三个一级 Tab；`素材配置` 内当前只包含 `UI` 子 Tab，不展示背景音乐生成入口。关卡列表默认至少一关，支持新增、删除和进入关卡详情。
5. 关卡详情页支持生成或重新生成画面；已有正式图后显示吸底“关卡测试”入口。
6. 发布、作品测试、自动保存作品名称、作品描述、作品标签和关卡列表仍可用。
7. 草稿初次生成后首关默认带 `uiBackgroundImageSrc`；UI Tab 可修改提示词并重新生成背景图；生成后运行态应显示 `uiBackgroundImageSrc`，拼图槽位和棋盘边界仍由默认运行态样式绘制。
7. 草稿初次生成后首关默认带 `uiBackgroundImageSrc`；若后端只返回 `uiBackgroundImageObjectKey` 也必须能在结果页、试玩和运行态正常预览；UI Tab 可修改提示词并重新生成背景图；生成后运行态应显示 `uiBackgroundImageSrc` 或换签后的 `uiBackgroundImageObjectKey`，拼图槽位和棋盘边界仍由默认运行态样式绘制。