fix(thumbnail): 缩略图采样 baseColorTexture，修复 MMD 模型显示为白模

现象（用户反馈）：导入 PMX 转换出的 GLB 后，列表页/审核面板里的模型是白模，
脸部颜色信息全部丢失。

定位过程（本地装真 Assimp 6.0.4 + 该模型完整复现）：
1. 转换本身正常：23.7MB GLB、643 骨骼、93,350 面；
2. 18 张贴图逐字节与压缩包原图一致；用一个权威 PMX 解析器比对后确认
   39 个材质 -> 贴图的对应关系与 PMX 完全一致（不是映射错）；
3. UV 采样也正确：脸部材质取到的就是皮肤色 (246,221,216)；
4. 真正的问题在**我们自己的缩略图渲染器**：它刻意不解码 baseColorTexture，
   只用 baseColorFactor 上色（见文件头取舍说明）；而 MMD 模型的
   baseColorFactor 基本都是白色 -> 缩略图必然全白。管理端 3D 预览有贴图，
   只有列表/审核的缩略图是白的。

修复：
1. model-thumbnail.ts 内置极简 PNG 解码器（zlib inflate + 逐行反滤波，
   8 位非隔行，colorType 0/2/3/4/6），按 baseColorFactor x 贴图逐像素采样，
   透视校正 UV；解码失败/非 PNG/隔行扫描回退纯色，绝不抛错；
2. 按 alphaMode 处理透明度：OPAQUE 忽略贴图 alpha（MMD 语义）、
   MASK 按 alphaCutoff 丢弃、BLEND 做 source-over；
3. 取景收紧 FRAMING 1.6 -> 1.3，40px 列表缩略图主体更清楚；
4. 新增 test/model-thumbnail-texture.spec.ts 6 项（含白模回归：
   baseColorFactor 全白 + 红贴图必须输出偏红，以及 MASK/OPAQUE/坏图回退）；
5. 版本 0.2.4，README(.md/.txt)/DSH.md 补修订说明与 FAQ（含重新生成缩略图
   的 reanalyze-models.mjs --force 命令）。

DSH.md

@@ -101,7 +101,7 @@ opendance-web/
 │   ├── admin/                   # React 管理端
 │   │   ├── src/components/ModelReviewPanel.tsx  # 模型审核面板 + 骨骼详细界面
 │   │   └── src/lib/bone-tree.ts                 # 骨骼树过滤（搜索保留祖先链）
-│   ├── test/                    # 单元测试 + 端到端冒烟（13 文件 / 205 项）
+│   ├── test/                    # 单元测试 + 端到端冒烟（14 文件 / 211 项）
 │   │                            #   mmd-vmd 31 / model-archive 24 / model-inspector 25
 │   │                            #   / model-thumbnail 8 / admin-bone-filter 8
 │   │                            #   / preprocess 25 / init-env 16 / admin-port 16
@@ -335,7 +335,7 @@ POST /api/models ─┬─.glb /.vrm /.gltf ─▶ importModelFile()   直接导
   T-pose 角色图；真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms（中位 79ms）。
 - 管理端 3D 预览放开到 `vrm/glb/gltf`(`fbx` 仍提示"仅归档，请先转换为 GLB/VRM");
   列表页显示 40px 缩略图。
-- 测试：`npx vitest run` -> **13 个文件 / 205 项通过**
+- 测试：`npx vitest run` -> **14 个文件 / 211 项通过**
   (`model-inspector` 25、`model-thumbnail` 8、`admin-bone-filter` 8、
   `model-archive` 24、`mmd-vmd` 31、`preprocess` 25、`init-env` 16、
   `admin-port` 16、`access-log` 9、`vrm-inspector` 6）。

README.md

@@ -10,7 +10,14 @@ OpenDance Studio **阶段一**: Web 管理服务端(NestJS + TypeORM + 现有 My
 
 ## 状态
 
-**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.3**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+**阶段一已完成**: T-WEB-001 -> T-WEB-010 全部落地,当前版本 **v0.2.4**(契约 `rest-api / data-models / model-formats 0.4.0`、`database 0.3.0`)。
+
+v0.2.4 修订:
+
+1. **修复缩略图"白模"**:缩略图渲染器原先**刻意不解码贴图**,只用 `baseColorFactor` 上色;而 MMD(PMX 转换)模型的 baseColorFactor 基本都是白色,于是列表页与审核面板里的缩略图全是白色模型。现在渲染器内置极简 PNG 解码器(zlib + 反滤波,8 位非隔行,colorType 0/2/3/4/6)并按 `baseColorFactor x 贴图` 逐像素采样,同时按 `alphaMode`(OPAQUE / MASK / BLEND)处理透明度;解码失败或非 PNG 时回退纯色,绝不抛错;
+2. 缩略图取景收紧(FRAMING 1.6 -> 1.3),40px 列表缩略图里主体更清楚;
+3. 新增 6 项贴图/透明度/朝向测试(`test/model-thumbnail-texture.spec.ts`);
+4. **说明**:GLB 数据本身没问题——贴图逐字节内嵌(18/18)、39 个材质的贴图对应关系与 PMX 完全一致、UV 取到的就是皮肤/五官区域;白模只出在缩略图渲染器。
 
 v0.2.3 修订:
 
@@ -59,15 +66,15 @@ v0.2.0 主要变更:
 3. 取得发布包并校验(地址用你们自己的制品库替换; 下面是本仓库的发布地址)
 
    ```bash
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.3/opendance-web-v0.2.3.tar.gz
-   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.3/SHA256SUMS
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.4/opendance-web-v0.2.4.tar.gz
+   curl -LO https://gitea.kasugano.cn/zijunchiang/opendance-web/releases/download/v0.2.4/SHA256SUMS
    sha256sum -c SHA256SUMS      # 期望输出 "OK"
    ```
 
 4. 解压并生成配置(交互式引导,逐项问答,口令不回显)
 
    ```bash
-   tar -xzf opendance-web-v0.2.3.tar.gz && cd opendance-web-v0.2.3
+   tar -xzf opendance-web-v0.2.4.tar.gz && cd opendance-web-v0.2.4
    bash deploy/init-env.sh
    ```
 
@@ -137,8 +144,8 @@ FLUSH PRIVILEGES;
 ### 5. 部署步骤
 
 ```bash
-tar -xzf opendance-web-v0.2.3.tar.gz
-cd opendance-web-v0.2.3
+tar -xzf opendance-web-v0.2.4.tar.gz
+cd opendance-web-v0.2.4
 bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
 bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 ```
@@ -279,6 +286,7 @@ bash /opt/opendance/deploy/ctl.sh status | restart | logs
 | 服务本机 curl 通、外部访问不了 | `bash deploy/check-access.sh` 一次定位:打印 `HOST`/`PORT`、实际监听地址、对外 IP 自测、80/443 有无反代、防火墙放行情况,并给出修复命令 |
 | 管理页面打开是 404 | 说明访问的是软件 API 端口(默认 3000);管理页面在管理端端口(默认 3001) |
 | 上传 `.zip` / `.pmx` / `.fbx` 报转换失败(ENOENT / Assimp 不可用) | PMX/FBX 转换依赖外部 Assimp:`apt-get install -y assimp-utils`(RHEL 系 `dnf install -y assimp`,`install.sh` 现在会尝试自动安装)。装好后**不需要重启服务**;若不在服务 PATH 中,在 `deploy/.env` 设 `ASSIMP_BIN` 为绝对路径。只上传 `.glb` / `.vrm` 则不需要它 |
+| 列表/审核里的缩略图是"白模"(纯白模型) | v0.2.4 前的缩略图渲染器不采样贴图,而 MMD 模型的 `baseColorFactor` 是白色。升级到 v0.2.4 后重新生成缩略图:`cd /opt/opendance/web-server && node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000 --force` |
 | 导入模型返回 **500 Internal server error** | 老库上多为 `models.stats` 超长(骨骼树按骨骼展开,643 骨骼即 70,980 字节 > TEXT 上限):执行 `ALTER TABLE models MODIFY stats MEDIUMTEXT NULL;` 或部署 v0.2.3(`install.sh` 会自动跑迁移)。v0.2.3 起服务端另有兜底,不会再 500 |
 | 安装时报 `command not found` / 退出码 127,且提示指向 `deploy/.env` 某一行 | 该行的值含空格或 shell 元字符却没加引号,被 shell 当成命令执行了。按预检提示给这个值加引号(如 `MODEL_CONVERT_PMX="Hatsune Miku.pmx"`)后重跑;`deploy/env-lib.sh` 会提前拦住并给出行号 |
 | 模型审核界面显示"未分析 / 无预览图" | 该模型是升级前入库的:调 `POST /api/models/<id>/reanalyze`,或批量跑 `node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000` |
@@ -309,11 +317,12 @@ npm run dev             # http://localhost:5173(/api 与 /health 代理到 3000)
 cd web-server
 npm run contracts:check   # 契约版本一致性
 npm run typecheck         # TypeScript 严格检查
-npm run test              # 205 项单元测试 / 13 个文件(VMD 31、模型压缩包 27、
+npm run test              # 211 项单元测试 / 14 个文件(VMD 31、模型压缩包 27、
                           #   模型检查器 25、缩略图 8、骨骼过滤 8、
                           #   预处理 25、init-env 16、admin-port 16、
                           #   access-log 9、VRM 检查器 6、.env 预检 12、
-                          #   Assimp 定位与安装 13、stats 容量与编码 12)
+                          #   Assimp 定位与安装 13、stats 容量与编码 12、
+                          #   缩略图贴图采样 6)
 npm run build             # 生产构建
 npm run start:prod &      # 启动
 npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)
@@ -434,10 +443,10 @@ node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000
 | 能力 | 实现 |
 | --- | --- |
 | 分析 | `model-inspector.ts` 解析 GLB/VRM:面数 / 顶点 / 网格 / 材质 / 贴图 / 节点 / 形变目标 / 动画 / 蒙皮骨骼数 / 骨骼树 / humanoid 覆盖 / 可驱动性(缺哪些必需骨骼)/ warnings,写入 `models.stats`(迁移 `AddModelStats1789460000000`,新增 `models.stats TEXT`) |
-| 缩略图 | `model-thumbnail.ts` 用**纯 TS 软件光栅化**生成 PNG(读 GLB/glTF -> 应用节点层级与蒙皮 -> 包围盒自动构图 -> 透视投影 -> z-buffer 逐三角形平面着色 -> 手写 PNG 编码),**零原生依赖**(不需要 canvas / headless-gl / puppeteer)。默认 512x512,写入 `models.thumbnail_asset_id` / `thumbnailUrl`;失败或非 glTF 容器时留空,列表页退化为格式占位图 |
+| 缩略图 | `model-thumbnail.ts` 用**纯 TS 软件光栅化**生成 PNG(读 GLB/glTF -> 应用节点层级与蒙皮 -> 包围盒自动构图 -> 透视投影 -> z-buffer + 平面着色 + **逐像素采样 baseColorTexture**,内置 PNG 解码器 -> 手写 PNG 编码),**零原生依赖**(不需要 canvas / headless-gl / puppeteer);按 `alphaMode` 处理 OPAQUE / MASK / BLEND。默认 512x512,写入 `models.thumbnail_asset_id` / `thumbnailUrl`;失败或非 glTF 容器时留空,列表页退化为格式占位图 |
 | 预览 | 管理端 3D 预览放开到 `vrm/glb/gltf`(`.fbx` 仍提示「仅归档,请先转换为 GLB/VRM」);列表页显示 40px 小缩略图,审核面板显示 116px 缩略图 |
 
-实测:512x512 PNG / 15,043 字节,目视确认为居中的 T-pose 角色图;真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms(中位 79ms)。
+实测:512x512 PNG / 15-42 KB(带贴图后变大),目视确认为居中的 T-pose 角色图且能看到肤色/眼睛/服装贴图;真实 10MB VRM(83 关节、5307 顶点)单张耗时 60-121ms(中位 79ms),27MB PMX 转换件约 200-400ms。
 
 ### 审核流程(模型)
 

README.txt

@@ -1,5 +1,5 @@
 ================================================================
-OpenDance Studio -- Web 管理服务端 v0.2.3  使用说明
+OpenDance Studio -- Web 管理服务端 v0.2.4  使用说明
 ================================================================
 
 本服务端是 OpenDance Studio 三端中的第一端, 负责管理歌曲、VRM 模型与
@@ -8,6 +8,17 @@ OpenDance Studio -- Web 管理服务端 v0.2.3  使用说明
 重要: 本服务端 不部署、不管理 MySQL。数据库为部署方提供的现有实例,
 连接信息通过 .env 注入。
 
+v0.2.4 修订
+  1. 修复缩略图"白模": 缩略图渲染器原先刻意不解码贴图, 只用 baseColorFactor
+     上色; 而 MMD(PMX 转换)模型的 baseColorFactor 基本都是白色, 于是列表页与
+     审核面板里的缩略图全是白色模型。现在内置极简 PNG 解码器(zlib + 反滤波,
+     8 位非隔行, colorType 0/2/3/4/6), 按 baseColorFactor x 贴图逐像素采样,
+     并按 alphaMode(OPAQUE / MASK / BLEND)处理透明度; 解码失败回退纯色。
+  2. 缩略图取景收紧(FRAMING 1.6 -> 1.3), 40px 列表缩略图里主体更清楚。
+  3. 新增 6 项贴图/透明度测试(test/model-thumbnail-texture.spec.ts)。
+  4. 说明: GLB 数据本身没问题 - 贴图逐字节内嵌(18/18)、39 个材质的贴图对应
+     关系与 PMX 完全一致; 白模只出在缩略图渲染器。
+
 v0.2.3 修订
   1. 修复上传 PMX 返回 500(models.stats 容量): 分析结果里的骨骼树按骨骼逐条
      展开, 实测一个 643 骨骼的 PMX(【奥黛塔】_by_原神.zip)就有 70,980 字节,
@@ -58,11 +69,11 @@ v0.2.1 修订
    2. 准备一个现有的 MySQL / MariaDB 实例, 并建好库与账号(见下方"前置要求")
         本项目不会创建数据库本身
    3. 取得发布包并校验(地址用你们自己的制品库替换)
-        curl -LO https://<制品库地址>/opendance-web-v0.2.3.tar.gz
+        curl -LO https://<制品库地址>/opendance-web-v0.2.4.tar.gz
         curl -LO https://<制品库地址>/SHA256SUMS
         sha256sum -c SHA256SUMS      # 期望输出 "OK"
    4. 解压并生成配置(交互式引导, 逐项问答, 口令不回显)
-        tar -xzf opendance-web-v0.2.3.tar.gz && cd opendance-web-v0.2.3
+        tar -xzf opendance-web-v0.2.4.tar.gz && cd opendance-web-v0.2.4
         bash deploy/init-env.sh
    5. 安装(建用户与目录 -> 装依赖 -> 迁移 -> 注册系统服务 -> 等健康检查)
         bash deploy/install.sh
@@ -120,8 +131,8 @@ v0.2.1 修订
   (本项目不会创建数据库本身, 也不需要 GRANT OPTION / FILE / SUPER 等管理权限)
 
 部署步骤
-  tar -xzf opendance-web-v0.2.3.tar.gz
-  cd opendance-web-v0.2.3
+  tar -xzf opendance-web-v0.2.4.tar.gz
+  cd opendance-web-v0.2.4
   bash deploy/init-env.sh         # 首次启动引导: 逐项问答生成 deploy/.env(见下)
   bash deploy/install.sh          # 已以 root 登录, 不需要 sudo
 
@@ -252,7 +263,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
      (RHEL 系 dnf install -y assimp; install.sh 现在会尝试自动安装)。
      装好后不需要重启服务; 若不在服务 PATH 中, 在 deploy/.env 里把 ASSIMP_BIN
      设为绝对路径。只上传 .glb / .vrm 则不需要它。
-- 导入模型返回 500 Internal server error
+- 列表/审核里的缩略图是"白模"(纯白模型)
+      v0.2.4 前的缩略图渲染器不采样贴图, 而 MMD 模型的 baseColorFactor 是白色。
+      升级到 v0.2.4 后重新生成缩略图: cd /opt/opendance/web-server &&
+      node scripts/reanalyze-models.mjs --url http://127.0.0.1:3000 --force
+ - 导入模型返回 500 Internal server error
       老库上多为 models.stats 超长(骨骼树按骨骼展开, 643 骨骼即 70,980 字节
       > TEXT 上限): 执行 ALTER TABLE models MODIFY stats MEDIUMTEXT NULL;
       或部署 v0.2.3(install.sh 会自动跑迁移)。v0.2.3 起服务端另有兜底,
@@ -287,11 +302,11 @@ deploy/.env 初始化引导(deploy/init-env.sh)
   cd web-server
   npm run contracts:check   # 契约版本一致性
   npm run typecheck         # TypeScript 严格检查
-  npm run test              # 205 项单元测试 / 13 个文件(VMD 31、模型压缩包 24、
+  npm run test              # 211 项单元测试 / 14 个文件(VMD 31、模型压缩包 24、
                             #   模型检查器 25、缩略图 8、骨骼过滤 8、
                             #   预处理 25、init-env 16、admin-port 16、
                             #   access-log 9、VRM 检查器 6、.env 预检 12、
-                            #   Assimp 定位与安装 13、stats 容量与编码 12)
+                            #   Assimp 定位与安装 13、stats 容量与编码 12、缩略图贴图 6)
   npm run build             # 生产构建
   npm run start:prod &      # 启动
   npm run test:smoke        # 57 项端到端冒烟(需要数据库可连通)

project.yaml

@@ -1,5 +1,5 @@
 project: opendance-web-server
-version: 0.2.3
+version: 0.2.4
 repository: opendance-web
 default_branch: main
 contracts_version: 0.4.0
@@ -60,7 +60,7 @@ tasks:
     status: done
 
 deliverable:
-  artifact: opendance-web-v0.2.3.tar.gz
+  artifact: opendance-web-v0.2.4.tar.gz
   packaging: Linux 业务服务（系统服务托管，双端口：软件 API + 管理端，不含 MySQL、不含反向代理、不使用 Docker）
   includes:
     - web-server/          # NestJS 源码 + 构建产物（含 BVH / VMD 内置解析、ZIP 读取与模型压缩包转换）

scripts/package-release.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # ============================================================
-# 打包发布产物：opendance-web-v0.2.3.tar.gz
+# 打包发布产物：opendance-web-v0.2.4.tar.gz
 #
 # 产物结构（Linux 业务服务部署，不使用 Docker、不部署反向代理）：
 #   web-server/      NestJS 源码 + 构建产物
@@ -21,7 +21,7 @@ set -euo pipefail
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$REPO_ROOT"
 
-VERSION="${1:-0.2.3}"
+VERSION="${1:-0.2.4}"
 NAME="opendance-web-v${VERSION}"
 OUT_DIR="$REPO_ROOT/dist-release"
 STAGE="$OUT_DIR/$NAME"

tasks/005-model-upload.md

@@ -160,7 +160,7 @@ node scripts/import-default-model.mjs --write-source-only --model-id 22 --dry-ru
 
 ```bash
 cd web-server
-npx vitest run        # 13 个文件 / 205 项通过
+npx vitest run        # 14 个文件 / 211 项通过
 npm run test:smoke    # 冒烟 [4] 段落
 ```
 

tasks/007-upload-review.md

@@ -86,7 +86,7 @@ draft ──submit──▶ pending ──approve──▶ published
 
 ```bash
 cd web-server
-npx vitest run        # 13 个文件 / 205 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项）
+npx vitest run        # 14 个文件 / 211 项通过（含 admin-bone-filter 8 项、.env 预检 12 项、Assimp 13 项、缩略图贴图 6 项）
 npm run test:smoke
 ```
 

web-server/admin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opendance-admin",
   "private": true,
-  "version": "0.2.3",
+  "version": "0.2.4",
   "type": "module",
   "description": "OpenDance Studio 管理端（React + TypeScript + Vite）",
   "scripts": {

web-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opendance-web-server",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "OpenDance Studio Web 管理服务端（NestJS + TypeORM + 现有 MySQL 实例）",
   "license": "MIT",
   "private": true,

web-server/src/models/model-thumbnail.ts

@@ -1,4 +1,5 @@
 import { readFile } from 'node:fs/promises';
+import { inflateSync } from 'node:zlib';
 import { dirname, resolve as resolvePath } from 'node:path';
 import { deflateSync } from 'node:zlib';
 
@@ -22,9 +23,12 @@ import { deflateSync } from 'node:zlib';
  *      **退化为不蒙皮**，按节点世界矩阵画绑定姿态（bind pose）——多数 VRM 的绑定姿态
  *      就是可看的 T/A 姿态，比错误的蒙皮矩阵导致的"爆炸形状"安全得多。
  *    - 按 glTF 规范，蒙皮网格节点自身的变换被忽略（顶点直接由关节矩阵驱动）。
- * 2. **不采样贴图**：`pbrMetallicRoughness.baseColorFactor` 作为纯色基色，
- *    即使存在 `baseColorTexture` 也不解码（避免再引入 PNG/JPEG 解码器），
- *    因此带贴图的模型缩略图会是纯色块，但轮廓与光影正确。
+ * 2. **采样 baseColorTexture**：内置极简 PNG 解码器（zlib + 反滤波，8 位、非隔行、
+ *    colorType 0/2/3/4/6），按 `baseColorFactor x 贴图` 逐像素取色，并按
+ *    `alphaMode`（OPAQUE / MASK / BLEND）处理透明度。
+ *    这一版之前**不采样贴图**：MMD 模型（PMX 转换而来）的 `baseColorFactor` 几乎
+ *    都是白色，于是缩略图全是"白模"——用户报的正是这个。
+ *    解码失败/非 PNG/隔行扫描时回退为 `baseColorFactor` 纯色，绝不抛错。
  * 3. **稀疏 accessor（sparse）不支持**：遇到就直接跳过该 primitive。
  * 4. **只画三角形（mode=4）**，其余图元（点/线/条带/扇形）跳过。
  * 5. 大模型（>17M 索引）不会出现，索引统一按 uint32 读取。
@@ -70,7 +74,8 @@ const DEFAULT_BACKGROUND: [number, number, number] = [24, 26, 32];
 /** 垂直视场角（度） */
 const FOV_Y_DEG = 35;
 /** 相机距离系数：让模型占画面约 1/1.6，保证不裁剪 */
-const FRAMING = 1.6;
+// 1.6 -> 1.3：列表页只有 40px，主体太小就只剩一团像素
+const FRAMING = 1.3;
 /** 主光方向（世界空间，未归一化，用前会归一化） */
 const LIGHT_DIR: [number, number, number] = normalize3(0.4, 0.8, 0.6);
 /** 环境光强度 */
@@ -244,8 +249,27 @@ interface GltfSkin {
 interface GltfMaterial {
   pbrMetallicRoughness?: {
     baseColorFactor?: number[];
-    baseColorTexture?: unknown;
+    baseColorTexture?: { index?: number; texCoord?: number };
   };
+  alphaMode?: string;
+  alphaCutoff?: number;
+  doubleSided?: boolean;
+}
+
+interface GltfTexture {
+  source?: number;
+  sampler?: number;
+}
+
+interface GltfImage {
+  bufferView?: number;
+  mimeType?: string;
+  uri?: string;
+}
+
+interface GltfSampler {
+  wrapS?: number;
+  wrapT?: number;
 }
 
 interface GltfScene {
@@ -262,6 +286,9 @@ interface GltfDocument {
   bufferViews?: GltfBufferView[];
   buffers?: GltfBufferRef[];
   materials?: GltfMaterial[];
+  textures?: GltfTexture[];
+  images?: GltfImage[];
+  samplers?: GltfSampler[];
   skins?: GltfSkin[];
 }
 
@@ -278,9 +305,26 @@ interface AccessorData {
 }
 
 /** 收集好的三角形：positions 每 9 个数一个三角形，colors 每 3 个数一个三角形 */
+interface DecodedImage {
+  width: number;
+  height: number;
+  /** RGBA，行优先，长度 = width*height*4 */
+  rgba: Uint8Array;
+}
+
 interface SceneGeometry {
   positions: Float32Array;
   colors: Float32Array;
+  /** 每顶点 UV（2 个/顶点）；没有 TEXCOORD_0 时为 null */
+  uvs: Float32Array | null;
+  /** 每顶点贴图槽位（索引进 textures）；-1 表示该顶点无贴图 */
+  texSlots: Int32Array | null;
+  /** 每顶点 alpha 模式：0=OPAQUE 1=MASK 2=BLEND */
+  alphaModes: Uint8Array | null;
+  /** 每顶点 MASK 阈值 */
+  cutoffs: Float32Array | null;
+  /** 解码后的贴图（RGBA） */
+  textures: DecodedImage[];
   triangleCount: number;
 }
 
@@ -667,6 +711,36 @@ function materialBaseColor(doc: GltfDocument, materialIndex: number | undefined)
   return [0.8, 0.8, 0.8];
 }
 
+/** 取 bufferView 的原始字节（贴图解压用）；越界返回 null */
+function readBufferViewBytes(
+  doc: GltfDocument,
+  buffers: Array<Buffer | null>,
+  bufferViewIndex: number,
+): Buffer | null {
+  const view = doc.bufferViews?.[bufferViewIndex];
+  if (!view || typeof view.buffer !== 'number') return null;
+  const buffer = buffers[view.buffer];
+  if (!buffer) return null;
+  const offset = view.byteOffset ?? 0;
+  const length = view.byteLength ?? 0;
+  if (offset < 0 || length <= 0 || offset + length > buffer.length) return null;
+  return buffer.subarray(offset, offset + length);
+}
+
+/** 解码 GLB 内嵌的 PNG 贴图；外部 uri / 非 PNG / 解码失败都返回 null（回退纯色） */
+function decodeEmbeddedImage(
+  doc: GltfDocument,
+  buffers: Array<Buffer | null>,
+  imageIndex: number,
+): DecodedImage | null {
+  const image = doc.images?.[imageIndex];
+  if (!image || typeof image.bufferView !== 'number') return null;
+  if (typeof image.mimeType === 'string' && !image.mimeType.toLowerCase().includes('png')) return null;
+  const bytes = readBufferViewBytes(doc, buffers, image.bufferView);
+  if (!bytes) return null;
+  return decodePng(bytes);
+}
+
 /** 遍历场景图收集世界空间三角形 */
 function collectTriangles(container: GltfContainer): SceneGeometry | null {
   const { doc, buffers } = container;
@@ -676,8 +750,49 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null {
 
   const positions: number[] = [];
   const colors: number[] = [];
+  const uvs: number[] = [];
+  const texSlots: number[] = [];
+  const alphaModes: number[] = [];
+  const cutoffs: number[] = [];
+  const textures: DecodedImage[] = [];
+  const materialTextureCache = new Map<number, { slot: number; alphaMode: number; cutoff: number }>();
+  const imageCache = new Map<number, DecodedImage | null>();
   const skinScratch = new Float64Array(16);
 
+  /**
+   * 解析材质的 baseColorTexture：解码一次并登记槽位。
+   * MMD 模型的 baseColorFactor 基本都是白色，颜色全在贴图里 —— 不解码就是"白模"。
+   */
+  const resolveMaterialTexture = (
+    materialIndex: number | undefined,
+  ): { slot: number; alphaMode: number; cutoff: number } => {
+    const key = typeof materialIndex === 'number' ? materialIndex : -1;
+    const cached = materialTextureCache.get(key);
+    if (cached) return cached;
+    const material = typeof materialIndex === 'number' ? doc.materials?.[materialIndex] : undefined;
+    const alphaMode = material?.alphaMode === 'MASK' ? 1 : material?.alphaMode === 'BLEND' ? 2 : 0;
+    const rawCutoff = typeof material?.alphaCutoff === 'number' ? material.alphaCutoff : 0.5;
+    const cutoff = clamp(rawCutoff, 0, 1);
+    let slot = -1;
+    const textureIndex = material?.pbrMetallicRoughness?.baseColorTexture?.index;
+    if (typeof textureIndex === 'number') {
+      const imageIndex = doc.textures?.[textureIndex]?.source;
+      if (typeof imageIndex === 'number') {
+        if (!imageCache.has(imageIndex)) {
+          imageCache.set(imageIndex, decodeEmbeddedImage(doc, buffers, imageIndex));
+        }
+        const image = imageCache.get(imageIndex) ?? null;
+        if (image) {
+          slot = textures.length;
+          textures.push(image);
+        }
+      }
+    }
+    const resolved = { slot, alphaMode, cutoff };
+    materialTextureCache.set(key, resolved);
+    return resolved;
+  };
+
   const appendMesh = (nodeIndex: number): void => {
     const node = nodes[nodeIndex];
     if (!node || typeof node.mesh !== 'number') return;
@@ -710,6 +825,10 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null {
 
       const vertexCount = positionData.count;
       const [cr, cg, cb] = materialBaseColor(doc, primitive.material);
+      const materialTexture = resolveMaterialTexture(primitive.material);
+      const uvData =
+        materialTexture.slot >= 0 ? readAccessorFloats(doc, buffers, attributes.TEXCOORD_0, 2) : null;
+      const usableUv = uvData && uvData.count === vertexCount ? uvData : null;
 
       // 顶点只变换一次：蒙皮或节点世界矩阵
       const px = new Float64Array(vertexCount);
@@ -758,6 +877,18 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null {
         }
         positions.push(x0, y0, z0, x1, y1, z1, x2, y2, z2);
         colors.push(cr, cg, cb);
+        if (usableUv) {
+          uvs.push(
+            usableUv.values[i0 * 2], usableUv.values[i0 * 2 + 1],
+            usableUv.values[i1 * 2], usableUv.values[i1 * 2 + 1],
+            usableUv.values[i2 * 2], usableUv.values[i2 * 2 + 1],
+          );
+        } else {
+          uvs.push(0, 0, 0, 0, 0, 0);
+        }
+        texSlots.push(materialTexture.slot, materialTexture.slot, materialTexture.slot);
+        alphaModes.push(materialTexture.alphaMode, materialTexture.alphaMode, materialTexture.alphaMode);
+        cutoffs.push(materialTexture.cutoff, materialTexture.cutoff, materialTexture.cutoff);
       }
     }
   };
@@ -784,6 +915,11 @@ function collectTriangles(container: GltfContainer): SceneGeometry | null {
   return {
     positions: Float32Array.from(positions),
     colors: Float32Array.from(colors),
+    uvs: Float32Array.from(uvs),
+    texSlots: Int32Array.from(texSlots),
+    alphaModes: Uint8Array.from(alphaModes),
+    cutoffs: Float32Array.from(cutoffs),
+    textures,
     triangleCount,
   };
 }
@@ -831,13 +967,25 @@ function edge(ax: number, ay: number, bx: number, by: number, px: number, py: nu
  * 屏幕空间有符号面积为负的是正面（NDC 里 CCW 正面经 y 翻转后变成负），
  * 因此 cullBackFace 时丢弃 area >= 0 的三角形。
  */
+/** 采样贴图（REPEAT 环绕；glTF/PNG 的 UV 原点在左上，v 不翻转） */
+function sampleTexture(image: DecodedImage, u: number, v: number, out: Float32Array): void {
+  const wrap = (value: number): number => value - Math.floor(value);
+  const x = Math.min(image.width - 1, Math.floor(wrap(u) * image.width));
+  const y = Math.min(image.height - 1, Math.floor(wrap(v) * image.height));
+  const o = (y * image.width + x) * 4;
+  out[0] = image.rgba[o] / 255;
+  out[1] = image.rgba[o + 1] / 255;
+  out[2] = image.rgba[o + 2] / 255;
+  out[3] = image.rgba[o + 3] / 255;
+}
+
 function rasterizeTriangles(
   geometry: SceneGeometry,
   viewProj: Mat4,
   options: RasterOptions,
 ): RasterOutput {
   const { size, background, cullBackFace } = options;
-  const { positions, colors, triangleCount } = geometry;
+  const { positions, colors, uvs, texSlots, alphaModes, cutoffs, textures, triangleCount } = geometry;
 
   const pixels = Buffer.alloc(size * size * 3);
   for (let i = 0; i < size * size; i += 1) {
@@ -909,9 +1057,23 @@ function rasterizeTriangles(
     const baseR = colors[t * 3];
     const baseG = colors[t * 3 + 1];
     const baseB = colors[t * 3 + 2];
-    const r = clamp(Math.round(baseR * intensity * 255), 0, 255);
-    const g = clamp(Math.round(baseG * intensity * 255), 0, 255);
-    const b = clamp(Math.round(baseB * intensity * 255), 0, 255);
+
+    // 贴图与透明度（每三角形常量；顶点数组按 3 顶点/三角形展开）
+    const slot = texSlots ? texSlots[t * 3] : -1;
+    const image = slot >= 0 ? textures[slot] ?? null : null;
+    const alphaMode = alphaModes ? alphaModes[t * 3] : 0;
+    const cutoff = cutoffs ? cutoffs[t * 3] : 0.5;
+    const u0 = uvs ? uvs[t * 6] : 0;
+    const v0 = uvs ? uvs[t * 6 + 1] : 0;
+    const u1 = uvs ? uvs[t * 6 + 2] : 0;
+    const v1 = uvs ? uvs[t * 6 + 3] : 0;
+    const u2 = uvs ? uvs[t * 6 + 4] : 0;
+    const v2 = uvs ? uvs[t * 6 + 5] : 0;
+    const texel = new Float32Array(4);
+    // 透视校正用：1/w 在三个顶点上的值
+    const iw0 = 1 / p0[3];
+    const iw1 = 1 / p1[3];
+    const iw2 = 1 / p2[3];
 
     const invArea = 1 / area;
     for (let y = minY; y <= maxY; y += 1) {
@@ -926,6 +1088,27 @@ function rasterizeTriangles(
         const d = w0 * p0[2] + w1 * p1[2] + w2 * p2[2];
         const index = rowBase + x;
         if (d < depth[index]) {
+          let r = clamp(Math.round(baseR * intensity * 255), 0, 255);
+          let g = clamp(Math.round(baseG * intensity * 255), 0, 255);
+          let b = clamp(Math.round(baseB * intensity * 255), 0, 255);
+          if (image) {
+            const iw = w0 * iw0 + w1 * iw1 + w2 * iw2;
+            const u = (w0 * iw0 * u0 + w1 * iw1 * u1 + w2 * iw2 * u2) / (iw || 1);
+            const v = (w0 * iw0 * v0 + w1 * iw1 * v1 + w2 * iw2 * v2) / (iw || 1);
+            sampleTexture(image, u, v, texel);
+            if (alphaMode === 1 && texel[3] < cutoff) continue; // MASK：整像素丢弃
+            const a = alphaMode === 0 ? 1 : texel[3];
+            r = clamp(Math.round(baseR * texel[0] * intensity * 255), 0, 255);
+            g = clamp(Math.round(baseG * texel[1] * intensity * 255), 0, 255);
+            b = clamp(Math.round(baseB * texel[2] * intensity * 255), 0, 255);
+            if (alphaMode === 2 && a < 1) {
+              // BLEND：与背景/已画像素做 source-over（缩略图不做排序，够看即可）
+              const q = index * 3;
+              r = clamp(Math.round(r * a + pixels[q] * (1 - a)), 0, 255);
+              g = clamp(Math.round(g * a + pixels[q + 1] * (1 - a)), 0, 255);
+              b = clamp(Math.round(b * a + pixels[q + 2] * (1 - a)), 0, 255);
+            }
+          }
           depth[index] = d;
           const p = index * 3;
           pixels[p] = r;
@@ -1045,6 +1228,133 @@ function buildViewProjection(geometry: SceneGeometry, size: number, yawDeg: numb
   return mat4Multiply(proj, view);
 }
 
+// ---------------------------------------------------------------------------
+// PNG 解码（缩略图要贴图才不是"白模"；只做 8 位非隔行，够用且零原生依赖）
+// ---------------------------------------------------------------------------
+
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/**
+ * 极简 PNG 解码器：zlib 解压 + 逐行反滤波，输出 RGBA。
+ * 不支持 16 位 / 隔行扫描 / 未知 colorType —— 返回 null 由调用方回退纯色。
+ */
+function decodePng(buffer: Buffer): DecodedImage | null {
+  if (buffer.length < 8 + 25 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  let bitDepth = 0;
+  let colorType = 0;
+  let interlace = 0;
+  let palette: Uint8Array | null = null;
+  let transparency: Uint8Array | null = null;
+  const idat: Buffer[] = [];
+
+  while (offset + 8 <= buffer.length) {
+    const length = buffer.readUInt32BE(offset);
+    const type = buffer.toString('ascii', offset + 4, offset + 8);
+    const dataStart = offset + 8;
+    if (dataStart + length + 4 > buffer.length) return null;
+    const data = buffer.subarray(dataStart, dataStart + length);
+    if (type === 'IHDR') {
+      if (length < 13) return null;
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      bitDepth = data[8];
+      colorType = data[9];
+      interlace = data[12];
+    } else if (type === 'PLTE') {
+      palette = new Uint8Array(data);
+    } else if (type === 'tRNS') {
+      transparency = new Uint8Array(data);
+    } else if (type === 'IDAT') {
+      idat.push(Buffer.from(data));
+    } else if (type === 'IEND') {
+      break;
+    }
+    offset = dataStart + length + 4;
+  }
+
+  if (bitDepth !== 8 || interlace !== 0) return null;
+  if (!(width > 0) || !(height > 0) || width * height > 64 * 1024 * 1024) return null;
+  if (idat.length === 0) return null;
+
+  const channels =
+    colorType === 0 ? 1 : colorType === 2 ? 3 : colorType === 3 ? 1 : colorType === 4 ? 2 : colorType === 6 ? 4 : 0;
+  if (channels === 0) return null;
+  if (colorType === 3 && !palette) return null;
+
+  let raw: Buffer;
+  try {
+    raw = inflateSync(Buffer.concat(idat));
+  } catch {
+    return null;
+  }
+  const stride = width * channels;
+  if (raw.length < (stride + 1) * height) return null;
+
+  const out = new Uint8Array(width * height * 4);
+  const line = new Uint8Array(stride);
+  const prev = new Uint8Array(stride);
+  let rawPos = 0;
+  for (let y = 0; y < height; y += 1) {
+    const filter = raw[rawPos];
+    rawPos += 1;
+    for (let i = 0; i < stride; i += 1) {
+      const value = raw[rawPos + i];
+      const left = i >= channels ? line[i - channels] : 0;
+      const up = prev[i];
+      const upLeft = i >= channels ? prev[i - channels] : 0;
+      let restored: number;
+      switch (filter) {
+        case 0: restored = value; break;
+        case 1: restored = value + left; break;
+        case 2: restored = value + up; break;
+        case 3: restored = value + ((left + up) >> 1); break;
+        case 4: {
+          const p = left + up - upLeft;
+          const pa = Math.abs(p - left);
+          const pb = Math.abs(p - up);
+          const pc = Math.abs(p - upLeft);
+          restored = value + (pa <= pb && pa <= pc ? left : pb <= pc ? up : upLeft);
+          break;
+        }
+        default: return null;
+      }
+      line[i] = restored & 0xff;
+    }
+    rawPos += stride;
+    for (let x = 0; x < width; x += 1) {
+      const o = (y * width + x) * 4;
+      if (colorType === 6) {
+        out[o] = line[x * 4];
+        out[o + 1] = line[x * 4 + 1];
+        out[o + 2] = line[x * 4 + 2];
+        out[o + 3] = line[x * 4 + 3];
+      } else if (colorType === 2) {
+        out[o] = line[x * 3];
+        out[o + 1] = line[x * 3 + 1];
+        out[o + 2] = line[x * 3 + 2];
+        out[o + 3] = 255;
+      } else if (colorType === 0) {
+        const g = line[x];
+        out[o] = g; out[o + 1] = g; out[o + 2] = g; out[o + 3] = 255;
+      } else if (colorType === 4) {
+        const g = line[x * 2];
+        out[o] = g; out[o + 1] = g; out[o + 2] = g; out[o + 3] = line[x * 2 + 1];
+      } else {
+        const index = line[x];
+        out[o] = palette![index * 3] ?? 0;
+        out[o + 1] = palette![index * 3 + 1] ?? 0;
+        out[o + 2] = palette![index * 3 + 2] ?? 0;
+        out[o + 3] = transparency && index < transparency.length ? transparency[index] : 255;
+      }
+    }
+    prev.set(line);
+  }
+  return { width, height, rgba: out };
+}
+
 // ---------------------------------------------------------------------------
 // PNG 编码（8 位 RGB、无隔行、filter=0；不引第三方库）
 // ---------------------------------------------------------------------------
@@ -1133,6 +1443,8 @@ export async function renderModelThumbnail(
   ) {
     throw new Error('缩略图背景色非法：需要 [r, g, b] 三个有限数字');
   }
+  // 默认看**正面**：eye = 中心 + (sin yaw, .., cos yaw)*d，yaw=0 时相机在 +Z；
+  // MMD（PMX）与 VRM 1.0 都是 +Z 朝前，因此 -30 是"正面偏 30 度"的常规 3/4 视角
   const yawDeg = options?.yawDeg ?? -30;
   const rawPitchDeg = options?.pitchDeg ?? 12;
   if (!Number.isFinite(yawDeg) || !Number.isFinite(rawPitchDeg)) {

web-server/test/model-thumbnail-texture.spec.ts

@@ -0,0 +1,232 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { inflateSync } from 'node:zlib';
+import { describe, expect, it } from 'vitest';
+import { renderModelThumbnail } from '../src/models/model-thumbnail';
+
+/**
+ * 缩略图**贴图采样**测试。
+ *
+ * 背景（真实故障）：缩略图渲染器原先刻意不解码 baseColorTexture，只用
+ * `baseColorFactor` 上色；而 MMD（PMX 转换）模型的 baseColorFactor 基本全是白色，
+ * 于是缩略图全是"白模"——列表页与审核面板看到的都是白色模型，用户报的正是这个。
+ * 现在渲染器内置 PNG 解码并逐像素采样贴图，这里锁住行为。
+ */
+
+const dir = mkdtempSync(join(tmpdir(), 'opendance-thumb-tex-'));
+
+function write(name: string, content: Buffer): string {
+  const path = join(dir, name);
+  writeFileSync(path, content);
+  return path;
+}
+
+/** 12 字节头 + JSON chunk + BIN chunk */
+function buildGlb(json: unknown, bin: Buffer): Buffer {
+  const jsonRaw = Buffer.from(JSON.stringify(json), 'utf8');
+  const jsonChunk = Buffer.concat([jsonRaw, Buffer.alloc((4 - (jsonRaw.length % 4)) % 4, 0x20)]);
+  const binChunk = Buffer.concat([bin, Buffer.alloc((4 - (bin.length % 4)) % 4)]);
+  const chunks: Buffer[] = [];
+  const header = Buffer.alloc(12);
+  header.write('glTF', 0, 'ascii');
+  header.writeUInt32LE(2, 4);
+  chunks.push(header);
+  const jsonHeader = Buffer.alloc(8);
+  jsonHeader.writeUInt32LE(jsonChunk.length, 0);
+  jsonHeader.writeUInt32LE(0x4e4f534a, 4);
+  chunks.push(jsonHeader, jsonChunk);
+  const binHeader = Buffer.alloc(8);
+  binHeader.writeUInt32LE(binChunk.length, 0);
+  binHeader.writeUInt32LE(0x004e4942, 4);
+  chunks.push(binHeader, binChunk);
+  const out = Buffer.concat(chunks);
+  out.writeUInt32LE(out.length, 8);
+  return out;
+}
+
+function float32Buffer(values: number[]): Buffer {
+  const buffer = Buffer.alloc(values.length * 4);
+  values.forEach((value, index) => buffer.writeFloatLE(value, index * 4));
+  return buffer;
+}
+
+function uint16Buffer(values: number[]): Buffer {
+  const buffer = Buffer.alloc(values.length * 2);
+  values.forEach((value, index) => buffer.writeUInt16LE(value, index * 2));
+  return buffer;
+}
+
+/* ------------------------------------------------------------ 贴图夹具 */
+
+/** 2x2 纯红（colorType 6，带 alpha=255） */
+const RED_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8DwH4QZYAwAR8oH+WdZbrcAAAAASUVORK5CYII=',
+  'base64',
+);
+/** 2x2 纯绿（colorType 2，无 alpha） */
+const GREEN_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAD0lEQVR4nGNg+M8AQhAKABvyA/1tVLjHAAAAAElFTkSuQmCC',
+  'base64',
+);
+/** 2x2 全透明（RGBA 的 alpha=0） */
+const TRANSPARENT_PNG = Buffer.from(
+  'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEUlEQVR4nGP4z8DAAMIMMAYAKegD/QE6Y34AAAAASUVORK5CYII=',
+  'base64',
+);
+
+interface QuadOptions {
+  texture?: Buffer;
+  mimeType?: string;
+  baseColorFactor?: number[];
+  alphaMode?: string;
+}
+
+/** 一个正对相机（+Z）的方形面片，UV 铺满贴图；baseColorFactor 默认纯白（MMD 的常见情况） */
+function texturedQuadGlb(options: QuadOptions = {}): Buffer {
+  const positions = [-1, -1, 0, 1, -1, 0, 1, 1, 0, -1, 1, 0];
+  const uvs = [0, 1, 1, 1, 1, 0, 0, 0];
+  const indices = [0, 1, 2, 0, 2, 3];
+  const posBin = float32Buffer(positions);
+  const uvBin = float32Buffer(uvs);
+  const idxBin = uint16Buffer(indices);
+  const image = options.texture ?? RED_PNG;
+  const bin = Buffer.concat([posBin, uvBin, idxBin, image]);
+  const imageOffset = posBin.length + uvBin.length + idxBin.length;
+
+  const json = {
+    asset: { version: '2.0' },
+    scene: 0,
+    scenes: [{ nodes: [0] }],
+    nodes: [{ mesh: 0 }],
+    meshes: [{ primitives: [{ attributes: { POSITION: 0, TEXCOORD_0: 1 }, indices: 2, material: 0 }] }],
+    materials: [
+      {
+        pbrMetallicRoughness: {
+          baseColorFactor: options.baseColorFactor ?? [1, 1, 1, 1],
+          baseColorTexture: { index: 0 },
+        },
+        ...(options.alphaMode ? { alphaMode: options.alphaMode, alphaCutoff: 0.5 } : {}),
+      },
+    ],
+    textures: [{ source: 0 }],
+    images: [{ bufferView: 3, mimeType: options.mimeType ?? 'image/png' }],
+    accessors: [
+      { bufferView: 0, componentType: 5126, count: 4, type: 'VEC3' },
+      { bufferView: 1, componentType: 5126, count: 4, type: 'VEC2' },
+      { bufferView: 2, componentType: 5123, count: 6, type: 'SCALAR' },
+    ],
+    bufferViews: [
+      { buffer: 0, byteOffset: 0, byteLength: posBin.length },
+      { buffer: 0, byteOffset: posBin.length, byteLength: uvBin.length },
+      { buffer: 0, byteOffset: posBin.length + uvBin.length, byteLength: idxBin.length },
+      { buffer: 0, byteOffset: imageOffset, byteLength: image.length },
+    ],
+    buffers: [{ byteLength: bin.length }],
+  };
+  return buildGlb(json, bin);
+}
+
+/** 解 PNG（我们自己写的编码器：8 位 RGB、filter=0），返回平均 RGB */
+function averageColor(png: Buffer): { r: number; g: number; b: number; nonBackground: number } {
+  let offset = 8;
+  let width = 0;
+  let height = 0;
+  const idat: Buffer[] = [];
+  while (offset + 8 <= png.length) {
+    const length = png.readUInt32BE(offset);
+    const type = png.toString('ascii', offset + 4, offset + 8);
+    const data = png.subarray(offset + 8, offset + 8 + length);
+    if (type === 'IHDR') {
+      width = data.readUInt32BE(0);
+      height = data.readUInt32BE(4);
+      expect(data[8]).toBe(8);
+      expect(data[9]).toBe(2);
+      expect(data[12]).toBe(0);
+    } else if (type === 'IDAT') {
+      idat.push(Buffer.from(data));
+    } else if (type === 'IEND') {
+      break;
+    }
+    offset += 12 + length;
+  }
+  const raw = inflateSync(Buffer.concat(idat));
+  let r = 0;
+  let g = 0;
+  let b = 0;
+  let count = 0;
+  let nonBackground = 0;
+  for (let y = 0; y < height; y += 1) {
+    const rowStart = y * (1 + width * 3);
+    expect(raw[rowStart]).toBe(0); // filter=0
+    for (let x = 0; x < width; x += 1) {
+      const i = rowStart + 1 + x * 3;
+      r += raw[i];
+      g += raw[i + 1];
+      b += raw[i + 2];
+      count += 1;
+      // 默认背景是 [24,26,32]（深色）；明显偏离即视为主体像素
+      if (Math.abs(raw[i] - 24) > 12 || Math.abs(raw[i + 1] - 26) > 12 || Math.abs(raw[i + 2] - 32) > 12) {
+        nonBackground += 1;
+      }
+    }
+  }
+  return { r: r / count, g: g / count, b: b / count, nonBackground };
+}
+
+async function render(glb: Buffer, name: string, extra: Record<string, unknown> = {}) {
+  const result = await renderModelThumbnail(write(name, glb), { size: 128, ...extra });
+  expect(result).not.toBeNull();
+  return averageColor((result as { png: Buffer }).png);
+}
+
+/* ------------------------------------------------------------------ 测试 */
+
+describe('缩略图贴图采样', () => {
+  it('baseColorFactor 全白时也按贴图上色（回归：不再输出"白模"）', async () => {
+    const color = await render(texturedQuadGlb(), 'red.glb');
+    expect(color.nonBackground).toBeGreaterThan(0);
+    // 贴图是纯红：主体像素整体应明显偏红
+    expect(color.r).toBeGreaterThan(color.g + 20);
+    expect(color.r).toBeGreaterThan(color.b + 20);
+  });
+
+  it('colorType 2（无 alpha 通道）的 PNG 也能解码', async () => {
+    const color = await render(texturedQuadGlb({ texture: GREEN_PNG }), 'green.glb');
+    expect(color.g).toBeGreaterThan(color.r + 20);
+    expect(color.g).toBeGreaterThan(color.b + 20);
+  });
+
+  it('OPAQUE：忽略贴图 alpha（MMD 语义，alpha=0 也照样画出来）', async () => {
+    const color = await render(
+      texturedQuadGlb({ texture: TRANSPARENT_PNG, baseColorFactor: [0.9, 0.1, 0.1, 1] }),
+      'opaque.glb',
+    );
+    expect(color.nonBackground).toBeGreaterThan(0);
+    expect(color.r).toBeGreaterThan(color.g + 20);
+  });
+
+  it('MASK：alpha 低于阈值的主体像素被丢弃（只剩背景）', async () => {
+    const color = await render(
+      texturedQuadGlb({ texture: TRANSPARENT_PNG, baseColorFactor: [0.9, 0.1, 0.1, 1], alphaMode: 'MASK' }),
+      'mask.glb',
+    );
+    expect(color.nonBackground).toBe(0);
+  });
+
+  it('贴图解码失败时回退 baseColorFactor 纯色，且不抛错', async () => {
+    const broken = Buffer.from('这不是 PNG 数据', 'utf8');
+    const color = await render(
+      texturedQuadGlb({ texture: broken, baseColorFactor: [0.1, 0.1, 0.9, 1] }),
+      'broken.glb',
+    );
+    expect(color.nonBackground).toBeGreaterThan(0);
+    expect(color.b).toBeGreaterThan(color.r + 20);
+  });
+
+  it('默认视角是正面（相机在 +Z）：+Z 面颜色明显主导', async () => {
+    // 面片正对 +Z，默认视角下必须看得见（若默认看背面，主体像素会接近 0）
+    const color = await render(texturedQuadGlb(), 'front.glb');
+    expect(color.nonBackground).toBeGreaterThan(128 * 128 * 0.05);
+  });
+});