补预览桥注入与去重的覆盖空白说明

- 踩坑记录新增 2026-10-05 条：preview.rs 的标签注入与去重没有用例覆盖，列出 4 个既有用例并给出人工验证清单
2026-10-05 15:43:41 +08:00
parent 629369eb0c
commit 8d1980488e
1 changed files with 7 additions and 0 deletions
@@ -22,6 +22,13 @@
 - **结论（现行口径）**：改桥后必须重启 AGC 客户端才生效——先确认没有在跑的 AGC Vite（3080 等端口空闲）再 `npm run agc`；只刷新页面、只重启后端或只重装 npm 依赖都无效。核实内嵌版本：在 exe 二进制里搜新代码标记，或比对 `resources/preview/local-preview-fit.js` 的 sha256。
 - **关联**：`apps/ai-game-creator-shell/src-tauri/src/preview.rs`（`PREVIEW_FIT_BRIDGE_SCRIPT`）、`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`、`genarrative-dev-stack-port-routing`（端口探测与 `npm run agc` 口径）。

+## 2026-10-05 预览桥的注入与去重在 Rust 侧没有用例覆盖
+
+- **现象 / 风险**：改动 `preview.rs` 的注入逻辑（`inject_preview_fit_bridge` / `build_preview_response` / `PREVIEW_FIT_BRIDGE_TAG`）时，没有自动化门禁会告诉你「标签没注入」或「注入了两次」。两种失效都只在运行时才暴露：没注入等于整套运行画面点选静默失效（桥脚本的尺寸上报与点选都不执行，页面看起来完全正常）；注入两次会让桥的监听、尺寸上报与点选回调各注册一遍，页面同样看不出差别。
+- **现状**：`preview.rs` 的 `mod tests` 只有 4 个用例——`npm_preview_requires_build_and_prefers_bundled_assets`、`root_layout_serves_root_entry_and_keeps_legacy_paths_available`、`root_layout_does_not_expose_control_or_data_directories`、`legacy_layout_serves_root_ui_modules`；它们只断言预览路由的选取、状态行与页面自身文本，不涉及桥标签是否出现、出现几次，也不覆盖 `scan_preview_fit_bridge_html` 的「页面已带标签就不重复注入」分支（`inject_preview_fit_bridge` 里的 `if scan.has_bridge_script { return html.into_bytes(); }`）。
+- **结论（现行口径）**：这类「把常量原样返回 / 标签字符串存在」的转发型行为不固化成长用例（仓库口径：复制与源码文本断言不进测试）。改注入逻辑时按人工验证清单核对：① 响应 HTML 里 ``<script src="/__genarrative/local-preview-fit.js"></script>`` 出现在 `</body>` 前，且是经典脚本（不带 `type` / `nomodule`）；② 页面自身已带该标签时，响应里的标签数量不增加；③ `/__genarrative/local-preview-fit.js` 返回 200，且内容与 `resources/preview/local-preview-fit.js` 逐字节一致（`include_str!` 内嵌，可比 sha256）。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/preview.rs`（`PREVIEW_FIT_BRIDGE_SCRIPT` / `PREVIEW_FIT_BRIDGE_TAG` / `inject_preview_fit_bridge`）、`apps/ai-game-creator-shell/src-tauri/resources/preview/local-preview-fit.js`。
+
 ## 2026-10-04 Phaser 4 `hitTestPointer` 的返回顺序不是叠放顺序

 - **现象**：运行画面点选 Phaser 4 画面时，按「数组第一个 / 最后一个」当最上层会点错对象——点的是上层精灵，引用却落到下层的素材上；对象越多越容易错。