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