1

docs/technical/PUZZLE_RUNTIME_FRONTEND_LOGIC_REHOME_2026-05-02.md

@@ -0,0 +1,46 @@
+# 拼图运行态低延迟交互前端化修正 2026-05-02
+
+## 背景
+
+本次检查发现正式平台入口的拼图运行态存在后端裁决回流：
+
+1. 作品详情、公开作品卡和结果页试玩会启动后端 run。
+2. `PuzzleRuntimeShell` 的交换和拖动回调在非本地 run 时会调用 `swapPuzzlePieces`、`dragPuzzlePieceOrGroup`。
+3. 服务端 run snapshot 如果直接覆盖前端当前棋盘，会让移动、交换、合并和通关反馈出现延迟或回退。
+
+这与 PRD 中“前端以本地计算得到的 `allTilesResolved = true` 或 `status = cleared` 作为本关通关真相；后端不再参与拼块布局裁决”的规则冲突。
+
+## 修正口径
+
+正式平台入口采用混合运行态：
+
+1. 正式平台开局仍调用后端 `startPuzzleRun`，保留真实 `runId`、游玩记录、排行榜和下一关存储锚点。
+2. 点击交换只调用 `swapLocalPuzzlePieces`。
+3. 拖动单块或合并块只调用 `dragLocalPuzzlePiece`。
+4. 自动合并、拆分、合并块整体平移、被覆盖块交换和通关判定都以前端当前 `PuzzleRunSnapshot` 为准。
+5. 通关后调用后端 `submitPuzzleLeaderboard` 持久化成绩并读取真实排行榜；前端只合并排行榜与下一关 handoff，不用后端棋盘覆盖当前棋盘。
+6. 点击同作品下一关调用后端 `advancePuzzleNextLevel`，由 SpacetimeDB 返回新的运行态快照。
+7. 当前作品没有下一关时，通关弹窗展示后端 handoff 返回的相似作品；用户点击具体候选作品时直接 `startPuzzleRun(profileId, null)`，从目标作品第 `1` 关重新开始。
+8. 失败状态点击“重新开始”时，正式 run 使用当前关 `levelId` 重新 `startPuzzleRun`，草稿/本地 run 使用本地重建，二者都保留当前失败关卡。
+9. 结果页草稿试玩没有正式后端 run 时，继续使用本地 run、local leaderboard 和本地下一关兜底。
+
+## 工程落点
+
+1. `src/services/puzzle-runtime/puzzleLocalRuntime.ts`
+   - `startLocalPuzzleRun` 支持按 `levelId` 启动。
+   - `advanceLocalPuzzleLevel` 仅作为草稿试玩和无后端 run 的兜底。
+   - 正式平台的移动、交换、合并、拆分和通关裁决仍复用本地函数，避免交互延迟。
+2. `src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`
+   - 平台拼图开局、恢复存档、排行榜、下一关接回后端。
+   - 正式平台入口不再调用 `/api/runtime/puzzle/runs/{runId}/swap`、`/drag`。
+   - 后端排行榜返回的 run 只合并排行榜和 `nextLevelMode / nextLevelProfileId / nextLevelId / recommendedNextWorks`，不覆盖当前棋盘。
+   - 相似作品候选卡点击启动目标作品新 run；失败重开按当前关 `levelId` 启动新 run。
+3. `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`
+   - 公开拼图玩法交互测试断言前端本地交换函数被调用。
+   - 同时断言后端 `swap / drag` 不参与棋盘交互，后端 `leaderboard / next-level` 继续参与非即时链路。
+
+## 边界
+
+本次只收回拼图玩法内的移动、交换、合并、拆分和通关裁决。创作 Agent、作品保存、发布、公开广场读取、作品详情读取、作品改造、排行榜、同作品下一关、相似候选生成、失败重开和游玩记录仍走现有后端链路。
+
+旧 `SERVER_RS_DDD_WP_PZ_RUNTIME_BACKEND_TRUTH_CLOSURE_2026-05-01.md` 作为历史收尾记录保留；若与本文冲突，以本文的“低延迟棋盘前端裁决，非即时链路后端持久化”口径为准。