feat: add puzzle clear template runtime

.hermes/shared-memory/pitfalls.md

@@ -1,4 +1,4 @@
-# 踩坑与排障记录
+# 踩坑与排障记录
 
 > 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。
 
@@ -87,6 +87,22 @@
 - 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t \"puzzle draft generation auto starts trial and runtime back opens draft result\"`，确认 `window.location.pathname === '/runtime/puzzle'` 且 `window.location.search` 同时包含 `runtimeProfileId` 和 `runtimeSessionId`。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/services/puzzleRuntimeUrlState.ts`、`src/routing/appPageRoutes.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 拼消消草稿试玩不能只测 swap 回调
+
+- 现象：拼消消结果页和 runtime shell 的单测都能通过，但真实页面里卡片只是交换，完全不会消除，顶部准备区还会因为已知的卡背占位路径显示坏图。
+- 原因：草稿试玩走的是前端本地 runtime，早期测试只覆盖了 `onSwapCards` 回调和局部状态，没有验证完整的消除、重力补牌、关卡完成和资源兜底链路；同时顶部卡背对 `puzzle-clear-card-back.webp` 这类已知缺失资源没有前置回退。
+- 处理：草稿试玩的回归测试必须覆盖“交换 -> 完整图案消除 -> 补牌 -> 关卡完成”闭环，并在组件测试里验证真实点击/拖拽序列；顶部准备区卡背遇到已知占位路径时直接回退到 `puzzle.webp` 这类可用参考图，不等图片加载失败后再兜底。
+- 验证：`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 通过，浏览器 smoke 页实测可完成一次消除并弹出“本关完成”。
+- 关联：`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消消除过渡不能隐藏已有卡片的最终下沉格
+
+- 现象：消除补牌过程中偶尔看起来下方有空位，但同列上方卡片没有落下来。
+- 原因：后端和本地 runtime 的重力补牌已经把已有卡片压到底；真正的问题在前端过渡层。消除动画曾按旧消除坐标隐藏棋盘格，掉落动画也曾隐藏所有 drop 目标格。当某个旧卡下沉到刚被消除的格子时，最终 snapshot 里的真实卡片会被隐藏，视觉上像补牌没有落下。
+- 处理：消除 / 掉落覆盖层只负责动画表现，不再隐藏已有场上卡片的最终格；只有从顶部准备区新补入、前一帧棋盘不存在的卡片，才允许临时隐藏底层目标格来配合下落动画。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx -t "已有卡片因重力下沉时目标格不被过渡状态隐藏成空位"`，并保留领域侧 `cargo test -p module-puzzle-clear refill --manifest-path server-rs/Cargo.toml`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`server-rs/crates/module-puzzle-clear/src/application.rs`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
+
 ## 首页推荐分流参数不能条件性调用 hook
 
 - 现象：桌面首页或移动首页在 HMR、断点切换或重新渲染后直接报 React hook 顺序错误，页面停在“正在加载内容”。
@@ -955,6 +971,14 @@
 - 验证：`cargo test -p api-server phone_auth_sms_provider_errors_keep_upstream_http_semantics --manifest-path server-rs/Cargo.toml`，真实 provider 频控时接口不再返回 `500`。
 - 关联：`server-rs/crates/module-auth/src/errors.rs`、`server-rs/crates/api-server/src/phone_auth.rs`、`docs/technical/PHONE_SMS_PROVIDER_ERROR_HTTP_MAPPING_FIX_2026-05-08.md`。
 
+
+## 本地短信 smoke 先确认 SMS provider
+
+- 现象：浏览器里短信验证码发送成功，但提交 `123456` 仍然报验证码错误，或者短信登录后又回到未登录态。
+- 原因：当前运行中的 `api-server` 如果读取到 `.env.local` 里的 `SMS_AUTH_PROVIDER=aliyun`，就会走真实短信 provider 口径；这时 mock 验证码 `123456` 不会被接受。之前本地调试时常见的误判是把 `.env.local` 改成 mock 了，但没有重启 `npm run dev`，或者旧的 `scripts/dev.mjs` 进程还在沿用旧环境。
+- 处理：本地只做 UI / 账号链路 smoke 时，把 `.env.local` 显式设为 `SMS_AUTH_PROVIDER=mock` 且配置 `SMS_AUTH_MOCK_VERIFY_CODE=123456`，然后重启 `npm run dev` 或 `npm run dev:api-server`。要做真实短信联调时，再切回 `SMS_AUTH_PROVIDER=aliyun` 并重启。
+- 验证：`POST /api/auth/phone/send-code` 应返回 `providerRequestId=mock-request-id`；`POST /api/auth/phone/login` 用 `123456` 应返回 `200` 且 `user.loginMethod=phone`。浏览器侧短信登录成功后，会先进入邀请码弹窗或我的页面，不应再提示“验证码错误”。
+- 关联：`scripts/dev-utils.mjs`、`scripts/dev-utils.test.ts`、`scripts/dev.mjs`、`server-rs/crates/api-server/src/config.rs`。
 ## 手机验证码登录成功后又瞬间回到未登录
 
 - 现象：手机号验证码登录先成功，随后 UI 又闪回“未登录”，登录弹窗可能重新出现。
@@ -1665,3 +1689,110 @@
 - 处理：推荐页拖拽只校验当前是否有作品、多作品可切换以及是否正在提交动画，不再要求登录；登录态相关操作仍由点赞、改造等按钮自身权限控制。
 - 验证：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 覆盖访客态纵向滑动不弹登录且触发下一条推荐。
 - 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
+
+## Windows junction worktree 下 Vitest 定向路径失败先切真实路径
+
+- 现象：在 `C:\Users\...\ .codex\worktrees\...` 这类 junction 工作区运行 `npm run test -- src/...` 时，Vitest 可能报 `Failed to load url C:/Users/... (resolved id: F:/DevWorktrees/...)`，同一测试文件明明存在却被判定找不到。
+- 原因：Vite / Vitest 在 Windows 下会把测试入口 realpath 到真实 worktree 路径；如果命令从 junction 路径传入相对文件参数，入口路径和 resolved id 可能跨盘符不一致。
+- 处理：前端定向测试优先从 `Get-Item <worktree> | Format-List Target` 显示的真实路径运行，例如 `F:\DevWorktrees\codex\worktrees\f584\Genarrative`；不要把这类文件加载失败误判成组件或路由断言失败。
+- 验证：同一命令从真实路径执行应正常收集并运行测试，例如 `npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+- 关联：`src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx`、`src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/routing/appPageRoutes.test.ts`。
+
+## 拼消消草稿试玩要和正式 runtime 分流
+
+- 现象：拼消消结果页点击“试玩”后如果仍然调用 `/api/runtime/puzzle-clear/runs`，草稿试玩会被正式 run 规则和统计约束卡住，公开作品又可能和草稿恢复串台。
+- 原因：拼消消既有草稿生成 / 结果页 / 发布闭环，也有正式公开 runtime；如果把结果页试玩和公开运行态复用同一个后端 startRun 入口，`work detail` 读取路径和统计口径都会混在一起。
+- 处理：结果页试玩改走前端本地 `runtimeMode=draft` snapshot，只用于草稿试玩和关卡切换，不写正式 run；公开详情和推荐流进入正式 runtime 时才走后端 `/api/runtime/puzzle-clear/*`。客户端读取作品详情时也要区分创作详情 `/api/creation/puzzle-clear/works/{profileId}` 与公开运行态详情 `/api/runtime/puzzle-clear/works/{profileId}`。
+- 验证：点击拼消消结果页的试玩按钮，不应再请求 `/api/runtime/puzzle-clear/runs`；公开详情入口仍应能读取后端运行态详情。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/services/puzzle-clear/puzzleClearClient.ts`、`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`。
+
+## 拼消消 runtime 必须继承拼图模板的原生交互基线
+
+- 现象：拼消消卡片在浏览器里会出现原生图片拖拽 / 下载手柄，或窗口拉伸后棋盘和卡片被拉成矩形。
+- 原因：拼消消 runtime 早期只继承了“交换 / 消除”的业务逻辑，没有完整继承拼图模板在基础交互上的防护：`touch-none`、`select-none`、`aspect-square`、`draggable={false}`、`onDragStart(event.preventDefault())`、`-webkit-user-drag: none`。
+- 处理：棋盘容器必须保持正方形约束，卡片按钮和内层 `<img>` 都要显式禁用浏览器原生拖拽，样式层也要补 `user-select: none` 与 `-webkit-user-drag: none`，不能只靠业务指针逻辑。
+- 验证：浏览器中检查棋盘 `getBoundingClientRect().width === height`，卡片图片 `draggable="false"` 且 `-webkit-user-drag` 为 `none`；真实拖拽只应进入交换逻辑，不应触发原生图片拖拽。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/index.css`、`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消拖拽浮层要挂到页面级 portal
+
+- 现象：拼消消拖拽时图片看起来没有贴在鼠标或手指上，尤其是平台壳层本身带有 transform 时更明显。
+- 原因：拖拽 ghost 用了 `position: fixed`，但如果还挂在会被 transform 的局部容器里，浏览器会把 fixed 当成相对该祖先定位；`clientX/clientY` 读到的是视口坐标，两个坐标系一混就会出现肉眼可见的偏移。
+- 处理：拖拽浮层必须通过 portal 挂到 `document.body` 这一层，再继续使用 `clientX/clientY - pointerOffset` 计算 left/top；不要把 ghost 留在平台壳或任何会参与 transform 的容器里。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 应断言拖拽浮层父节点是 `document.body`，且 left/top 与按下点偏移一致。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消要继承拼图模板的动作语言，不只是规则
+
+- 现象：拼消消如果只实现“交换后裁决”，但没有开局翻牌、按下留空位、被替换卡快速飞回、以及局部拼接块整体拖动，玩家会直觉上觉得比原拼图更笨重。
+- 原因：早期实现容易把“规则独立”误读成“动作语言也要重写”，结果只保留了交换逻辑，没有沿用拼图模板里已经验证过的拖拽反馈、空位让位和合并块连续感。
+- 处理：拼消消运行态要继承拼图模板的基础手感：只在开局保留入场翻牌，拖起时源位立即呈空，放下时被替换卡要有明确飞向空位的位移感，连通块要作为整体拖动和整体呈现。
+- 验证：浏览器拖拽时能看到跟手 ghost、源位空槽、落点飞入和整组拼接层；`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 应覆盖这些行为。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/index.css`。
+
+## 拼消消空格位必须允许落位，不能当成不可交互死格
+
+- 现象：运行到某一关后，棋盘里出现空格位，用户能看见空洞但拖不进去，也点不动。
+- 原因：空格位被前端交互或后端裁决误当成“无效目标”，只保留了交换逻辑，没有把“源卡落入空位、源位清空”当成合法移动。
+- 处理：空格位必须保留 button 交互态和落点命中逻辑；前端拖拽 / 点击落到空格时直接提交移动，后端和本地 runtime 都要把源卡移动到目标格并清空源格，不再走失败交换。
+- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml player_move_can_drop_card_into_empty_target_cell -- --nocapture`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`。
+
+## 拼消消空位落卡后必须立即补位，不能把空洞留成真空格
+
+- 现象：卡牌成功落进空格后，源位仍然留空，玩家会误以为那个格子坏掉了。
+- 原因：移动逻辑只处理了“落到空位”，没有在未消除时同步走一遍重力补位，所以源列会短暂或永久留下空洞。
+- 处理：只要移动后棋盘存在空位，就立即走补位和可解性修复；这样源位会从顶部准备区补卡，不会留下不可交互空洞。
+- 验证：`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml player_move_can_drop_card_into_empty_target_cell -- --nocapture`。
+- 关联：`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`。
+## 拼消消锁定组覆盖层必须锚定在棋盘本身
+
+- 现象：消除或补牌过程中，局部完成的组图偶尔会看起来从格子里“飘出去”，并且大小会随着窗口和外层面板变化而异常拉伸。
+- 原因：锁定组视觉层用了 `absolute inset-0`，但棋盘容器本身不是 `position: relative`，于是覆盖层实际锚到了更外层的运行态面板，`gridColumn` / `gridRow` 只能在错误坐标系里排版。
+- 处理：棋盘容器必须显式 `relative`，让锁定组覆盖层、拖拽鬼影和格子坐标都在同一正方形棋盘坐标系内排版；不要把这类覆盖层锚到外层 `section` 或整页容器。
+- 验证：浏览器里棋盘 `getBoundingClientRect()` 和锁定组覆盖层应共享同一块正方形区域，窗口缩放后组图不应再出现越界或被拉伸的现象；`PuzzleClearRuntimeShell.test.tsx` 需要断言棋盘 class 包含 `relative`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
+
+## 拼消消中央场地底图必须挂在棋盘内部
+
+- 现象：创作阶段选择了中央场地底图，但运行态消除卡片后只看到浅色格子或空点，看不到底图。
+- 原因：底图被渲染成整页氛围背景，并被页面渐变、棋盘面板和格子 `bg-white/78` 遮住；棋盘内部没有静态底图层，空格仍保留不透明卡片底色。
+- 处理：`boardBackgroundAsset.imageSrc` 必须作为 `puzzle-clear-board` 内部的 `absolute inset-0` 静态底图渲染；空格、消除空位和拖拽源位必须透明或近透明，不能继续使用实体卡片白底。
+- 验证：`PuzzleClearRuntimeShell.test.tsx` 断言 `puzzle-clear-board-background` 在棋盘内，`/board-bg.png` 只出现一次，空格 class 包含 `bg-transparent` 且不包含 `bg-white/78`。
+- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 创作入口突然消失先查前后端是否串到不同 worktree
+
+- 现象：`http://127.0.0.1:3000/` 可访问，但创作 Tab 里新增玩法入口消失；例如 `puzzle-clear` 已在代码默认种子中存在，浏览器仍看不到“拼消消”。
+- 原因：Vite 可能来自当前 worktree，但代理目标的 `api-server` 仍是另一个 worktree 的旧进程，或者 `api-server` 连到旧 SpacetimeDB 模块；此时 `/api/creation-entry/config` 会返回旧入口配置。
+- 处理：先用 `Get-NetTCPConnection -State Listen -LocalPort 3000,8083,3103` 结合 `Get-CimInstance Win32_Process` 确认端口进程路径；停止串线的旧 `api-server`，再用当前 worktree 的 `npm run dev:spacetime -- --spacetime-port <port> --database <database>` 和 `npm run dev:api-server -- --api-port <port> --spacetime-port <port> --database <database>` 拉起同一套服务。
+- 验证：`GET /api/creation-entry/config` 应包含目标入口，且监听端口的命令行都指向同一个 worktree；浏览器创作 Tab 对应分类应显示入口卡。
+- 关联：`scripts/dev.mjs`、`.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## Windows junction 工作区下 dev.mjs 直接执行入口要用 realpath 判断
+
+- 现象：在 `C:\Users\...\ .codex\worktrees\...` 这类 junction 路径里运行 `npm run dev:web`，进程会秒退，`3000` 不监听，但同一脚本从真实 worktree 路径能正常启动。
+- 原因：`scripts/dev.mjs` 的入口判断只比对 `process.argv[1]` 和 `import.meta.url` 的字面路径；junction 路径和 realpath 路径不一致时会误判成“不是直接执行”，于是主流程根本不进入。
+- 处理：入口判断改成基于 `realpathSync(...)` 的 `isDirectModuleExecution(...)`，让 junction 路径和真实 worktree 路径指向同一个模块；同时补回归测试覆盖该场景。
+- 验证：`npm run test -- scripts/dev.test.ts scripts/dev-stack-port-utils.test.ts` 通过后，`npm run dev:web -- --web-port 3000 --api-port 8083 --no-interactive` 应能稳定把 `0.0.0.0:3000` 监听起来。
+- 关联：`scripts/dev.mjs`、`scripts/dev.test.ts`。
+
+## Vitest 定向测试在 Windows junction 工作区要切真实路径
+
+- 现象：在 `C:\Users\...\ .codex\worktrees\...` 这类 junction 路径里跑 `npm run test -- src/...` 时，Vitest 会报 `Failed to load url ... (resolved id: F:/DevWorktrees/...)`，看起来像文件不存在。
+- 原因：Vite / Vitest 会把入口 realpath 到真实 worktree 路径；如果命令从 junction 路径传入相对文件参数，入口路径和 resolved id 可能跨盘符不一致。
+- 处理：前端定向测试优先从真实路径 `F:\DevWorktrees\codex\worktrees\f584\Genarrative` 运行，不要把这类文件加载失败误判成组件或路由断言失败。
+- 验证：同一命令从真实路径执行应正常收集并运行测试。
+- 关联：`src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/routing/appPageRoutes.test.ts`。
+- 现象：新增或扩展 `*-generating` 页面后，生成卡只渲染首帧，`已耗时` / `预计等待` 停在进入页那一刻不动。
+- 原因：平台壳层的共享 `miniGameGenerationProgressNowMs` 时钟没有把新生成阶段纳入 tick 条件，或者该阶段的 `buildMiniGameDraftGenerationProgress(..., nowMs)` 没有接入同一时钟。
+- 处理：任何共享生成页都要通过平台壳层统一的时钟判断和 `nowMs` 传递刷新，新增生成阶段时要同时补 `selectionStage` 判定、`useEffect` 依赖和进度调用点。
+- 验证：浏览器里进入对应生成页后，`已耗时` / `预计等待` 应持续变化，不应停在首帧。
+
+## 拼消消要用真实可消除判断，不要把“已相邻”当成可解
+
+- 现象：拼消消开局或补牌后会直接出现已完成的图案组，或者 `1x2` 被当成半锁定局部留在场上。
+- 原因：早期把可解性写成“场上已经有同组相邻卡”或“只要有一对相邻同组卡就算可解”，这会把已完成盘面误当成合法盘面；同时半锁定规则没有排除 `1x2`。
+- 处理：开局和补牌后的重排必须先排除现成消除，再用真实交换 / 落位模拟判断是否会产生新消除；`1x2` 永远不进入半锁定组，半锁定只允许 `1x3`、`2x2`、`2x3`。
+- 验证：`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 与 `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml -- --nocapture` 通过后，开局盘面不应直接出现 completed group。
+- 关联：`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`。