记录资源预览读取分支与版本时间的排查口径

- PRD 明确队列身份用的 category 是资源分区栏目、只用于前端去重与布局，不作为 IPC 入参
- PRD 明确 read_local_project_media_preview 的线上 category 是原生读取分支，只接受 art / audio，须由卡片预览类型派生
- pitfalls 新增「媒体预览 category 是读取分支而非栏目」：记录阶段二把用例一起改成错误行为导致门禁失守，并写明现有守卫位置与实测失败口径
- pitfalls 新增「versions[].createdAt 是 Unix 秒」：记录夹具与实现一起错导致门禁失真，以及已知秒值断言年月日的验收口径

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

@@ -5126,3 +5126,21 @@
 - 排查口径：任何"复用了共享画布子组件、但没复用 `CanvasViewport`"的宿主，都要先确认这些子组件依赖的根类由谁渲染；共享 CSS 里出现没有 fallback 的 `var(--genarrative-image-canvas-*)` 时，缺根类就是静默丢样式。
 - 验证：AGC 侧用真实 `pointerdown` / `pointermove` 造框选，断言选择框存在、内联几何非空，且最近的 `.genarrative-image-canvas` 祖先就是画本场景根；把根类去掉后该用例会失败（已实测）。
 - 关联：`packages/image-canvas-react/src/styles.css`、`packages/image-canvas-react/src/SelectionOverlay.tsx`、`packages/image-canvas-react/src/CanvasViewport.tsx`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`。
+
+## AGC 卡片媒体预览的线上 `category` 是读取分支，不是画布分区栏目（2026-09-10）
+
+- 现象：真机资源画布上大量卡片只显示占位方框图标，没有真实缩略图；门禁全绿。
+- 原因：`read_local_project_media_preview` 的入参 `category` 在原生侧只认 `art` / `audio`（`apps/ai-game-creator-shell/src-tauri/src/commands.rs` 的 `read_local_project_media_preview_at`：`"art" => Art` / `"audio" => Audio` / `_ => Err("媒体预览类别只支持 art 或 audio")`）。阶段二（`2f8753f59`）把 `ProjectResource.category` 从旧的资源类型轴（`art` / `audio` / `code` / `document`）换成 6 类资产分类栏目轴（`ui-interaction` / `character` / `scene` / `audio` / `document` / `unclassified` / `version`），而调用点仍然透传 `job.resource.category`，于是栏目值被原生侧直接拒绝，所有走媒体分支的卡片（GIF / SVG / AVIF / BMP / MP4 / WebM / MOV 与音频）全部读不出预览。PNG / JPEG / WEBP 走 `read_local_project_image_preview`，该命令没有 `category` 入参，所以照常加载——这就是"有些图正常、有些图全不加载"的分裂观感。
+- 处理：新增 `projectResourceMediaPreviewCategory(resource)`，从卡片预览类型（`projectResourceCardPreviewKind`）派生线上取值，与分区栏目轴解耦；调用点不再传栏目。
+- 门禁为什么抓不到：阶段二把用例一起改成了错误行为——`tests/appSurface/project-development.suite.ts` 的 mock 注释直接写成"媒体读取的 `category` 现在传资源所在的功能栏目"并按 `relativePath` 返回，`tests/useProjectResourceCardPreviews.test.ts` 把断言从 `category: 'art'` 改成 `category: 'unclassified'`。**用例断言的是自己刚写的行为，不再对齐原生契约**，所以改坏也不会有红灯。
+- 验收口径：断言必须钉住原生侧真实取值。现有守卫在 `tests/useProjectResourceCardPreviews.test.ts`（扩展名图片必须发 `category: 'art'`、音频必须在播放意图后发 `category: 'audio'`）与 `tests/appSurface/project-development.suite.ts`（`icon.svg` 必须发 `category: 'art'`，即便它落在「UI 交互」栏目）。把调用点改回 `job.resource.category` 时这两条会失败（已实测）。
+- 关联：`apps/ai-game-creator-shell/src/view/project-development/resourceCardPreviewModel.ts`、`useProjectResourceCardPreviews.ts`、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`。
+
+## AGC `versions[].createdAt` 是 Unix 秒，渲染前必须 ×1000（2026-09-10）
+
+- 现象：游戏版本选择器里所有版本都显示 `1970/1/22 00:41:17`。
+- 原因：写入侧 `apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs` 的 `created_at: unix_timestamp()`（两处：`ensure_initial_game_iteration_version_at`、`append_agent_game_iteration_version_at`），而 `unix_timestamp()` 取 `SystemTime::duration_since(UNIX_EPOCH).as_secs()` —— 单位是**秒**。显示侧 `formatIterationVersionLabel` 却写成 `new Date(version.createdAt)`，秒值被当成毫秒，`1788075047` → `1970/1/22 00:41:15`。
+- 处理：`new Date(version.createdAt * 1000)`，与既有秒口径（`ResourceAssetDeleteDialog.tsx`、待确认资源编辑创建时间标签）保持一致；并给 `GameIterationVersion.createdAt` 补契约注释写明单位。
+- 门禁为什么抓不到：单测夹具本身就是毫秒值（`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`。