fix: polish bark battle creation flow

.hermes/shared-memory/pitfalls.md

@@ -46,6 +46,36 @@
 - 验证：点击汪汪声浪后直接看到创作页内嵌表单，不再出现独立配置页；测试应覆盖内嵌表单与 runtime 返回路径。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/bark-battle-creation/BarkBattleConfigEditor.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。
 
+## 汪汪声浪发布态不要丢失结果页最终素材
+
+- 现象：结果页上传或批量生成玩家形象、对手形象、UI 背景后，发布进入正式 runtime 仍可能显示初始草稿素材或兜底视觉。
+- 原因：`publish_bark_battle_work` 如果只把结果页最终状态保存到 `published_snapshot_json`，但正式 runtime 读取的 `config_json` 仍来自草稿行旧值，就会丢失结果页局部替换。
+- 处理：发布时把最终 `publishedSnapshot` 解析为 `BarkBattleEditorConfigSnapshot`、规范化后同时写入 `bark_battle_published_config.config_json` 和 `published_snapshot_json`；首轮自动生成只由 `bark-battle-generating` 负责，结果页仅覆盖已接入的玩家形象、对手形象和竞技背景图片槽位，不再提供音频配置入口。
+- 验证：发布后 runtime config 应包含结果页最终 `playerCharacterImageSrc`、`opponentCharacterImageSrc` 和 `uiBackgroundImageSrc`。
+
+## 汪汪声浪 v1 生成页和正式运行态要分开
+
+- 现象：如果把初始三图自动生成、结果页修补、公开发布和正式运行态混在一页，创作者容易误以为一次生成和正式运行是同一职责。
+- 原因：`bark-battle-generating` 才应该承担玩家形象、对手形象和竞技背景的自动生成；结果页只做单槽修补，正式 runtime 又必须切到真实麦克风和正式统计。
+- 处理：表单提交后先进入独立生成页，部分失败仍进结果页；结果页只保留单槽重试、重新生成和上传，不再保留一次生成按钮、音频配置入口、皮肤预设入口或排名配置。发布后先到统一作品详情页，再进正式 runtime；草稿试玩允许 mock，不写正式 run。
+- 验证：生成页负责首轮自动产出三图；结果页不出现一次生成按钮、音频配置入口、皮肤预设入口或排名配置；正式 runtime 必须麦克风可用且会写正式 run，草稿试玩不写正式统计。
+
+## 汪汪声浪生成页不要只停留在前端内存草稿
+
+- 现象：点击“生成草稿”后生成页一直转圈，或刷新 / 回到草稿架后看不到三图素材。
+- 原因：生成页只在前端内存里合并玩家形象、对手形象和竞技背景，没有把生成结果写回 `bark_battle_draft_config.config_json`；另外 BFF 若在刚创建草稿后先读 `spacetime-client` 订阅 cache 再保存，cache 可能短暂落后，导致保存失败或返回旧快照。
+- 处理：生成页三图完成后调用 `POST /api/creation/bark-battle/drafts/{draftId}/config` 持久化；保存接口直接把请求快照交给 SpacetimeDB procedure，由模块事务校验 owner / work，并在 HTTP 回包用本次请求里的三图字段覆盖，避免订阅 cache 滞后；保存请求必须设置前端超时，保存失败也进入结果页并标记部分失败。
+- 验证：`npm run test -- src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx src/services/bark-battle-creation/barkBattleCreationClient.test.ts src/components/bark-battle-creation/BarkBattleResultView.test.tsx packages/shared/src/contracts/barkBattle.test.ts`；`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "bark battle"`；`cargo check --manifest-path server-rs\Cargo.toml -p api-server`。
+- 关联：`src/components/bark-battle-creation/BarkBattleGeneratingView.tsx`、`src/services/bark-battle-creation/barkBattleCreationClient.ts`、`server-rs/crates/api-server/src/bark_battle.rs`、`server-rs/crates/spacetime-module/src/bark_battle.rs`。
+
+## 汪汪声浪三图不要复用 RPG 场景图链路
+
+- 现象：玩家形象和对手形象看起来走了场景图片 prompt；生成页三个槽位同时转圈，但只有第一个真实生成，首图返回后三个槽位一起停止或只显示首图。
+- 原因：前端曾复用 `/api/runtime/custom-world/scene-image`，三类素材都被当成 RPG landmark scene image；生成页又只用父级 draft 判断 ready，批量 Promise 结束后才一次性合并结果，缺少逐槽状态。
+- 处理：Bark Battle 生图统一走 `POST /api/creation/bark-battle/images/generate`，请求体包含 `slot` 和 v1 配置；后端在 `api-server/src/bark_battle.rs` 按 `player-character`、`opponent-character`、`ui-background` 分别拼装正式 prompt，写入 `generated-bark-battle-assets`，并返回 `prompt/actualPrompt`。前端 `generateAllBarkBattleImageAssets` 保持三槽 `Promise.allSettled` 并通过 `onSlotComplete` 逐槽刷新生成页状态。
+- 验证：`npm run test -- src/services/bark-battle-creation/barkBattleCreationClient.test.ts src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx packages/shared/src/contracts/barkBattle.test.ts`；`cargo test -p shared-contracts bark_battle --manifest-path server-rs\Cargo.toml`；`cargo check --manifest-path server-rs\Cargo.toml -p platform-oss -p api-server`。
+- 关联：`src/services/bark-battle-creation/barkBattleCreationClient.ts`、`src/components/bark-battle-creation/BarkBattleGeneratingView.tsx`、`server-rs/crates/api-server/src/bark_battle.rs`、`server-rs/crates/platform-oss/src/lib.rs`。
+
 ## 抓大鹅批量重新生成物品不要新增 itemId
 
 - 现象：结果页批量重新生成物品后，试玩或正式运行态的物品类型和图片对应关系漂移，或者用户输入一个不存在名称后被当作新物品追加。
@@ -1039,3 +1069,27 @@
 - 处理：打开草稿时把持久化 `generationStatus=generating` 等同于生成中 notice，恢复对应玩法生成进度页；恢复计时使用作品摘要 `updatedAt` 推导 `startedAtMs`。
 - 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating"`。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 汪汪声浪草稿试玩不要写正式 run
+
+- 现象：如果草稿结果页试玩和发布后 runtime 共用同一写成绩路径，未发布或未确认资源的草稿试玩会污染正式单局、排行榜和作品统计。
+- 原因：`BarkBattleRuntimeShell` 同时承担草稿预览和发布后运行态，需要由调用方显式传入 `runtimeMode` 区分是否写正式 run。
+- 处理：草稿结果页试玩保持 `runtimeMode=draft`，只做本地预览；发布成功后先进入 `/works/detail?work=BB-xxxxxxxx`，再从详情页以 `runtimeMode=published` 进入正式 runtime，并在开始/结算时分别调用 `startBarkBattleRun` 与 `finishBarkBattleRun`。
+- 验证：草稿试玩不触发 start / finish run；正式 runtime 必须先通过麦克风授权，再写 start run 和结算派生指标。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`、`src/services/bark-battle-runtime/barkBattleRuntimeClient.ts`。
+
+## 汪汪声浪移动端创作表单不要再套一层纵向滚动
+
+- 现象：移动端创作 Tab 里进入汪汪声浪表单后，页面右侧出现不自然的内层滚动条，最后的形象描述输入框容易被“生成草稿”按钮、键盘或底部 TabBar 挤压 / 遮挡；顶部玩法卡首尾也可能贴边显得被裁。
+- 原因：外层 `.platform-tab-panel` 已经是纵向滚动容器，创作页中间又有多层 `overflow-hidden`，旧的 `BarkBattleConfigEditor` 根节点再加 `overflow-y-auto`，形成外层 Tab 面板 + 内层表单的套滚动；底部按钮只预留 safe-area，不预留真实操作区距离；顶部玩法卡横向滚动条隐藏且首尾没有 scroll padding。
+- 处理：移动端让 Bark Battle 表单跟随父级滚动，`lg` 以上才恢复表单内滚动；创作页容器移动端使用 `overflow-visible` 和 safe-area 底部 padding；顶部模板 tablist 加 `scroll-px-3` / 横向 padding，移动端卡片宽度收窄，避免首尾 ring 和圆角贴边裁切。
+- 验证：`npm run test -- src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "create tab shows template tabs"`、移动端视口检查最后一个输入框与“生成草稿”按钮不重叠。
+- 关联：`src/components/bark-battle-creation/BarkBattleConfigEditor.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 汪汪声浪拟声词不要被默认狗主题锁死
+
+- 现象：创作者把主题或形象改成机甲、猫、骑士等非狗主题后，局内仍播放 `轰汪！`、`汪爆！` 这类狗叫词，表现像系统强行把主题带回狗。
+- 原因：拟声词 textarea 如果一开始就填入默认小狗词池，并且始终作为自定义 `onomatopoeia` 提交，runtime 会优先使用该字段，无法再根据新的 `themeDescription` / `playerImageDescription` / `opponentImageDescription` 走主题 fallback。
+- 处理：`BarkBattleConfigEditor` 需要区分“系统默认词池”和“创作者已手动编辑”。未手动编辑时随主题 / 形象描述自动重算；手动编辑后才冻结为自定义词池。默认词池只在命中狗相关关键词时加入狗叫词，非狗主题使用科技、幻想或通用高能词。
+- 验证：`npm run test -- src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/games/bark-battle/ui/__tests__/BarkBattleRuntimeShell.test.tsx`，并确认非狗主题的拟声词不含 `汪`。
+- 关联：`src/components/bark-battle-creation/BarkBattleConfigEditor.tsx`、`src/games/bark-battle/application/BarkBattleConfig.ts`、`src/games/bark-battle/ui/BarkBattleRuntimeShell.tsx`。