refactor: 收口拼图 runtime 状态合并

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

@@ -0,0 +1,36 @@
+# 【前端架构】Platform Puzzle Runtime State Model 收口计划
+
+## 背景
+
+`PlatformEntryFlowShellImpl.tsx` 曾内联 `mergePuzzleServiceRuntimeState(...)`，在拼图排行榜提交回包后，把服务端 run 快照合并回当前前端 run。此逻辑没有 React state、网络、URL 或弹窗副作用，却需要理解 `PuzzleRunSnapshot` 的局部真相分工：拼块布局、当前关卡状态和计时结果由前端即时裁决；服务端回包只补排行榜、run 身份、通关数上限和下一关 handoff。
+
+若该合并规则继续留在平台壳，后续调整排行榜来源、相似作品下一关或本地 / 服务端 run 混合策略时，维护者必须翻大型壳层并同时避开大量副作用代码。
+
+## 决策
+
+新增 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts` 作为 Platform Puzzle Runtime State **Module**。公开 **Interface**：
+
+- `mergePuzzleServiceRuntimeState(currentRun, serviceRun)`：当双方都有 `currentLevel` 时，保留当前前端关卡状态与棋盘，只合并服务端 run 身份、`clearedLevelCount` 上限、排行榜与下一关 handoff；任一方缺 `currentLevel` 时返回当前 run。
+
+`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它负责提交排行榜、读取回包、写 React state、刷新 archive 和错误提示，不再持有拼图 run 快照合并字段清单。
+
+## Interface 约束
+
+- 缺少 `currentRun.currentLevel` 或 `serviceRun.currentLevel` 时不得合并，直接返回当前 run。
+- `clearedLevelCount` 取当前 run 与服务端 run 的最大值，避免服务端较旧回包降低本地通关数。
+- 排行榜优先取 `serviceRun.currentLevel.leaderboardEntries`；为空时取 `serviceRun.leaderboardEntries`；两者皆空时保留当前关卡榜单。
+- `currentLevel` 的棋盘、状态、计时和关卡字段来自当前 run，不被服务端回包覆盖。
+- `runId`、`entryProfileId`、`recommendedNextProfileId`、`nextLevelMode`、`nextLevelProfileId`、`nextLevelId`、`recommendedNextWorks` 来自服务端 run。
+
+## Depth / Leverage / Locality
+
+- **Depth**：壳层传入当前 run 与服务端 run，即取得合并后的稳定快照；排行榜来源、下一关 handoff 和前端局部真相保留规则藏入 Module Implementation。
+- **Leverage**：排行榜提交、后续相似作品推荐或服务端 run 字段变化时，先改纯 Module 与单测，壳层提交副作用不变。
+- **Locality**：拼图 runtime 快照合并规则集中到一个纯测试面，避免在平台壳中继续散落 `PuzzleRunSnapshot` 字段判断。
+
+## 验收
+
+- `npm run test -- src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts`
+- `npx eslint src/components/platform-entry/platformPuzzleRuntimeStateModel.ts src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
+- `npm run typecheck`
+- `npm run check:encoding`