Update Match3D/image-generation docs & code
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:
@@ -1,20 +1,33 @@
|
||||
# 拼图与抓大鹅结果页音乐入口 2026-05-11
|
||||
|
||||
> 2026-05-14 临时关闭：拼图与抓大鹅草稿生成阶段不再自动生成背景音乐；拼图结果页 `素材配置` 只保留 `UI` 子 Tab；抓大鹅结果页 `素材配置` 只保留 `物品` 与 `UI` 子 Tab，物品详情不展示点击音效生成入口。通用 `/api/creation/audio/*` 路由对拼图与抓大鹅目标暂时返回 `410 Gone`；视觉小说专用音频路由不受本次关闭影响。
|
||||
|
||||
## 0. 2026-05-14 临时关闭口径
|
||||
|
||||
拼图与抓大鹅的创作音频生成入口暂时关闭：
|
||||
|
||||
1. 拼图草稿编译阶段不再自动生成背景音乐，只生成首图与 UI 背景。
|
||||
2. 抓大鹅草稿编译阶段不再自动生成背景音乐，也不再生成物品点击音效。
|
||||
3. 拼图结果页 `素材配置` 只保留 `UI` 子 Tab，隐藏 `背景音乐` 子 Tab 与重新生成入口。
|
||||
4. 抓大鹅结果页 `素材配置` 只保留 `物品` 与 `UI` 子 Tab，物品详情隐藏点击音效生成入口。
|
||||
5. 通用 `/api/creation/audio/*` 路由对拼图与抓大鹅目标暂时返回 `410 Gone`；视觉小说专用音频路由保持可用。
|
||||
6. 既有草稿或作品中的 `backgroundMusic` / `clickSound` 字段不清空，运行态仍按历史兼容逻辑播放已存在的音频。
|
||||
|
||||
## 1. 范围
|
||||
|
||||
本方案把 VectorEngine 音频生成能力从视觉小说结果页扩展到拼图与抓大鹅结果页：
|
||||
本方案记录 VectorEngine 音频生成能力曾从视觉小说结果页扩展到拼图与抓大鹅结果页；当前拼图与抓大鹅入口已临时关闭：
|
||||
|
||||
1. 拼图结果页在 `素材配置 > 背景音乐` 中支持通过 Suno 生成作品背景音乐；旧一级 `音乐` Tab 已删除。
|
||||
2. 抓大鹅结果页在 `素材配置 > 背景音乐` 中支持通过 Suno 生成作品背景音乐；旧一级 `音乐` Tab 已删除。
|
||||
3. 抓大鹅 `素材配置 > 物品` 支持为每个生成物体通过 Vidu 手动生成点击音效；创作入口不展示点击音效生成开关。
|
||||
1. 拼图结果页不展示 `素材配置 > 背景音乐`，旧一级 `音乐` Tab 继续删除。
|
||||
2. 抓大鹅结果页不展示 `素材配置 > 背景音乐`，旧一级 `音乐` Tab 继续删除。
|
||||
3. 抓大鹅 `素材配置 > 物品` 详情面板不展示点击音效生成入口。
|
||||
4. 拼图运行态与抓大鹅运行态内置默认关卡音频配置：通用点击音效 `/audio/ui-click-soft.wav`、过关音效 `/audio/ui-level-clear.wav`、倒计时临界音效 `/audio/ui-countdown-warning.wav`。
|
||||
5. 拼图和抓大鹅草稿生成阶段会自动生成背景音乐并转存 OSS，结果页继续支持试听和重新生成。
|
||||
5. 拼图和抓大鹅草稿生成阶段不生成背景音乐，也不因缺少背景音乐阻塞草稿完成。
|
||||
|
||||
本轮不新增 SpacetimeDB 表，不修改表字段，不把供应商密钥下发到前端。
|
||||
|
||||
## 2. 通用音频接口
|
||||
|
||||
后端在既有视觉小说音频路由外新增通用创作音频路由：
|
||||
后端在既有视觉小说音频路由外曾新增通用创作音频路由。临时关闭期间，以下通用路由保留；对拼图或抓大鹅目标直接返回 `410 Gone`，不得被拼图或抓大鹅入口继续调用：
|
||||
|
||||
| 方法 | 路由 | 用途 |
|
||||
| --- | --- | --- |
|
||||
@@ -32,7 +45,7 @@
|
||||
5. 确认 `asset_object` 并绑定 `asset_entity_binding`。
|
||||
6. 音频真正可下载并准备转存时，按 `taskId + assetKind + entityId + slot` 幂等扣费；背景音乐固定扣除 `5` 泥点，物品点击音效固定扣除 `10` 泥点。任务仍在处理中不扣费，转存或资产绑定失败自动退款。
|
||||
|
||||
通用背景音乐提交允许 `prompt = ""`。拼图和抓大鹅草稿生成都按纯音乐处理：后端提交 Suno 时固定带 `make_instrumental = true`，只用 `title` 和 `tags` 约束作品气质，不把歌词或规则描述写入 prompt。视觉小说原路由保持兼容，内部继续复用同一套提交、轮询、转存逻辑。
|
||||
通用背景音乐提交历史上允许 `prompt = ""`。当前通用创作音频入口被后端显式熔断，不能通过该路由继续提交或转存音频。视觉小说专用路由保持兼容，内部继续复用同一套提交、轮询、转存逻辑。
|
||||
|
||||
## 3. 数据落点
|
||||
|
||||
@@ -53,7 +66,7 @@
|
||||
}
|
||||
```
|
||||
|
||||
草稿生成阶段在生成首关作品题目后，使用作品题目作为 Suno `title`，`prompt` 为空，`tags` 使用轻快、拼图、循环、instrumental。自动草稿编译必须拿到可播放的 `backgroundMusic.audioSrc` 后才返回成功；生成失败应返回上游错误并停留在生成页，不能进入结果页后显示“暂无音乐”。运行态从 `PuzzleRuntimeLevelSnapshot.backgroundMusic.audioSrc` 读取该字段作为背景音乐源，游戏开始后自动循环播放；历史草稿或手动删除音乐时字段为空，则保持静默背景音乐兜底。
|
||||
当前草稿生成阶段跳过背景音乐生成；自动草稿编译只校验首图与 UI 背景。运行态仍兼容历史 `PuzzleRuntimeLevelSnapshot.backgroundMusic.audioSrc`，旧草稿若已有音乐可继续播放；新草稿默认保持静默背景音乐兜底。
|
||||
|
||||
### 3.2 抓大鹅
|
||||
|
||||
@@ -62,18 +75,16 @@
|
||||
1. 作品背景音乐暂存到第一个 `Match3DGeneratedItemAsset.backgroundMusic`，表示当前 work profile 的作品级背景音乐。
|
||||
2. 单个物体点击音效保存到对应 `Match3DGeneratedItemAsset.clickSound`。
|
||||
|
||||
这是一个兼容性折中：当前 Match3D work profile 没有 work-level metadata 字段，而 `generated_item_assets_json` 已经随作品详情、草稿架、运行态入口稳定传递。草稿生成阶段的文本计划在生成物品名称时同步生成 `backgroundMusic.title` 作为背景音乐名称，`backgroundMusic.prompt` 固定为空字符串，后端用该名称作为 Suno `title` 并生成纯音乐。自动草稿编译必须把生成后的 `backgroundMusic.audioSrc` 写回首个素材后才返回成功；若 Suno 提交、轮询、下载、OSS 转存或资产绑定失败，本次草稿生成返回失败并允许用户重试同一 session/profile。后续若新增正式作品 metadata 表达，应迁移 `backgroundMusic` 到作品级字段。
|
||||
这是一个兼容性折中：当前 Match3D work profile 没有 work-level metadata 字段，而 `generated_item_assets_json` 已经随作品详情、草稿架、运行态入口稳定传递。当前草稿生成阶段不再生成 `backgroundMusic` 或 `clickSound`；历史草稿中已有字段仍按旧兼容逻辑传递到运行态。后续若重新打开音频能力或新增正式作品 metadata 表达，应迁移 `backgroundMusic` 到作品级字段。
|
||||
|
||||
## 4. 前端交互
|
||||
|
||||
结果页 UI 保持轻量：
|
||||
|
||||
1. 拼图 `素材配置 > 背景音乐` 与抓大鹅 `素材配置 > 背景音乐` 只展示必要输入、生成按钮、状态与音频预览，不展示供应商规则说明。
|
||||
1. 拼图与抓大鹅结果页暂不展示背景音乐生成输入、生成按钮、状态和音频预览。
|
||||
2. 生成完成后立即写回本地草稿状态，并触发既有保存链路或专用保存接口。
|
||||
3. 抓大鹅每个物体音效生成入口放在对应素材详情面板内，不在列表下方展开大段配置。
|
||||
4. 抓大鹅物体音效提示词允许在素材详情面板内编辑；背景音乐只允许在 `素材配置 > 背景音乐` 编辑曲名和风格，生成请求固定使用空 `prompt`。
|
||||
5. 背景音乐和物体音效生成期间都显示进度条，生成完成后展示 audio 控件试听。
|
||||
6. 背景音乐重新生成只要求曲名非空；重新生成继续按纯音乐提交，`prompt = ""`，按钮展示 `5` 泥点成本。
|
||||
3. 抓大鹅每个物体详情面板只保留素材查看和名称编辑，不展示音效提示词或生成入口。
|
||||
4. 若历史素材已有 `backgroundMusic` 或 `clickSound`，结果页不提供重新生成入口；试玩和运行态仍可消费已存在字段。
|
||||
|
||||
### 4.1 运行态默认点击音效
|
||||
|
||||
@@ -89,11 +100,11 @@
|
||||
|
||||
2026-05-13 修正：
|
||||
|
||||
1. 拼图 `素材配置 > 背景音乐` 的试听控件也必须通过 `useResolvedAssetReadUrl` 对 generated legacy path 换签后再设置 `<audio src>`；签名未就绪或失败时只显示“音频已绑定”，不得把裸 `/generated-puzzle-assets/...` 路径交给浏览器请求。
|
||||
2. 抓大鹅结果页已使用同一换签口径，后续新增音频试听入口必须复用该模式。
|
||||
1. 拼图 `素材配置 > 背景音乐` 的试听控件当前隐藏；后续恢复时必须通过 `useResolvedAssetReadUrl` 对 generated legacy path 换签后再设置 `<audio src>`。
|
||||
2. 抓大鹅结果页后续恢复音频试听入口时必须复用同一换签口径，不能把裸 `/generated-match3d-assets/...` 音频路径直接交给 `<audio>`。
|
||||
3. 拼图和抓大鹅运行态在开局时会尝试自动播放背景音乐；若浏览器因自动播放策略拒绝，玩家首次按下拼图块或点击抓大鹅物品时必须再次调用同一个背景音乐播放函数，避免草稿音乐已经传入运行态但局内始终无声。
|
||||
4. 播放失败仍只做静默兜底，不弹出规则说明或阻断局内交互。
|
||||
5. 拼图结果页合并后端生成完成回包时，若本地首关仍处于 `generationStatus = generating`，必须把 `backgroundMusic` 与候选图、正式图、UI 背景一起合并进编辑态；否则音乐面板会继续显示“暂无音乐”，后续自动保存还会把空音乐写回 profile。
|
||||
5. 拼图结果页合并后端生成完成回包时，若本地首关仍处于 `generationStatus = generating`，必须保留回包中的历史 `backgroundMusic` 字段，避免自动保存把旧音频覆盖为空；该字段不再驱动可见音乐面板。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
|
||||
Reference in New Issue
Block a user