记录 kind 别名只救新登记不救存量 category 的陷阱

- 补记 ui 资产落待归类的完整成因链：kind 兜底 image 再经 image → unclassified 误分
- 写明 register_local_asset_entry 命中同路径时不重算 category，故存量 57 条无法自愈
- 写明读取侧必须信任落盘 category 的原因：存在用户手动改分类的正式链路
- 列出三个根治选项供拍板：读时重派生 / 一次性回填 / 只改写入侧
- 记录别名表在 TS 与 Rust 各有一份实现、必须成对维护，以及交叉守卫位置

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

@@ -5144,3 +5144,14 @@
 - 门禁为什么抓不到：单测夹具本身就是毫秒值（`createdAt: 1_760_000_000_000`），断言用 `new Date(夹具值)` 反推期望，**夹具和实现一起错**，用例自洽却失真。
 - 验收口径：夹具必须与落盘口径一致（真实秒值），并用已知秒值断言渲染出的年月日（`1788075047` → `2026/8/30`），而不是只断言"不等于 1970"。改成 `new Date(createdAt)` 时该用例会失败（已实测）。
 - 关联：`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasVersionBindingModel.ts`、`packages/shared/src/contracts/gameCreationApp.ts`、`apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs`。
+
+## 资源 kind 别名只救新登记，不救存量 category（2026-09-10）
+
+- 现象：真机 `What do u wanna do kitten` 的 66 项资源里 58 项落「待归类」，其中 57 项是 `kind:"ui"` 的 UI 资产，本该在「UI 交互」。
+- 成因链：`ui` 不在 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` 里、也没有别名，于是走 `canonicalGameCreationAppAssetKind` 的 `image` 兜底，再经 `image → unclassified` 被误分到「待归类」。它并不是历史遗留值——`assets.rs:1656` 的 `infer_canvas_export_asset_kind`（画板导出导入）**现在仍在写出** `ui` / `animation` / `asset`。
+- **关键陷阱**：补别名只影响「今后新登记」的资产。`register_local_asset_entry`（`assets.rs:1748-1757`）命中同 `localPath` 的既有资产时只覆盖 `kind` / `media_type` / `source`，**不重算 `category`**；而读取侧 `gameCreationAppAssetCategory` 优先信任落盘 `category`、只在它缺失或非法时才按 `kind` 派生。所以这 57 条的落盘 `category: "unclassified"` 会一直有效，重导入也自愈不了。
+- 为什么读取侧要信任落盘值：存在用户手动改分类的正式链路 `update_manifest_asset_classification_at`（`project/manifest.rs:1110`），读时无条件重派生会吃掉用户的手动设置。
+- 根治选项（需产品拍板）：① 读时把 `unclassified` 当作「未设置」再按 kind 派生（简单但失去"我就是要 unclassified"的表达力）；② 一次性回填这 57 条（保留人工设置语义，需迁移脚本）；③ 只改写入侧让新素材 canonical 化（治不了存量）。
+- 另一处必须成对维护：别名表有**两份实现**——TS 侧 `packages/shared/src/contracts/gameCreationApp.ts` 的 `GAME_CREATION_APP_LEGACY_ASSET_KINDS`（读投影用）与 Rust 侧 `server-rs/crates/shared-contracts/src/game_creation_app.rs` 的 `canonical_game_creation_app_asset_kind`（写入侧按 kind 派生 category 用）。只改一边就会让落盘 category 与读侧栏目互相矛盾。交叉守卫见 `apps/ai-game-creator-shell/tests/assetKindCanonicalMapping.test.ts`（直接解析 Rust 源码比对）。
+- 真机计数守卫见 `apps/ai-game-creator-shell/tests/resourceCardPreviewRealManifest.test.ts`。
+- 关联：`apps/ai-game-creator-shell/src-tauri/src/assets.rs`、`apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs`、`packages/shared/src/contracts/gameCreationApp.ts`、`server-rs/crates/shared-contracts/src/game_creation_app.rs`。