Merge branch 'fix/agc-preview-alpha-background' into fix/agc-canvas-acceptance-batch

docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md

@@ -101,6 +101,8 @@
 
 先记住状态枚举：`data-preview-kind` ∈ `raster-image | media-image | video | audio | code | document | version | placeholder`；`data-preview-status` **只有 `idle | loading | loaded | failed` 四个值，不存在 `unsupported`**。"不适用"不是状态，表现为**永远 idle**。
 
+棋盘格底另有一条独立判据：`data-preview-has-alpha` **只在预览已加载且这张图真的带 alpha 通道时才写 `'true'`**（原生头部判据：PNG colorType 4/6 或 `tRNS`、WebP alpha 标志；JPEG 恒不透明）。缺属性与不透明同档，卡面退回纯色底。因此「真透明底」与「AI 把棋盘格画进像素里」不再同形：**看 `data-preview-has-alpha` 而不是看卡面有没有棋盘格**。
+
 ```js
 // ① 全量分布（首选）
 [...document.querySelectorAll('.game-resource-card[data-preview-kind]')]
@@ -120,6 +122,11 @@
 [...document.querySelectorAll('.game-resource-card[data-preview-status="loaded"]')]
   .filter(e => !e.querySelector('.game-resource-card-visual img, .game-resource-card-visual video'))
   .map(e => [e.dataset.resourceCardId, e.dataset.previewKind])
+
+// ⑤ 真假透明底：已加载的图片卡按 alpha 分组
+//    真透明（true）才应有棋盘格底；AI 画了棋盘格的不透明图这里必须是 undefined
+[...document.querySelectorAll('.game-resource-card[data-preview-status="loaded"][data-preview-kind="raster-image"], .game-resource-card[data-preview-status="loaded"][data-preview-kind="media-image"]')]
+  .reduce((m, e) => { const k = e.dataset.previewHasAlpha ?? '(无 alpha 判据)'; m[k] = (m[k] || 0) + 1; return m; }, {})
 ```
 
 | 现象 | 说明 | 第一眼做什么 |
@@ -128,6 +135,7 @@
 | `failed` + `data-preview-error` | 读取或解码真失败，读 `data-preview-error` 原文 | `retryable=false` 表示永久失败（超尺寸、损坏、类型不支持、不安全 SVG）；可见性预取遇 failed 会直接放弃，不会自愈 |
 | `loaded` 但无主体节点 | 原生返回的 dataUrl 为空、或解码不出画面 | 这类**不报错**，只能靠脚本 ④ 抓 |
 | `placeholder` + `idle` | **不适用**（游戏代码、无法识别的二进制产物等），正常 | 不要当 bug 报 |
+| 卡面有棋盘格但 `data-preview-has-alpha` 缺失 | **这张图其实不透明**：棋盘格是图里画进去的（旧构建会额外再铺一层卡面棋盘格，两者叠在一起） | 脚本 ⑤ 分组确认；真透明卡才允许有 `'true'` |
 
 **IPC 侧**：预览只走 4 条命令 `read_local_project_image_preview`、`read_local_project_media_preview`、`read_local_project_text_preview`、`cancel_local_project_resource_preview_scope`。媒体那条的 `category` **只接受 `art` / `audio`**，传栏目值会被原生拒绝，表现是卡片全空、没有缩略图。