1

docs/technical/PUZZLE_IMAGE_AND_FRONTEND_RULES_ALIGNMENT_2026-04-29.md

@@ -0,0 +1,42 @@
+# 拼图图片与前端规则裁决对齐 2026-04-29
+
+## 背景
+
+本轮明确调整拼图运行态边界：
+
+1. 拼图生成图片重新回到 `1:1` 正方形。
+2. 拼图中的拖动、交换、合并、拆分与通关判定由前端即时计算。
+3. 移动端运行时棋盘需要贴近屏幕两侧边缘，减少无效留白。
+
+此前误按 `9:16` 竖屏统一图片和棋盘，会让拼图块在移动端可操作面积不足，也和拼图素材的切块体验不匹配。本轮回到正方形棋盘与正方形生图。
+
+## 落地结论
+
+### 1. 图片生成
+
+1. 拼图生成图固定使用 `1024*1024`。
+2. 文生图和参考图生图共用同一个尺寸常量，禁止一条链路仍生成竖屏或横版图。
+3. 拼图图片提示词明确写入 `1:1 正方形画布`，继续保留 `3x3 或 4x4 拼图切块`、主体清晰、层次明确、无文字水印等约束。
+4. 图片生成仍由 `api-server` 执行。SpacetimeDB reducer 不做网络 I/O。
+
+### 2. 前端规则裁决
+
+1. 运行态的交换、拖动、合并、拆分、通关判定由前端基于 `PuzzleRunSnapshot` 即时计算。
+2. 正式 run 与本地测试 run 复用同一套前端规则函数，避免正式链路和测试链路玩法漂移。
+3. 后端仍负责开始 run、进入下一关、道具扣费、暂停计时同步、排行榜提交、作品与下一关候选读取。
+4. 正式 run 的 `/drag` 后端 HTTP 接口已撤出 Rust API；拖动不再有后端入口。`/swap` 暂作点击交换兼容入口，拖动中的交换由前端本地规则完成。
+
+### 3. 移动端棋盘布局
+
+1. 运行时棋盘根容器恢复 `aspect-square`。
+2. 移动端横向 padding 收紧到 `0.25rem`，棋盘宽度使用 `min(99vw, 可用高度)`，尽量贴近屏幕两侧边缘。
+3. 单格不设置固定最小高度，避免移动端被单格撑破。
+4. 顶部 HUD 与底部道具仍保留安全区，不能遮挡棋盘可操作区域。
+
+## 验收
+
+1. 点击拼图草稿生成或重新生成画面时，后端请求 DashScope 的 `size` 为 `1024*1024`。
+2. 图片提示词包含 `1:1 正方形拼图关卡`。
+3. 正式拼图 run 中拖动拼块后，前端立即更新棋盘、合并块和通关状态，不再等待 `/drag`。
+4. 移动端运行时棋盘为正方形，并尽量贴近屏幕两侧边缘。
+5. 下一关、道具、排行榜仍走现有后端链路，不把外部 I/O 或扣费逻辑塞回前端。

docs/technical/PUZZLE_IMAGE_AND_RUNTIME_9_16_ALIGNMENT_2026-04-29.md

@@ -1,42 +0,0 @@
-# 拼图图片生成与运行时 9:16 对齐 2026-04-29
-
-## 背景
-
-拼图生成图和运行时画面需要统一为竖屏游戏口径。此前链路里存在两类不一致：
-
-1. 旧方案按 `1:1` 正方形生成与承载。
-2. 上一轮误按 `16:9` 横版对齐，和本轮竖屏玩法目标相反。
-
-本次统一为 `9:16` 竖屏尺寸，确保生成图、结果页预览、发布正式图、历史素材缩略和实际游戏棋盘使用同一画面比例。
-
-## 落地结论
-
-### 1. 图片生成
-
-1. 拼图生成图固定使用 `720*1280`。
-2. 文生图和参考图生图共用同一个尺寸常量，禁止一条链路仍生成正方形或横版图。
-3. 拼图图片提示词明确写入 `9:16 竖屏画布`，并继续保留 `3x3 或 4x4 拼图切块`、主体清晰、层次明确、无文字水印等约束。
-4. 图片生成仍由 `api-server` 执行。SpacetimeDB reducer 只负责 session、draft、candidate、work profile 的确定性落库，不做网络 I/O。
-
-### 2. 结果页与素材选择
-
-1. 画面预览容器使用 `aspect-[9/16]`。
-2. 发布弹窗正式图使用 `aspect-[9/16]`。
-3. 历史拼图素材卡片缩略图使用 `aspect-[9/16]`。
-4. 图片显示继续使用 `object-cover`，兼容历史正方形或横版素材，但新生成素材的真相比例为 `9:16`。
-
-### 3. 运行时棋盘
-
-1. `PuzzleRuntimeShell` 继续作为唯一运行时承载组件，不新增页面。
-2. 棋盘根容器使用 `aspect-[9/16]`，并显式设置行列网格，3x3 / 4x4 都在竖屏舞台内切片。
-3. 棋盘最大宽度按可用视口高度反推，避免桌面端竖屏棋盘被宽容器撑出首屏。
-4. 单格不设置固定最小高度，避免移动端竖屏棋盘被单格高度撑破。
-5. 拼图片背景切片仍按 `board.cols * 100%` 与 `board.rows * 100%` 计算，比例由棋盘容器统一决定。
-
-## 验收
-
-1. 点击拼图草稿生成或重新生成画面时，后端请求 DashScope 的 `size` 为 `720*1280`。
-2. 结果页画面预览、发布弹窗正式图、历史素材缩略图均为 `9:16`。
-3. 进入拼图运行时后，棋盘整体为 `9:16` 竖屏，不再是正方形或横版。
-4. 移动端和桌面端运行时棋盘不被单格最小高度撑出首屏，顶部标题、底部状态与棋盘不重叠。
-5. 旧正方形或横版素材仍能被 `object-cover` 展示和游玩，不阻断历史作品。

docs/technical/PUZZLE_RUNTIME_REAL_LEADERBOARD_2026-04-27.md

@@ -103,6 +103,15 @@
 3. 结算弹窗显示时，如果真实榜单尚未回写完成，可以显示加载态；但不能回退到假数据。
 4. 下一关开始后，当前关卡榜单状态清空。
 
+## 7.1 2026-04-29 与前端拖动裁决的对齐
+
+当前拼图拖动、合并、拆分与通关判定完全由前端运行态负责，后端排行榜接口只负责真实成绩表与榜单聚合：
+
+1. 排行榜提交不得依赖 SpacetimeDB 里的旧棋盘快照已经通过后端拖动接口进入 `cleared`。
+2. 后端仍校验 `profileId`、`gridSize`、昵称和成绩，并把当前提交写入真实成绩表。
+3. 后端响应里的 `leaderboardEntries` 是唯一需要合并回前端当前 run 的数据。
+4. 前端不能用排行榜响应里的旧棋盘快照覆盖本地拖动后的棋盘，否则会把刚刚通关的前端状态回滚。
+
 ## 8. 测试要求
 
 至少覆盖：

docs/technical/PUZZLE_SINGLE_PLAYER_AND_REAL_IMAGE_PLAN_2026-04-24.md

@@ -65,6 +65,16 @@
 7. 每次进入下一关都会重置棋盘、推进关卡序号，并按已通关数量切换 `3x3 / 4x4`
 8. 当前不依赖后端 `start/swap/drag/next-level` 接口保存过程状态
 
+## 6. 2026-04-29 拖动责任边界修正
+
+拼图运行态的拖动逻辑完全交给前端：
+
+1. `pointerup` 解析出的目标格只调用前端 `dragLocalPuzzlePiece`。
+2. 单块拖动、合并块整体平移、被覆盖块交换、拆分、重新合并、通关判定，都以前端当前 `PuzzleRunSnapshot` 为准。
+3. Rust API 不再暴露 `/api/runtime/puzzle/runs/{runId}/drag` 给前端调用；后端旧 procedure 仅作为历史兼容实现，不作为当前运行态入口。
+4. 真实排行榜仍由后端成绩表负责；提交成功后，前端只把后端返回的 `leaderboardEntries` 合并回当前本地棋盘快照，不能用后端旧棋盘覆盖前端拖动后的状态。
+5. 下一关仍通过 `advanceLocalPuzzleNextLevel` 把前端当前 run 交给 Rust API 生成候选关卡，后端只裁决图片来源与新关卡初始化，不保存上一关拖动过程。
+
 ## 5. 当前实现判断标准
 
 当下面结果成立时，视为这一轮目标达成：

docs/technical/README.md

@@ -12,6 +12,7 @@
 - [BIG_FISH_DRAFT_PROGRESS_AND_SESSION_TIMEOUT_GUARD_FIX_2026-04-28.md](./BIG_FISH_DRAFT_PROGRESS_AND_SESSION_TIMEOUT_GUARD_FIX_2026-04-28.md)：记录大鱼吃小鱼草稿进度页从单步 compile 改为多阶段感知展示，以及大鱼会话读取在 Maincloud 抖动时增加短重试与超时语义收口的修复口径。
 - [BIG_FISH_PROMPT_MODULE_EXTRACTION_2026-04-28.md](./BIG_FISH_PROMPT_MODULE_EXTRACTION_2026-04-28.md)：记录大鱼吃小鱼草稿生成、生图、动作三类提示词从业务脚本中抽离到独立 `prompt/big_fish.rs` 模块的边界与职责划分。
 - [BIG_FISH_MAIN_IMAGE_TRANSPARENT_BACKGROUND_ALIGNMENT_2026-04-28.md](./BIG_FISH_MAIN_IMAGE_TRANSPARENT_BACKGROUND_ALIGNMENT_2026-04-28.md)：记录大鱼吃小鱼等级主图与动作关键帧正式图在 Rust 后端复用 RPG 角色主图透明背景 alpha 后处理的对齐口径，并明确场地背景不走该处理。
+- [PUZZLE_IMAGE_AND_FRONTEND_RULES_ALIGNMENT_2026-04-29.md](./PUZZLE_IMAGE_AND_FRONTEND_RULES_ALIGNMENT_2026-04-29.md)：记录拼图生成图片回到 1:1，运行时拖动、交换、合并与拆分由前端即时裁决，以及移动端棋盘贴近屏幕边缘的落地边界。
 - [PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md](./PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md)：记录拼图结果页名称与标签编辑自动保存、发布门槛统一到 `3~6` 标签，以及前端发布校验不再被旧 session blocker 卡死的修复口径。
 - [SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md](./SPACETIMEDB_START_SH_EARLY_EXIT_DIAGNOSTICS_2026-04-27.md)：记录发布包 `start.sh` 只输出“SpacetimeDB 进程在就绪前退出”时的诊断补强，启动失败或超时时自动回显 `logs/spacetimedb.log`、`server ping`、端口监听和 root-dir 相关进程。
 - [RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md](./RPG_AND_AGENT_CHAT_TRUE_SSE_STREAMING_2026-04-26.md)：记录 RPG 运行时 NPC 聊天、RPG/自定义世界 Agent 与大鱼 Agent 从“拼完整 SSE 字符串后一次性返回”改为 `mpsc + Sse<Event>` 真流式输出的后端落地口径。