1

docs/experience/BIG_FISH_DRAFT_GENERATION_CHAIN_FIX_2026-04-28.md

@@ -0,0 +1,80 @@
+# 大鱼吃小鱼草稿生成链路修复 2026-04-28
+
+## 背景
+
+大鱼吃小鱼玩法的结果页已经具备等级卡、主图工坊、动作工坊和背景工坊，但当前 `big_fish_compile_draft` 只是把锚点交给 `module-big-fish` 的 `compile_default_draft(...)` 做静态模板拼装。
+
+这会导致两个直接问题：
+
+1. 草稿编译虽然能成功进入结果页，但每一级实体只会拿到非常概括的模板文本，无法真正产出“实体名称、文字描述、形象描述、待机动作描述、移动动作描述”这一组首稿。
+2. 主图和动作工坊默认提示词没有绑定到一份足够细的草稿真相源，动作面板只能看到合并后的 `motionPromptSeed`，会表现成“草稿生成一带而过，所有内容都没有正常生成”。
+
+## 本次修复口径
+
+### 1. 每级等级蓝图必须补齐的文本字段
+
+大鱼吃小鱼每一级 `level blueprint` 在保留原有字段的同时，新增并持久化下面这些文本真相：
+
+1. `textDescription`
+   - 当前等级实体的正文文字描述。
+   - 用于结果页等级卡和后续重生成时的人类可读设定底稿。
+2. `visualDescription`
+   - 当前等级实体的形象描述。
+   - 主图工坊默认输入内容直接取这份字段。
+3. `idleMotionDescription`
+   - 当前等级待机动作描述。
+   - `idle_float` 动作工坊默认输入内容直接取这份字段。
+4. `moveMotionDescription`
+   - 当前等级移动动作描述。
+   - `move_swim` 动作工坊默认输入内容直接取这份字段。
+
+### 2. 默认提示词流转规则
+
+草稿生成、结果页工坊和正式资产生成统一按下面口径流转：
+
+1. 草稿编译阶段先产出上述结构化文本字段。
+2. 主图工坊默认文案：
+   - 优先显示 `visualDescription`
+   - `visualPromptSeed` 作为主图正式生图提示词的冻结快照，可由 `visualDescription` 组合生成
+3. 动作工坊默认文案：
+   - `idle_float` 优先显示 `idleMotionDescription`
+   - `move_swim` 优先显示 `moveMotionDescription`
+   - `motionPromptSeed` 继续保留为动作方向总提示词摘要，但具体动作正式生图必须显式拼入动作位对应描述
+4. 草稿阶段生成的正式主图、动作图和后续重生成，都只能读取同一份 `draft.levels[*]` 真相，前端不得本地拼接新的设定文案。
+
+### 3. 编译策略
+
+`big_fish_compile_draft` 需要升级为：
+
+1. `api-server` 先调用 LLM 做结构化草稿编译。
+2. 若 LLM 成功，则把完整 `draft_json` 写回 SpacetimeDB。
+3. 若 LLM 不可用、返回非法 JSON 或字段缺失，则退回 `compile_default_draft(...)` 的 deterministic fallback。
+
+这样可以同时保证：
+
+1. 正常环境下草稿不再只是模板壳。
+2. 模型偶发失败时不会打断结果页主链。
+3. SpacetimeDB reducer 不承担外部网络调用，仍然符合后端边界。
+
+## 落地范围
+
+本次修复涉及：
+
+1. `server-rs/crates/module-big-fish`
+2. `server-rs/crates/spacetime-module`
+3. `server-rs/crates/spacetime-client`
+4. `server-rs/crates/shared-contracts`
+5. `server-rs/crates/api-server`
+6. `packages/shared/src/contracts/bigFish.ts`
+7. `src/components/big-fish-result/BigFishResultView.tsx`
+
+## 验收口径
+
+修复后需要满足下面这些观察结果：
+
+1. 点击“生成草稿”后，`draft.levels[*]` 不再只有空泛模板，而是每级都带名称、文字描述、形象描述、待机动作描述、移动动作描述。
+2. 打开主图工坊时，默认文本来自当前等级的 `visualDescription`。
+3. 打开待机动作工坊时，默认文本来自当前等级的 `idleMotionDescription`。
+4. 打开移动动作工坊时，默认文本来自当前等级的 `moveMotionDescription`。
+5. 资产槽位 `promptSnapshot` 与对应动作位 / 主图位的默认提示词一致。
+6. LLM 不可用时仍然能生成一版可用 fallback 草稿，而不是直接报错或写入空草稿。

docs/experience/PUZZLE_LOCAL_RUN_LEADERBOARD_FIX_2026-04-28.md

@@ -0,0 +1,27 @@
+# 拼图本地运行态通关排行榜误请求修复记录
+
+## 问题现象
+
+拼图关卡完成后，右下角会弹出错误提示，内容表现为拼图 `run` 不存在。
+
+## 根因
+
+当前拼图玩法仍有一条前端本地兜底链路：
+
+1. 进入拼图测试或公开作品体验时，前端先创建 `local-puzzle-run-*` 形式的本地运行态。
+2. 这类 `run` 只存在于前端内存，不存在后端持久化记录。
+3. 通关副作用里却统一调用了后端 `submitPuzzleLeaderboard(runId, payload)`。
+4. 后端拿到本地 `runId` 后无法找到真实记录，于是返回“run 不存在”，最终在运行时右下角暴露成错误提示。
+
+## 修复口径
+
+本次不改后端接口，也不把本地兜底 run 强行持久化到后端，而是先把边界收口到前端：
+
+1. 显式识别 `local-puzzle-run-*` 这类本地 run。
+2. 本地 run 通关后不再请求后端排行榜接口。
+3. 直接在前端本地生成只包含当前玩家成绩的排行榜数据，保证结算弹窗仍可展示成绩。
+4. 真实后端 run 仍继续走正式排行榜提交流程，不影响后续 Rust / SpacetimeDB 版本的统一收口。
+
+## 经验结论
+
+只要某条玩法链路还保留“本地 run / 本地快照”兜底，就不能在通关、副作用、排行榜、下一关等后置动作里默认把它当成后端真 run 使用。必须先做运行态来源分流，再决定是否调用依赖真实 runId 的接口。

docs/experience/README.md

@@ -32,3 +32,5 @@
 - [AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md](./AGENT_EMPTY_SESSION_DRAFT_VISIBILITY_2026-04-26.md)：记录 Agent 空会话不应进入作品草稿列表的后端判定规则。
 - [BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md](./BIG_FISH_PUBLISH_FEEDBACK_FIX_2026-04-26.md)：记录大鱼吃小鱼发布成功后结果页反馈与作品列表刷新的修复口径。
 - [BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md](./BIG_FISH_WORKS_JSON_COMPAT_FIX_2026-04-28.md)：记录大鱼作品列表 `items_json` 字段升级后的向后兼容修复口径，避免旧 JSON 直接打崩 works 接口。
+- [BIG_FISH_DRAFT_GENERATION_CHAIN_FIX_2026-04-28.md](./BIG_FISH_DRAFT_GENERATION_CHAIN_FIX_2026-04-28.md)：记录大鱼吃小鱼草稿生成从结构化内容产出到主图/动作默认提示词回填的修复口径。
+- [PUZZLE_LOCAL_RUN_LEADERBOARD_FIX_2026-04-28.md](./PUZZLE_LOCAL_RUN_LEADERBOARD_FIX_2026-04-28.md)：记录拼图本地 run 通关后误请求后端排行榜、导致“run 不存在”报错的边界修复口径。