refactor: 收口小游戏会话映射

docs/technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md

@@ -0,0 +1,40 @@
+# 【前端架构】Platform Mini Game Session Mapping Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 顶部曾保留拼图 runtime 恢复、跳一跳 pending session、敲木鱼 work detail 恢复和敲木鱼 pending session 四段纯 DTO 映射。它们没有 React state、网络请求、路由、弹窗或计时副作用，却住在大型平台壳内；新增或修正生成中草稿恢复时，需要在壳层里理解 sessionId 优先级、拼图稳定 ID、pending draft 默认值和木鱼 fallback 规则。
+
+这些规则属于平台壳 session / work 恢复映射，应成为可测试的 **Module**。壳层只负责调用网络、写 React state、写 URL 和切换 stage。
+
+## 决策
+
+新增 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts` 作为 Platform Mini Game Session Mapping **Module**。其公开 **Interface** 为：
+
+- `buildPuzzleRuntimeWorkFromSession(session, owner)`：从拼图 Agent session 构造可进入 runtime 的 draft `PuzzleWorkSummary`，缺草稿、缺 profile 或缺封面时返回 `null`。
+- `buildJumpHopPendingSession(item)`：从跳一跳作品架 summary 构造生成中 pending session。
+- `buildWoodenFishSessionFromWorkDetail(work, fallbackItem?)`：从敲木鱼 work detail 恢复 session，并按 summary / fallback / profileId 决定 sessionId。
+- `buildWoodenFishPendingSession(item)`：从敲木鱼作品架 summary 构造生成中 pending session。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：调用这些映射后继续负责 `set*Session`、`set*Work`、`set*Run`、`createMiniGameDraftGenerationState(...)`、`writeCreationUrlState(...)`、`enterCreateTab()` 和 `setSelectionStage(...)`。
+
+## Interface 约束
+
+- 拼图 runtime work 必须保留 `draft.coverImageSrc` 非空门槛，避免启动缺封面的草稿运行态。
+- 拼图 profileId 优先 `publishedProfileId`，否则用 `buildPuzzleResultProfileId(sessionId)`；workId 使用 `buildPuzzleResultWorkId(sessionId)`，缺失时回退 profileId。
+- 拼图 owner 缺省为 `current-user` / `玩家`；`publishReady` 来自 `session.resultPreview?.publishReady`。
+- 跳一跳 pending sessionId 优先 `sourceSessionId`，缺失时用 `profileId`；素材、路径和 prompt 维持空值兜底。
+- 敲木鱼 detail sessionId 优先级固定为 `work.summary.sourceSessionId > fallbackItem.sourceSessionId > profileId`。
+- 敲木鱼 pending session 保持 `floatingWords=['功德 +1']`、素材 / 音效 / 背景为空的旧默认。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以四个函数取得恢复用 DTO；ID 优先级和默认 draft 字段藏入 Module Implementation。
+- **Leverage**：后续新增生成中作品恢复或修改 sessionId 规则时，先改 Module 与单测，再保持壳层 Adapter 副作用不变。
+- **Locality**：拼图、跳一跳和敲木鱼的恢复映射集中在一个纯测试面，避免在大型壳层顶部继续堆积 DTO 构造。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts`
+- `npx eslint src/components/platform-entry/platformMiniGameSessionMappingModel.ts src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`