修复UI设计状态浮点回读失败

统一 UI State 写入与严格回读的浮点序列化表示

补充拖拽 Transform 与灵体素材保存回归测试

记录 UI State 浮点 JSON 校验排障经验

docs/project-memory/shared-memory/pitfalls.md

@@ -14,6 +14,14 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## UI 设计 State 的 strict JSON round-trip 不能混用两种浮点序列化表示（2026-08-19）
+
+- 现象：为节点拖拽/缩放生成非整数 Transform 后，保存报“UI 设计 State 安装后回读与待写内容不一致”；由于读取主文件失败关闭后恢复 `.previous`，后续回读表现为刚导入的 spirit/sprite 资产丢失。
+- 原因：写入使用 `serde_json::to_vec_pretty`，它对 `f32` 输出短十进制（如 `348.5318`）；读取端却以 `serde_json::to_value` 重建 canonical JSON，重新扩展为精确二进制值（如 `348.53179931640625`）。两者作为 `serde_json::Value` 不相等，合法的新主文件被误判为不受支持，然后错误回退到旧恢复副本。
+- 处理：严格 envelope 检查必须使用与磁盘写入相同的 `serialize_ui_design_document` 再解析为 `Value`，仍拒绝未知字段/值，却允许合法 `f32` 的稳定文件表示；不可再把 `to_vec_pretty` 与 `to_value` 的数字文本直接比较。
+- 验证：持久化回归使用带 `spirit` sprite、`Image.target_graphic` 引用及拖拽式非整数 Transform 的完整 State，断言保存返回和后续 load 均完整相等；同时保留旧空对象/未知 envelope 字段拒绝、CAS 和 `.previous` 恢复测试。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/ui_editor/persistence.rs`。
+
 ## 资源管理第二轮修复后不能继续用第一轮文档和弱测试作为验收合同
 
 - 现象：代码已经改成分区内 SVG plane 和卡内媒体，文档仍要求单全局 Overlay 或中央大图；CSS 正则和浅层 AppSurface 测试保持绿色，但真实 Tauri WebView 仍会默认缩放、主动预览请求饥饿、过滤后媒体继续播放或超深布局反复提交非法坐标。