1

docs/technical/PUZZLE_RUNTIME_DRAG_RESPONSE_FIX_2026-04-27.md

@@ -0,0 +1,50 @@
+# 拼图运行时拖动跟手延迟修复
+
+日期：`2026-04-27`
+
+## 1. 背景
+
+拼图玩法运行时已经支持单块拖动、合并块整体拖动与拆分，但实测拖动时拼块会明显慢于手指或鼠标，表现为“拖着走但始终落后半拍”，尤其在移动端更明显。
+
+本次目标只修复前端拖动跟手延迟，不改变拼图交换、合并、拆分、通关等玩法规则。
+
+## 2. 根因
+
+本轮定位到拖动延迟主要来自两个前端渲染问题：
+
+1. `pointermove` 每一帧都调用 `setDragState`，导致整个 `PuzzleRuntimeShell` 和整盘拼图格子持续重渲染。
+2. 拼块节点默认挂了 `transition`，拖动过程中的 `transform` 会被浏览器当成缓动动画处理，视觉上进一步放大“慢半拍”。
+
+这两个问题叠加后，即使后端或本地运行态裁决没有延迟，前端拖动视觉仍然会滞后。
+
+## 3. 修复口径
+
+### 3.1 拖动视觉更新改为直写 DOM
+
+拖动中的位移不再依赖 React state 持续驱动，而是改成：
+
+1. `pointerdown` 只记录起点和 pointer 信息。
+2. 超过拖动阈值后，只做一次 `setDraggingPieceId` 用于切换拖动态样式。
+3. 后续 `pointermove` 通过 `requestAnimationFrame` 合帧，把位移直接写入目标拼块或合并块容器的 `style.transform`。
+
+这样可以避免每一帧都触发整盘 React 重渲染。
+
+### 3.2 收紧过渡属性
+
+拼块节点不再使用包含 `transform` 的通用 `transition`，只保留颜色、边框、阴影、透明度等非位移动画属性，避免拖动中的 transform 被浏览器插值缓动。
+
+### 3.3 裁决边界保持不变
+
+本次只优化拖动阶段的视觉反馈：
+
+1. `pointerup` 后仍然走现有 `onDragPiece`。
+2. 单块交换、拖到合并块后拆分、合并块整体重排，继续沿用当前本地运行态规则。
+3. 不新增前端本地裁决，不把玩法真相从既有运行态实现中分叉出去。
+
+## 4. 验收标准
+
+1. 单块拖动时拼块视觉位置应紧跟手指或鼠标，不再出现明显缓动拖尾。
+2. 合并块整体拖动时，组容器应同步跟手移动。
+3. 点击选中与拖动阈值判定仍保持原语义，不因为优化误触发交换。
+4. 运行时现有结算弹窗、排行榜和下一关入口不受影响。
+5. 定向测试覆盖拖动提交坐标的行为，并运行编码检查确保中文文档未被写坏。