Sync local updates with origin/master

.hermes/shared-memory/pitfalls.md

@@ -1138,6 +1138,22 @@
 - 验证：`PuzzleResultView` 单测覆盖发布弹窗内展示 `泥点余额不足`。
 - 关联：`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/technical/PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md`、`docs/technical/ASSET_GENERATION_POINTS_CONSUMPTION_2026-04-27.md`。
 
+## 拼图发布检查阶段会在事件落库时炸 wasm
+
+- 现象：拼图发布在“发布检查”环节直接报 `The module instance encountered a fatal error`，wasm backtrace 指向 `spacetime_module::puzzle::publish_puzzle_work`，并停在 `procedure_commit_mut_tx` 的 commit 阶段。
+- 原因：`publish_puzzle_work_tx` 会无条件调用 `emit_puzzle_work_published_event` 写入 `puzzle_event`；该表的 `event_id` 是主键，而事件 ID 由 `profile_id + published_at_micros` 组成。只要同一发布动作被重复执行、重放，或极端情况下发生时间戳碰撞，commit 时就会因主键冲突触发 fatal error。
+- 处理：待修复。发布事件写入需要改成幂等，或在重复发布时显式跳过已存在的 `event_id`；发布动作本身也应补一层更明确的幂等键，避免把重复提交直接推到事务提交阶段。
+- 验证：对同一 `session_id/profile_id/published_at_micros` 重复调用 `publish_puzzle_work` 时，不应再在 commit 阶段炸 wasm；正常发布仍应生成作品、更新 session，并可进入公开详情。
+- 关联：`server-rs/crates/spacetime-module/src/puzzle.rs`、`server-rs/crates/api-server/src/puzzle/handlers.rs`、`server-rs/crates/spacetime-client/src/module_bindings/puzzle_event_table.rs`。
+
+## 拼图会过早进入待发布态，结果页可能空图但仍显示可发布
+
+- 现象：拼图创作有时刚结束就跳到“待发布”结果页，但结果页里的正式图还是空的，发布检查随后又会拦住，用户会感觉“已经完成了却又不能发布”。
+- 原因：拼图的待发布判定太弱，`build_result_preview` / `validate_publish_requirements` 和 `is_puzzle_session_snapshot_publish_ready` 只检查了作品名、简介、标签、关卡名和 cover 图，没有要求 `level_scene_image_src`、`ui_spritesheet_image_src`、`level_background_image_src` 等完整资产都齐；前端恢复链路里的 `hasRecoverableGeneratedPuzzleDraft` / `normalizeRecoveredPuzzleDraftSession` 也只要有 cover 或候选图就会把草稿当成已完成。
+- 处理：待修复时要把“待发布”门槛收紧到整套拼图资产包完整，再让恢复逻辑只在完整草稿下抬高为完成态，避免半成品直接进入结果页。
+- 验证：当某个拼图草稿只补齐首图、但关卡背景或 UI spritesheet 仍缺失时，不应再进入 `ready_to_publish`；结果页也不应把这类草稿误判为已完成。
+- 关联：`server-rs/crates/module-puzzle/src/application.rs`、`server-rs/crates/api-server/src/puzzle/tags.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`。
+
 ## WebGL 画布在高 DPR 移动端放大溢出
 
 - 现象：抓大鹅试玩入口进入后，3D 锅体和物体从中心圆形区域向右下溢出，顶部状态和底部备选栏也可能看起来被右侧裁切。
@@ -1508,6 +1524,14 @@
 - 验证：`npm run typecheck`，并跑 `npm test -- src/routing/appPageRoutes.test.ts` 覆盖 JumpHop 阶段路径。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 跳一跳地块图集不要套通用系列素材 n 行模型
+
+- 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 n。`，或者即使绕过报错也只生成了 atlas 预览路径，地块切片没有真正落盘。
+- 原因：跳一跳地块只有 6 个固定 tileType，但旧实现把它塞进通用系列素材 helper，并使用 `grid_size = 3` / `item_names = 6` 的语义冲突模型；随后又只保留 atlas 资产与模拟路径，没把六个切片逐一上传并确认到 `JumpHopTileAsset`。
+- 处理：跳一跳地块改用专用 `2行*3列` 图集 prompt，按 `start / normal / target / finish / bonus / accent` 顺序切 6 张 PNG，并对每张切片各自走 OSS 上传、asset_object 确认和 entity bind。
+- 验证：`cargo test -p api-server jump_hop_tile_atlas -- --nocapture` 通过后，再看 `jump_hop.rs` 不应再调用 `build_generated_asset_sheet_prompt` 处理地块图集；公开结果里应能拿到 6 个独立 `JumpHopTileAsset`。
+- 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## image2 dry-run 带参考图时不要直接打印 data URL
 
 - 现象：使用 VectorEngine `gpt-image-2-all` 生成带参考图的概念图时，如果 dry-run 直接打印完整请求体，参考图会被转成超长 `data:image/png;base64,...`，终端日志会被数百万字符淹没。