Genarrative/docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md

拼图与抓大鹅结果页音乐入口 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 音频生成能力曾从视觉小说结果页扩展到拼图与抓大鹅结果页；当前拼图与抓大鹅入口已临时关闭：

1. 拼图结果页不展示 素材配置 > 背景音乐，旧一级 音乐 Tab 继续删除。
2. 抓大鹅结果页不展示 素材配置 > 背景音乐，旧一级 音乐 Tab 继续删除。
3. 抓大鹅 素材配置 > 物品 详情面板不展示点击音效生成入口。
4. 拼图运行态与抓大鹅运行态内置默认关卡音频配置：通用点击音效 /audio/ui-click-soft.wav、过关音效 /audio/ui-level-clear.wav、倒计时临界音效 /audio/ui-countdown-warning.wav。
5. 拼图和抓大鹅草稿生成阶段不生成背景音乐，也不因缺少背景音乐阻塞草稿完成。

本轮不新增 SpacetimeDB 表，不修改表字段，不把供应商密钥下发到前端。

2. 通用音频接口

后端在既有视觉小说音频路由外曾新增通用创作音频路由。临时关闭期间，以下通用路由保留；对拼图或抓大鹅目标直接返回 410 Gone，不得被拼图或抓大鹅入口继续调用：

方法	路由	用途
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。
6. 音频真正可下载并准备转存时，按 taskId + assetKind + entityId + slot 幂等扣费；背景音乐固定扣除 5 泥点，物品点击音效固定扣除 10 泥点。任务仍在处理中不扣费，转存或资产绑定失败自动退款。

通用背景音乐提交历史上允许 prompt = ""。当前通用创作音频入口被后端显式熔断，不能通过该路由继续提交或转存音频。视觉小说专用路由保持兼容，内部继续复用同一套提交、轮询、转存逻辑。

3. 数据落点

3.1 拼图

拼图作品没有独立作品级 metadata 字段。背景音乐随 levels_json 保存到首个 PuzzleDraftLevel.backgroundMusic：

{
  "levelId": "puzzle-level-1",
  "backgroundMusic": {
    "taskId": "suno-task",
    "provider": "vector-engine-suno",
    "assetObjectId": "assetobj_1",
    "assetKind": "puzzle_background_music",
    "audioSrc": "/generated-puzzle-assets/..."
  }
}

当前草稿生成阶段跳过背景音乐生成；自动草稿编译只校验首图与 UI 背景。运行态仍兼容历史 PuzzleRuntimeLevelSnapshot.backgroundMusic.audioSrc，旧草稿若已有音乐可继续播放；新草稿默认保持静默背景音乐兜底。

3.2 抓大鹅

抓大鹅作品级音频与物体点击音效复用 generated_item_assets_json 数组保存，不新增表字段：

1. 作品背景音乐暂存到第一个 Match3DGeneratedItemAsset.backgroundMusic，表示当前 work profile 的作品级背景音乐。
2. 单个物体点击音效保存到对应 Match3DGeneratedItemAsset.clickSound。

这是一个兼容性折中：当前 Match3D work profile 没有 work-level metadata 字段，而 generated_item_assets_json 已经随作品详情、草稿架、运行态入口稳定传递。当前草稿生成阶段不再生成 backgroundMusic 或 clickSound；历史草稿中已有字段仍按旧兼容逻辑传递到运行态。后续若重新打开音频能力或新增正式作品 metadata 表达，应迁移 backgroundMusic 到作品级字段。

4. 前端交互

结果页 UI 保持轻量：

1. 拼图与抓大鹅结果页暂不展示背景音乐生成输入、生成按钮、状态和音频预览。
2. 生成完成后立即写回本地草稿状态，并触发既有保存链路或专用保存接口。
3. 抓大鹅每个物体详情面板只保留素材查看和名称编辑，不展示音效提示词或生成入口。
4. 若历史素材已有 backgroundMusic 或 clickSound，结果页不提供重新生成入口；试玩和运行态仍可消费已存在字段。

4.1 运行态默认点击音效

1. src/services/runtimeAudioFeedback.ts 提供通用关卡音频配置 DEFAULT_RUNTIME_LEVEL_AUDIO_CONFIG，内部缓存 HTMLAudioElement，失败时静默兜底，不阻塞玩法交互。
2. 拼图点击、按压或拖拽拼块时播放默认通用点击音效，并继续保留既有触觉反馈。
3. 抓大鹅点击物体时优先播放该物体绑定的 clickSound.audioSrc；若作品没有生成物体点击音效，则回退播放 /audio/ui-click-soft.wav。
4. 拼图关卡 currentLevel.status 首次进入 cleared 时播放默认过关音效；抓大鹅 run status 首次进入 won 时播放默认过关音效。
5. 拼图使用 displayRemainingMs，抓大鹅使用 timeLeftMs。当剩余时间进入默认阈值 5_000ms 后，每个自然秒桶最多播放一次倒计时音效，归零后停止。
6. 默认关卡音效跟随现有 musicVolume 设置，不新增独立音量 UI，不在运行态界面增加说明文案。
7. 拼图和抓大鹅运行态背景音乐同样跟随 musicVolume，读取 generated legacy path 时先换签，再交给隐藏 <audio loop preload="auto"> 自动播放；浏览器拒绝自动播放时静默失败，不阻断游戏交互。

4.2 草稿音乐试听与自动播放补充

2026-05-13 修正：

1. 拼图 素材配置 > 背景音乐 的试听控件当前隐藏；后续恢复时必须通过 useResolvedAssetReadUrl 对 generated legacy path 换签后再设置 <audio src>。
2. 抓大鹅结果页后续恢复音频试听入口时必须复用同一换签口径，不能把裸 /generated-match3d-assets/... 音频路径直接交给 <audio>。
3. 拼图和抓大鹅运行态在开局时会尝试自动播放背景音乐；若浏览器因自动播放策略拒绝，玩家首次按下拼图块或点击抓大鹅物品时必须再次调用同一个背景音乐播放函数，避免草稿音乐已经传入运行态但局内始终无声。
4. 播放失败仍只做静默兜底，不弹出规则说明或阻断局内交互。
5. 拼图结果页合并后端生成完成回包时，若本地首关仍处于 generationStatus = generating，必须保留回包中的历史 backgroundMusic 字段，避免自动保存把旧音频覆盖为空；该字段不再驱动可见音乐面板。

5. 验收

建议执行：

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。