收口统一创作流程一期

.hermes/shared-memory/pitfalls.md

@@ -142,6 +142,22 @@
 - 验证：浏览器里这三页的根区应仍保留 `platform-remap-surface`，但不再出现 `platform-page-stage`；草稿页顶部筛选样式应和发现页频道标签一致。
 - 关联：`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldWorkTabs.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/index.css`。
 
+## 统一创作壳现在自己负责页面滚动和四条入口外壳
+
+- 现象：统一创作页最初只包住拼图、抓大鹅和敲木鱼的工作台内容，跳一跳仍然保留独立工作台壳，页面级滚动职责也散落在平台入口 motion wrapper 里，导致移动端不同入口的可见外壳不一致。
+- 原因：`UnifiedCreationPage` 只做了标题和隐藏契约，入口壳还在各自工作台里保留 `platform-remap-surface` / `overflow-y-auto`，`jump-hop` 也没进入统一 spec。
+- 处理：把 `jump-hop` 纳入 `unifiedCreationSpec`，让 `UnifiedCreationPage` 自己承担页面级滚动与统一标题栏；`JumpHopCreationWorkspace`、`WoodenFishCreationWorkspace` 补 `unifiedChrome` / `showBackButton`，平台壳不再给这几条统一入口套额外滚动壳。
+- 验证：`npm run test -- src/components/unified-creation/unifiedCreationSpecs.test.ts src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedGenerationPage.test.tsx src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx` 通过后，`/creation/puzzle`、`/creation/match3d`、`/creation/jump-hop`、`/creation/wooden-fish` 都应由同一套统一创作页外壳承载。
+- 关联：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/components/unified-creation/unifiedCreationSpecs.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。
+
+## 统一创作编排层不要再让平台壳直挂旧工作台
+
+- 现象：平台入口壳已经切到统一创作外壳，但源码里仍直接 lazy import 并渲染四个旧工作台分支，看起来还是四套入口编排。
+- 原因：统一创作页只收口了可见外壳，入口层没有再抽一层统一创作编排组件，导致平台壳依旧要认识各玩法旧工作台。
+- 处理：新增 `UnifiedCreationWorkspace`，由它内部按 `playId` 选择真实工作台；平台壳只依赖这一层，不再直接挂旧工作台分支。旧工作台已迁入 `src/components/unified-creation/workspaces/`，不再是入口编排事实源。
+- 验证：`PlatformEntryFlowShellImpl.tsx` 中不应再出现四个旧工作台的入口渲染分支，创作 Tab 与 `/creation/<play>` 仍能正常进入对应工作台。
+- 关联：`src/components/unified-creation/UnifiedCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 
 ## Jenkinsfile 开头不能带 UTF-8 BOM
 
@@ -255,7 +271,7 @@
 - 原因：通用图像输入是受控输入面板，不是只服务单页的临时实现；图片、提示词、参考图数组、重绘开关等业务真相应由外层页面持有，组件最多持有参考图预览、删除确认这类短生命周期 UI 状态。
 - 处理：抽 `CreativeImageInputPanel` 时，保留上传卡、参考图入口、缩略图、预览弹层、删除确认和提交按钮的统一壳，但把主图文件读取、裁剪、历史素材、计费确认和具体提交动作留给外层页面；后续页面接入时只传业务回调和文案。
 - 验证：拼图入口测试仍可通过，且新组件可通过不同页面复用而不需要复制上传卡实现。
-- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`。
+- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`。
 
 ## RPG 发布不能只依赖 agent session seed_text
 
@@ -693,7 +709,7 @@
 - 原因：首图生成只通过 `compile_puzzle_draft.referenceImageSrc` 临时传 Data URL，不持久化到 SpacetimeDB；结果页重新生成则要把当前上传图或关卡 `pictureReference` 作为 `generate_puzzle_images.referenceImageSrc` 继续传给后端。
 - 处理：浏览器 Network 里确认 action payload 带 `referenceImageSrc`；api-server 日志按同一 `session_id` 查看 `拼图参考图解析完成`、`拼图 VectorEngine 图片生成 HTTP 返回`、`拼图 VectorEngine 图片下载完成`、`拼图生成图片已写入 OSS 与资产索引`，可定位慢在参考图读取、VectorEngine、下载或 OSS。
 - 验证：前端测试覆盖上传图 + AI 重绘、结果页保存的 `pictureReference` 重新生成；后端单测覆盖 VectorEngine 请求体 `image` 字段。
-- 关联：`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle.rs`。
+- 关联：`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle.rs`。
 
 ## 拼图首图生成后要把入口参考图写回 `pictureReference`
 
@@ -1447,16 +1463,16 @@
 - 现象：拼图创作页或结果页打开“选择历史图片”后，历史列表显示 `账号 user-1` 之类归属文案而不是图片名；`1713686400.000000Z` 这类时间显示为未知；选中后预览或生成参考图可能被怀疑不可用。
 - 原因：`/api/assets/history?kind=puzzle_cover_image` 返回的 `ownerLabel` 是资产归属账号，不是图片标题；`createdAt` 可能是 SpacetimeDB / shared-kernel 秒级时间字符串，不能只用浏览器 `new Date(value)` 解析。历史图的 `imageSrc` 是 `/generated-*` 私有兼容路径，浏览器预览必须换签。
 - 处理：前端标题和选中标签从 `imageSrc` 路径末尾推导，例如 `image.png`；时间解析兼容 ISO 与 `1713686400.000000Z`；创作页主图、历史列表图和结果页参考图继续用 `ResolvedAssetImage`，提交给后端时仍保留原始 `imageSrc`。
-- 验证：`npm run test -- src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`，并执行 `npm run check:encoding`。
-- 关联：`src/services/puzzle-works/puzzleHistoryAsset.ts`、`src/components/puzzle-agent/PuzzleHistoryAssetPickerDialog.tsx`、`docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md`。
+- 验证：`npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`，并执行 `npm run check:encoding`。
+- 关联：`src/services/puzzle-works/puzzleHistoryAsset.ts`、`src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.tsx`、`docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md`。
 
 ## 拼图历史图关闭 AI 重绘不要强制 Data URL
 
 - 现象：拼图创作页从历史生成图片中选择主图，再关闭 AI 重绘生成草稿时，后端报“上传图必须是图片 Data URL”。
 - 原因：历史图 `imageSrc` 是 `/generated-puzzle-assets/...` 私有兼容路径；AI 重绘开启时后端参考图分支会解析该路径，但关闭 AI 重绘的“直用上传图”分支旧实现只调用 `parse_puzzle_image_data_url`。
 - 处理：关闭 AI 重绘时也复用拼图参考图解析入口，允许 Data URL 与 `/generated-*` 历史路径统一转成 `PuzzleDownloadedImage` 后持久化；前端不需要下载历史图再转 base64。
-- 验证：`npm run test -- src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_uploaded_cover_can_reuse_resolved_history_image --manifest-path server-rs\Cargo.toml`、`npm run dev:api-server` 后检查 `/healthz`。
-- 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx`。
+- 验证：`npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_uploaded_cover_can_reuse_resolved_history_image --manifest-path server-rs\Cargo.toml`、`npm run dev:api-server` 后检查 `/healthz`。
+- 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx`。
 
 ## 拼图结果页局部生图不要污染草稿生成态
 
@@ -1474,7 +1490,7 @@
 - 原因：上传图直用路径应把 Data URL 或 `/generated-*` 历史图解析后持久化为 `sourceType=uploaded` 的正式候选，再继续生成 9:16 关卡画面、UI spritesheet 和纯背景；如果只把 `aiRedraw=false` 当作“不参考图片生成”，就会误走首图生成。
 - 处理：入口页用 payload 的 `aiRedraw` 写入生成页 metadata，`puzzleAiRedraw=false` 时进度跳过 `生成拼图首图`；后端 `compile_puzzle_draft` 和结果页 `generate_puzzle_images` 都在 `aiRedraw=false && referenceImageSrc 非空` 时走上传图直用候选。结果页关卡详情必须复用 `CreativeImageInputPanel`，不要把正式图当成可重绘参考图；本次上传或历史选择的图才显示 AI 重绘开关并可删除。
 - 验证：`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_result_level_direct_upload_skips_cover_image_generation --manifest-path server-rs\Cargo.toml`。
-- 关联：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`。
+- 关联：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`。
 
 ## Jenkins 数据库导入导出脚本先补 Node 工具链 PATH
 
@@ -1550,8 +1566,8 @@
 
 - 现象：竖屏打开拼图、抓大鹅或敲木鱼创作页时，浏览器页面本身无法滚动，生成按钮或右侧表单面板落到视口外；木鱼的敲击音效和功德词条看起来像被塞进单独滑动窗口。
 - 原因：平台根壳固定一屏并隐藏溢出，`UnifiedCreationPage` 又使用 `h-full min-h-0 overflow-hidden` 和内容区 `overflow-y-auto`，导致滚动责任落到内部内容窗，而不是整个创作 stage。
-- 处理：`UnifiedCreationPage` 只保留统一标题、隐藏字段契约和内容包装，不再设置内部纵向滚动；拼图、抓大鹅和敲木鱼三个统一创作入口的 `motion.div` stage 负责 `overflow-y-auto overflow-x-hidden`。拼图和抓大鹅在 `unifiedChrome` 下收起旧 `h-full overflow-hidden` 外壳，让表单主体跟随 stage 滚动。
-- 验证：用竖屏浏览器视口打开 `/creation/wooden-fish`、`/creation/puzzle` 和 `/creation/match3d`，页面级 stage 应可滚动到生成按钮；`.unified-creation-page__content` 不应包含 `overflow-y-auto`，木鱼工作台内部也不应出现独立纵向滚动容器，拼图 / 抓大鹅可见标题不应重复。
+- 处理：`UnifiedCreationPage` 统一负责标题、隐藏字段契约、内容包装和页面级纵向滚动；拼图、抓大鹅、跳一跳和敲木鱼的外层 `motion.div` 不再额外包 `overflow-y-auto`。各工作台在 `unifiedChrome` 下收起旧 `h-full overflow-hidden` 外壳，让表单主体跟随统一页面滚动。
+- 验证：用竖屏浏览器视口打开 `/creation/wooden-fish`、`/creation/puzzle`、`/creation/match3d` 和 `/creation/jump-hop`，统一创作页应可滚动到生成按钮；`.unified-creation-page` 应包含页面级 `overflow-y-auto`，木鱼工作台内部也不应出现独立纵向滚动容器，拼图 / 抓大鹅可见标题不应重复。
 - 验证：`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`。