Genarrative/docs/technical/PUZZLE_RUNTIME_FRONTEND_LOGIC_REHOME_2026-05-02.md

拼图运行态低延迟交互前端化修正 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 作为历史收尾记录保留；若与本文冲突，以本文的“低延迟棋盘前端裁决，非即时链路后端持久化”口径为准。