refactor: 收口小游戏生成状态模型

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

@@ -0,0 +1,43 @@
+# 【前端架构】Platform Mini Game Draft Generation State Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联维护小游戏生成状态的恢复、失败/完成收尾、展示 rebase、拼图后端进度合并和生成中 / ready 判定。壳层因此既要处理 API 回包、React state、后台任务、URL 和 stage，又要记住 `MiniGameDraftGenerationState` 的生命周期细节。
+
+这些状态变换不读取 DOM，不请求网络，也不写 React state；它们属于平台层小游戏草稿生成状态 **Module**。壳层只应决定何时调用、把返回值写入对应 state。
+
+## 决策
+
+新增 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts` 作为 Platform Mini Game Draft Generation State **Module**。其公开 **Interface** 为：
+
+- `createMiniGameDraftGenerationStateForRestoredDraft(kind, metadata?, startedAtMs?)`：为恢复的草稿重建生成态，并保留后端开始时间作为进度事实源。
+- `createFailedMiniGameDraftGenerationStateForRestoredDraft(kind, updatedAt, error, metadata?)`：恢复失败草稿时按后端 `updatedAt` 建立失败态。
+- `rebaseMiniGameDraftGenerationStateForDisplay(state)` 与 `rebaseMiniGameDraftBackgroundCompileTaskForDisplay(task)`：清理展示用 `finishedAtMs`，避免返回生成页后沿用结束态计时。
+- `createPuzzleDraftGenerationStateFromPayload(payload, session?)`、`resolvePuzzlePhaseFromSessionProgress(state, session)`、`mergePuzzleSessionProgressIntoGenerationState(state, session)`：集中处理拼图生成的 aiRedraw、后端进度百分比和 phase 推进。
+- `resolveFinishedMiniGameDraftGenerationState(state, phase, options?)`：统一完成 / 失败收尾的 `finishedAtMs`、错误与资产计数合并。
+- `isMiniGameDraftReady(state)` 与 `isMiniGameDraftGenerating(state)`：统一生成态轻量判定。
+
+`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责 API、background task、React state 写入、作品架刷新、URL 与 stage 切换。
+
+## Interface 约束
+
+- 恢复草稿状态必须允许调用方传入 `startedAtMs`；未传时使用当前时间，与旧逻辑一致。
+- 恢复失败状态必须通过 `resolveMiniGameDraftGenerationStartedAtMs(updatedAt)` 解析后端时间，并保留传入 metadata。
+- `resolveFinishedMiniGameDraftGenerationState` 只覆盖显式传入的 `error`、`completedAssetCount`、`totalAssetCount`；未传时沿用原 state。
+- 拼图 session 只有在 `draft` 存在且不是 `formDraft` 时才视为后端编译生成中 session，才写入 `puzzleProgressPercent` 并推进 phase。
+- 拼图进度阈值保持旧值：`>=96` 到 `puzzle-select-image`，`>=94` 到 `puzzle-ui-assets`，`>=88` 时按 `puzzleAiRedraw=false` 进入 `puzzle-level-scene`，否则进入 `puzzle-cover-image`。
+- phase 变化时 `puzzleActiveStepStartedAtMs` 使用 session `updatedAt` 解析值；phase 不变时保留旧值。
+- 展示 rebase 只清理 `finishedAtMs`，不得修改 phase、error、资产计数或 metadata。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层以状态变换函数表达意图；生成态字段、拼图阈值、时间解析与计数合并藏入 Module Implementation。
+- **Leverage**：后续新增小游戏生成恢复或调整拼图后端进度阈值时，先改 Module 与单测，再让壳层 Adapter 保持调用点不变。
+- **Locality**：小游戏生成状态规则集中到一个纯测试面，避免在大型壳层的 API callback、background task 和恢复流程中重复推理 `MiniGameDraftGenerationState`。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts`
+- `npx eslint src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`