1

docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md

@@ -0,0 +1,89 @@
+# 拼图与抓大鹅结果页音乐 Tab 2026-05-11
+
+## 1. 范围
+
+本方案把 VectorEngine 音频生成能力从视觉小说结果页扩展到拼图与抓大鹅结果页：
+
+1. 拼图结果页新增 `音乐` Tab，支持通过 Suno 生成作品背景音乐。
+2. 抓大鹅结果页新增 `音乐` Tab，支持通过 Suno 生成作品背景音乐。
+3. 抓大鹅 `3D素材` Tab 支持为每个生成物体通过 Vidu 生成点击音效。
+
+本轮不新增 SpacetimeDB 表，不修改表字段，不把供应商密钥下发到前端。
+
+## 2. 通用音频接口
+
+后端在既有视觉小说音频路由外新增通用创作音频路由：
+
+| 方法 | 路由 | 用途 |
+| --- | --- | --- |
+| `POST` | `/api/creation/audio/background-music` | 提交 Suno 背景音乐任务 |
+| `POST` | `/api/creation/audio/background-music/{task_id}/asset` | 查询并转存 Suno 音频资产 |
+| `POST` | `/api/creation/audio/sound-effect` | 提交 Vidu 音效任务 |
+| `POST` | `/api/creation/audio/sound-effect/{task_id}/asset` | 查询并转存 Vidu 音效资产 |
+
+通用转存请求由前端传入 `entityKind`、`entityId`、`slot`、`assetKind`、`profileId`。后端仍负责：
+
+1. 校验 VectorEngine 与 OSS 环境变量。
+2. 轮询供应商任务结果。
+3. 下载音频字节。
+4. 写入 OSS 私有对象。
+5. 确认 `asset_object` 并绑定 `asset_entity_binding`。
+
+视觉小说原路由保持兼容，内部继续复用同一套提交、轮询、转存逻辑。
+
+## 3. 数据落点
+
+### 3.1 拼图
+
+拼图作品没有独立作品级 metadata 字段。背景音乐随 `levels_json` 保存到首个 `PuzzleDraftLevel.backgroundMusic`：
+
+```json
+{
+  "levelId": "puzzle-level-1",
+  "backgroundMusic": {
+    "taskId": "suno-task",
+    "provider": "vector-engine-suno",
+    "assetObjectId": "assetobj_1",
+    "assetKind": "puzzle_background_music",
+    "audioSrc": "/generated-puzzle-assets/..."
+  }
+}
+```
+
+运行态后续可从当前关卡快照或作品详情读取该字段作为背景音乐源；若字段为空，继续使用现有程序化背景音乐兜底。
+
+### 3.2 抓大鹅
+
+抓大鹅作品级音频与物体点击音效复用 `generated_item_assets_json` 数组保存，不新增表字段：
+
+1. 作品背景音乐暂存到第一个 `Match3DGeneratedItemAsset.backgroundMusic`，表示当前 work profile 的作品级背景音乐。
+2. 单个物体点击音效保存到对应 `Match3DGeneratedItemAsset.clickSound`。
+
+这是一个兼容性折中：当前 Match3D work profile 没有 work-level metadata 字段，而 `generated_item_assets_json` 已经随作品详情、草稿架、运行态入口稳定传递。后续若新增正式作品 metadata 表达，应迁移 `backgroundMusic` 到作品级字段。
+
+## 4. 前端交互
+
+结果页 UI 保持轻量：
+
+1. `音乐` Tab 只展示必要输入、生成按钮、状态与音频预览，不展示供应商规则说明。
+2. 生成完成后立即写回本地草稿状态，并触发既有保存链路或专用保存接口。
+3. 抓大鹅每个物体音效生成入口放在对应素材详情面板内，不在列表下方展开大段配置。
+
+## 5. 验收
+
+建议执行：
+
+```powershell
+npm run check:encoding
+npm run test -- src\components\puzzle-result\PuzzleResultView.test.tsx
+npm run test -- src\components\match3d-result\Match3DResultView.test.tsx
+npm run typecheck
+cargo test -p shared-contracts creation_audio --manifest-path server-rs\Cargo.toml
+cargo test -p shared-contracts puzzle --manifest-path server-rs\Cargo.toml
+cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml
+cargo test -p api-server vector_engine_audio_generation --manifest-path server-rs\Cargo.toml
+cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml
+cargo check -p api-server --manifest-path server-rs\Cargo.toml
+```
+
+真实生成 smoke 需要本地私密环境配置 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 与 OSS 变量。后端改动后使用 `npm run api-server` 启动，并确认 `/healthz`。