Blender（开源）      → 简单设备/示意模型
SolidWorks / Revit   → 真实工业设备（导出为 GLTF/GLB 常用）
Three.js 官方示例库  → 学习用免费模型（KhronosGroup glTF-Sample-Models）

# GLTFLoader 在 three/examples 里（不是核心包），已随 three 安装
# import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";

import * as THREE from "three";
import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";

// 1. 创建加载器
const loader = new GLTFLoader();

// 2. 加载（异步）：onLoad 拿到解析后的 gltf 对象
loader.load(
  "/assets/models/pump.glb",      // 资源路径（放 /public/assets/models）
  (gltf) => {
    const model = gltf.scene;      // ← 真正的场景对象（Group 的超级版）
    scene.add(model);
  },
  (xhr) => {
    // 3. 进度回调（Day 111 做加载进度条）
    const pct = (xhr.loaded / xhr.total) * 100;
    console.log(`加载中 ${pct.toFixed(0)}%`);
  },
  (err) => {
    console.error("模型加载失败：", err);   // 4. 失败回调（Day 111 降级）
  }
);

// 推荐：loadAsync（配合 await/async，代码更清晰，Day 111 用）
// const gltf = await loader.loadAsync("/assets/models/pump.glb");

const gltf = await loader.loadAsync("/assets/models/pump.glb");
// gltf 里主要有：
//   gltf.scene        —— 场景根（一个 Group，挂所有模型内容）
//   gltf.animations   —— 模型自带的关键帧动画（Day 110 用）
//   gltf.cameras      —— 建模软件里留的相机（一般不用）

const model = gltf.scene;
// model 本身是个 Object3D（类似 Group），内部可能是多层嵌套：
//   pump.glb
//   └── pump (Group)
//       ├── body (Mesh)      ← 真正画出来的几何
//       ├── impeller (Mesh)  ← 叶轮
//       └── base (Mesh)

// 把设备 id 挂到模型根上（Day 104 拾取契约的模型版）
model.userData.deviceId = "pump-01";
// 交给引擎的可拾取清单（Day 104 pickables）
pickables.push(model);

现象：模型黑色 / 反光怪异 / 颜色不对
原因：① 模型贴图路径在导出时没嵌入（外部引用失效）
      ② 模型材质用了 Three 不认识的属性
修法：① 用 GLB（内嵌资源，不丢贴图）② 加载后遍历替换材质

// 模型材质兜底：遍历模型，把"没材质的 Mesh"补一个默认材质
model.traverse((child) => {
  if (child instanceof THREE.Mesh && !child.material) {
    child.material = new THREE.MeshStandardMaterial({ color: 0x16233a });
  }
});

现象：模型"巨大/极小"（一盏灯占满整个车间，或看不见）
原因：建模软件单位（cm/mm）≠ Three 单位（米）
修法：导入后统一 scale（cm→m 除以 100；mm→m 除以 1000）

model.scale.setScalar(0.01);   // 如果模型是 cm 导出的，统一缩到米

现象：设备"躺着/倒着"进场景
原因：建模坐标系（z 向上）≠ Three（y 向上）
修法：旋转矫正 model.rotation.x = Math.PI / 2，或建模时就导出正确方向

模型可能自带动画（如叶轮旋转）——存在 gltf.animations 里
Day 110 用 AnimationMixer 播放，今天只要知道"它在哪"

import * as THREE from "three";
import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";

// 1. 全局加载管理器：统一进度与状态
const manager = new THREE.LoadingManager();
let total = 0, loaded = 0;

manager.onStart = (url) => { total++; };                 // 新资源开始
manager.onLoad = () => { console.log("全部资源加载完成"); };  // 全部完成
manager.onProgress = (url, item, all) => {                // 单资源进度
  loaded = all;                                           // 完成的资源数
  updateProgressBar(loaded / total);                      // 更新 UI（Day 111）
};
manager.onError = (url) => { console.error("资源失败：", url); };

// 2. 让所有加载器共享 manager
const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);

// 模型缓存：多台相同设备只加载一次（Day 112 的 6 台同型泵）
const modelCache = new Map<string, THREE.Object3D>();

async function getModel(url: string): Promise<THREE.Object3D> {
  if (modelCache.has(url)) {
    return modelCache.get(url)!.clone();   // 已加载：克隆一个副本（不重复下载）
  }
  const gltf = await new GLTFLoader().loadAsync(url);
  modelCache.set(url, gltf.scene);
  return gltf.scene.clone();
}

// src/core/three/load-workshop-models.ts
import * as THREE from "three";
import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
import { LoadingManager } from "three";
import type { DeviceLayout } from "../config/device-layout";

/**
 * 按布局配置加载车间模型（GLB）
 * 返回：
 *   models     —— 已就位的模型（带 userData.deviceId，可拾取）
 *   onProgress —— 供调用方接进度条（Day 111）
 */
export async function loadWorkshopModels(
  layout: DeviceLayout[],
  manager: LoadingManager
): Promise<THREE.Group[]> {
  const loader = new GLTFLoader(manager);
  const models: THREE.Group[] = [];

  for (const cfg of layout) {
    // 1. 按类型取模型路径（本周用同一台泵模型示范，Day 112 可扩展映射表）
    const url = MODEL_URLS[cfg.type];
    const gltf = await loader.loadAsync(url);

    // 2. 五步体检：单位/方向/材质兜底（第五节）
    const model = gltf.scene;
    model.scale.setScalar(0.01);            // cm → m
    model.traverse((c) => {
      if (c instanceof THREE.Mesh && !c.material) {
        c.material = new THREE.MeshStandardMaterial({ color: 0x16233a });
      }
    });

    // 3. 就位 + 上户口
    model.position.set(cfg.position[0], cfg.position[1], cfg.position[2]);
    model.userData.deviceId = cfg.id;
    models.push(model);
  }
  return models;
}