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 和本地下一关兜底。
10. 运行态输入采用全项目通用的 src/services/input-devices/ 抽象层承接，指针、触控、mocap 等设备都先归一为 press / move / release / tap / drop 拖拽语义，再由拼图运行态解析具体拼块和落点。
11. mocap grab 不是点击选中语义，而是持续拖拽语义；松手时按当前棋盘归一坐标提交 drop。合并大块只需要提交其中任一成员拼块 pieceId，本地拼图运行时会按 mergedGroupId 解析整组平移。
12. 拼图作品详情或开局遇到后端 404 / NOT_FOUND / 资源不存在 时，平台入口不再停留在空详情或运行态错误页，而是清理当前拼图详情/run 状态并返回首页。

工程落点

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 继续参与非即时链路。
4. src/services/input-devices/
   • runtimeDragInputController 提供设备无关的拖拽会话状态机。
   • runtimeInputGeometry 提供屏幕坐标、归一坐标和网格命中的通用转换能力。
   • 玩法组件只传入“这个点对应哪个目标”和“drop 到哪个目标”的玩法解释，不在输入层写拼图专用规则。
5. src/components/puzzle-runtime/PuzzleRuntimeShell.tsx
   • 鼠标/触控与 mocap 共用同一个 runtime drag controller。
   • 合并块成员不再被 mocap 路径过滤；mocap 可从合并块任一占用格抓取，并复用本地运行时的大块拖拽规则。
6. src/components/platform-entry/PlatformEntryFlowShellImpl.tsx
   • openPuzzleDetail、openPuzzlePublicWorkDetail、startPuzzleRunFromProfile 对拼图作品缺失统一回首页。

边界

本次只收回拼图玩法内的移动、交换、合并、拆分和通关裁决。创作 Agent、作品保存、发布、公开广场读取、作品详情读取、作品改造、排行榜、同作品下一关、相似候选生成、失败重开和游玩记录仍走现有后端链路。

旧 SERVER_RS_DDD_WP_PZ_RUNTIME_BACKEND_TRUTH_CLOSURE_2026-05-01.md 作为历史收尾记录保留；若与本文冲突，以本文的“低延迟棋盘前端裁决，非即时链路后端持久化”口径为准。