A. 静态结构类
   1. 车间布局配置（设备清单/位置/朝向声明）   —— 类似 Day 68 的 topo-config
   2. 设备几何与材质（形状、颜色、金属度）     —— 场景树的"零件图纸"
   3. 光照配置（灯的种类/位置/强度）

B. 实时数据类（第 6 个月接 WS，本周先静态）
   4. 设备状态（ok / warn / alarm）
   5. 设备指标（温度、转速——未来驱动动画/颜色）

C. 交互状态类
   6. 相机位置/朝向（OrbitControls 内部）
   7. 悬停/点击的设备（详情面板数据源）
   8. 设备选中态（高亮效果）

D. 动画状态类
   9. 设备自转/风扇旋转相位（0~2π 循环）
   10. 帧时间戳（rAF 的 now）

import { ref } from "vue";
import * as THREE from "three";

// ❌ 反例：把 Three 场景树放进 ref
const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), mat);
const meshRef = ref(mesh);
// → Vue 用 Proxy 深度代理 mesh：
//   每次访问 meshRef.value.rotation 都走 Proxy getter
//   每次改 rotation.y 都触发 Proxy setter + 依赖追踪
//   rAF 里每帧改几十个属性 = 每帧几十次 Proxy + 可能的 watcher 调度

import { markRaw } from "vue";
import * as THREE from "three";

// ✅ 方式 A：markRaw——告诉 Vue"别代理我"
// 适合必须放进响应式容器（ref/reactive）但不需要追踪的场景
const deviceGroup = markRaw(new THREE.Group());

// ✅ 方式 B：普通变量/模块级持有（Day 87 同款纪律，更推荐）
// 场景树根本不需要"进 Vue 的视野"——普通变量即可
let sceneGraph: THREE.Group | null = null;   // 引擎内部持有

/**
 * 入向桥契约：Vue 侧配置/数据 → Three 引擎
 * 原则：桥口要"窄"——只传引擎需要的最小形态，不传整个 store
 */
export interface SceneBridge {
  /** 初始化车间：布局配置（设备清单/位置）→ 场景树（只调一次） */
  initDevices(config: DeviceLayout[]): void;
  /** 数据快照到达：状态 → 驱动设备颜色/动画（第 6 个月接 WS 时用） */
  updateStates(states: Map<string, DeviceState>): void;
  /** resize 通知（DPR/尺寸适配引擎内部处理） */
  resize(): void;
  /** 动画开关：组件失活暂停 / 激活恢复（Day 65 激活喂策略 3D 版） */
  setAnimation(on: boolean): void;
}

/**
 * 出向桥契约：引擎"报告事实"，不携带渲染对象
 * 原则：传 id 传数据，绝不把 Group/Mesh 引用递给 Vue
 */
export type SceneEvents =
  | { type: "hover"; deviceId: string | null }    // 悬停变化（离开为 null）
  | { type: "select"; deviceId: string };          // 设备点击（Day 104 实现）

ThreeViewport.vue（Vue 层：挂载点 + 生命周期）
   │  使用 markRaw/普通变量持有引擎
   ▼
SceneEngine（Three 层：场景树、循环、Raycaster——day99-102 的汇总）
   │  通过 SceneBridge 入向 / SceneEvents 出向
   ▼
Pinia store（数据层：设备状态/指标——第 6 个月才接 WS，本周先静态）

<!-- src/components/ThreeViewport.vue（Day 100 升级版：边界化的完整形态） -->
<script setup lang="ts">
/**
 * 3D 视口组件：Vue 层唯一与 Three 接触的"门户"
 * 边界纪律：
 *   1. 引擎实例普通变量持有（不放进 ref/reactive）
 *   2. 只通过 SceneBridge/SceneEvents 与引擎通信
 *   3. 卸载时停止循环 + dispose（成对纪律）
 */
import { onMounted, onUnmounted, ref } from "vue";
import { createSceneEngine } from "../core/three/scene-engine";
import { deviceLayout } from "../config/device-layout";   // 静态布局配置（Vue 侧）

const canvas = ref<HTMLCanvasElement>();
let dispose: (() => void) | null = null;
let engine: ReturnType<typeof createSceneEngine> | null = null;

onMounted(() => {
  // 1. 创建引擎（内部建场景/光照/循环/桥）
  engine = createSceneEngine(canvas.value!);

  // 2. 入向桥：喂静态布局（本周无 WS，用静态配置）
  engine.bridge.initDevices(deviceLayout);

  // 3. 出向桥：引擎事件 → Vue（Day 104 接交互）
  engine.events.on((e) => {
    if (e.type === "select") {
      // 未来：写 Pinia 选中态 / 打开详情面板
    }
  });

  // 4. 启动循环 + 清理成对
  const stop = engine.start();
  dispose = () => {
    stop();
    engine!.dispose();
  };
});

onUnmounted(() => dispose?.());
</script>

# 3D 场景 × Vue 边界决策文档（Day 103 初稿 / Day 105 定稿）

## 数据裁决表
（第三节完整表格，含三问依据与理由）

## 桥契约
（第五节的 SceneBridge / SceneEvents + 设计原则注释）

## 响应式纪律
- Three 对象只用 markRaw 或普通变量，绝不进 reactive/ref
- 传数据不传对象：Vue 侧只持有 id / 状态，不持有 Group/Mesh

## 反例推演记录
（第四节"场景树进 ref"的掉帧推演，供 review 对照）

## 复审触发条件
- 第 6 个月接 WS 时：确认 updateStates 的分频与脏检查（Day 46 能力回流）
- 设备数 > 500 时：重评 draw call 与可见性剔除（Day 106+ 主线）
- 新增"设备配置面板"时：重审光照/布局配置是否要从 Three 拆回 Vue