From cdc8b0554c92a0a158643a58aba17009f7d9d9e2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=88=98=20=E7=9B=B8=E5=8D=BF?= <lxqmoma@outlook.com>
Date: Fri, 21 Nov 2025 14:04:26 +0800
Subject: [PATCH] docs

---
 src/views/three/12/index.vue | 555 ++++++++++++++++++++++-------------
 注释说明.md                  | 175 +++++++++++
 2 files changed, 531 insertions(+), 199 deletions(-)
 create mode 100644 注释说明.md

diff --git a/src/views/three/12/index.vue b/src/views/three/12/index.vue
index 8bb446c..ccdd323 100644
--- a/src/views/three/12/index.vue
+++ b/src/views/three/12/index.vue
@@ -1,277 +1,325 @@
 <!--
  * @Description: 公共函数抽象 - 综合方案
+ * 这是一个集成了多种 Three.js 功能的综合场景演示：
+ * 1. 使用公共 composables 函数组织代码
+ * 2. 3D 模型加载与交互
+ * 3. 粒子系统（蒸汽效果、火焰效果、火焰蔓延）
+ * 4. 设备告警可视化
+ * 5. 后期处理（轮廓描边）
+ * 6. 射线检测与物体选择
+ * 7. 环境特效（天空盒、地板流动光效）
  * @Autor: 刘 相卿
  * @Date: 2025-11-17 16:08:50
  * @LastEditors: 刘 相卿
- * @LastEditTime: 2025-11-21 11:05:07
+ * @LastEditTime: 2025-11-21 13:57:08
 -->
 <script lang="ts" setup>
 import * as THREE from 'three'
 import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js'
 import { OutputPass } from 'three/examples/jsm/postprocessing/OutputPass.js'
 import { onMounted, onUnmounted, ref, shallowRef } from 'vue'
+// 导入所有公共 composable 函数
 import {
-  useEnvironment,
-  useParticleSystem,
-  usePostProcessing,
-  useThreeLighting,
-  useThreeScene,
+  useEnvironment, // 环境相关功能（天空盒、地板、网格等）
+  useParticleSystem, // 粒子系统（蒸汽、火焰等效果）
+  usePostProcessing, // 后期处理（轮廓描边、特效等）
+  useThreeLighting, // 灯光系统配置
+  useThreeScene, // 场景基础设置（场景、相机、渲染器、控制器）
 } from '@/composes/three'
 
-const threeRef = shallowRef<HTMLDivElement>()
+// ============ DOM 引用 ============
+const threeRef = shallowRef<HTMLDivElement>() // Three.js 渲染容器的引用
 
-let scene: THREE.Scene
-let camera: THREE.PerspectiveCamera
-let renderer: THREE.WebGLRenderer
-let controls: any
-let animationId: number
-let model: THREE.Group
-let composer: any
-let outlinePass: any
+// ============ Three.js 核心对象 ============
+let scene: THREE.Scene // 3D 场景
+let camera: THREE.PerspectiveCamera // 透视相机
+let renderer: THREE.WebGLRenderer // WebGL 渲染器
+let controls: any // 轨道控制器（OrbitControls）
+let animationId: number // 动画帧 ID，用于取消动画循环
+let model: THREE.Group // 加载的 GLTF 3D 模型
+let composer: any // 后期处理合成器
+let outlinePass: any // 轮廓描边 Pass
 
-// 粒子发射器
-let particleEmitter: any
-const isEmitting = ref(false)
+// ============ 粒子系统 - 蒸汽效果 ============
+let particleEmitter: any // 蒸汽粒子发射器（用于设备 kzf_peij_18）
+const isEmitting = ref(false) // 是否正在发射蒸汽粒子
 
-// 火焰发射器
-let flameEmitter: any
-const isFlaming = ref(false)
-const flameEmitters: any[] = [] // 所有火焰发射器数组
-const burningMeshes = new Set<THREE.Mesh>() // 已着火的网格集合
-let spreadTimer = 0 // 蔓延计时器
-const spreadInterval = 2 // 每2秒蔓延一次
-let centerFireEmitter: any = null // 中心大火发射器
-let totalMeshCount = 0 // 模型中网格总数
+// ============ 粒子系统 - 火焰效果 ============
+let flameEmitter: any // 初始火焰发射器
+const isFlaming = ref(false) // 是否开启火焰效果
+const flameEmitters: any[] = [] // 存储所有火焰发射器的数组（包括蔓延的火焰）
+const burningMeshes = new Set<THREE.Mesh>() // 已经着火的网格集合，用于火焰蔓延判断
+let spreadTimer = 0 // 火焰蔓延计时器（累计秒数）
+const spreadInterval = 2 // 火焰蔓延间隔时间（秒）
+let centerFireEmitter: any = null // 中心大火发射器（当火焰蔓延到整个模型时创建）
+let totalMeshCount = 0 // 模型中的网格总数（用于判断火焰蔓延程度）
 
-// 地板流动效果
-let flowingGround: any
+// ============ 地板特效 ============
+let flowingGround: any // 地板流动光效对象
 
-// 告警物体
-let alertMesh: THREE.Mesh | null = null
-const isAlerting = ref(false)
-let alertTime = 0
+// ============ 设备告警系统 ============
+let alertMesh: THREE.Mesh | null = null // 告警设备的网格对象（kzf_peij_18）
+const isAlerting = ref(false) // 是否处于告警状态
+let alertTime = 0 // 告警动画时间累计器（用于闪烁效果）
 
-// 选中物体信息
+// ============ 物体选择与信息显示 ============
 const selectedObject = ref<{
-  name: string
-  position: THREE.Vector3
-  material: string
-  mesh: THREE.Mesh
-} | null>(null)
+  name: string // 物体名称
+  position: THREE.Vector3 // 物体位置
+  material: string // 材质类型
+  mesh: THREE.Mesh // 网格对象引用
+} | null>(null) // 当前选中的物体信息
 
-const labelPosition = ref({ x: 0, y: 0 })
-const showDialog = ref(false)
+const labelPosition = ref({ x: 0, y: 0 }) // 物体信息标签在屏幕上的位置
+const showDialog = ref(false) // 是否显示设备详情弹窗
 const dialogContent = ref({
-  title: '',
-  description: '',
-  status: 'normal' as 'normal' | 'alert',
+  title: '', // 弹窗标题
+  description: '', // 弹窗描述
+  status: 'normal' as 'normal' | 'alert', // 设备状态
 })
 
-// 射线检测
-let raycaster: THREE.Raycaster
-let mouse: THREE.Vector2
+// ============ 射线检测（用于物体点击选择） ============
+let raycaster: THREE.Raycaster // 射线投射器
+let mouse: THREE.Vector2 // 鼠标在归一化设备坐标系中的位置 (-1 到 1)
 
+/**
+ * 初始化 Three.js 场景
+ * 这是整个应用的核心初始化函数，负责设置所有 3D 元素
+ */
 function init() {
+  // 检查 DOM 容器是否存在
   if (!threeRef.value)
     return
 
+  // 获取容器尺寸
   const width = threeRef.value.clientWidth
   const height = threeRef.value.clientHeight
 
-  // 使用公共函数创建基础场景
-  const sceneUtils = useThreeScene()
-  const envUtils = useEnvironment()
-  const lightingUtils = useThreeLighting()
-  const postUtils = usePostProcessing()
-  const particleUtils = useParticleSystem()
+  // ============ 初始化公共工具函数 ============
+  const sceneUtils = useThreeScene() // 场景基础工具
+  const envUtils = useEnvironment() // 环境效果工具
+  const lightingUtils = useThreeLighting() // 灯光工具
+  const postUtils = usePostProcessing() // 后期处理工具
+  const particleUtils = useParticleSystem() // 粒子系统工具
 
-  // 创建场景
+  // ============ 创建场景 ============
+  // 创建基础场景，配置海洋主题的背景色和雾效
   scene = sceneUtils.createScene({
-    backgroundColor: 0x001A33,
-    enableFog: true,
-    fogColor: 0x001A33,
-    fogNear: 20,
-    fogFar: 100,
+    backgroundColor: 0x001A33, // 深海蓝色
+    enableFog: true, // 启用雾效
+    fogColor: 0x001A33, // 雾的颜色与背景色一致
+    fogNear: 20, // 雾效开始距离
+    fogFar: 100, // 雾效结束距离（完全被雾遮挡）
   })
 
-  // 创建海蓝色渐变背景
+  // ============ 创建环境背景 ============
+  // 创建海蓝色渐变背景（从深蓝到浅蓝的垂直渐变）
   envUtils.createOceanGradientBackground(scene)
 
-  // 创建天空盒
+  // 创建天空盒（模拟天空环境）
   envUtils.createSkybox(scene, 0x004D80, 0x001A33)
 
-  // 创建相机
+  // ============ 创建相机 ============
   camera = sceneUtils.createCamera({
-    fov: 75,
-    aspect: width / height,
-    near: 0.1,
-    far: 1000,
-    position: { x: 0, y: 8, z: 18 },
+    fov: 75, // 视野角度（越大视野越广）
+    aspect: width / height, // 宽高比
+    near: 0.1, // 近裁剪面
+    far: 1000, // 远裁剪面
+    position: { x: 0, y: 8, z: 18 }, // 相机初始位置
   })
 
-  // 创建渲染器
+  // ============ 创建渲染器 ============
   renderer = sceneUtils.createRenderer(threeRef.value, {
-    antialias: true,
-    shadowMap: true,
-    shadowMapType: THREE.PCFSoftShadowMap,
-    toneMapping: THREE.ACESFilmicToneMapping,
-    toneMappingExposure: 0.8,
+    antialias: true, // 启用抗锯齿
+    shadowMap: true, // 启用阴影贴图
+    shadowMapType: THREE.PCFSoftShadowMap, // 使用柔和阴影
+    toneMapping: THREE.ACESFilmicToneMapping, // ACES 电影色调映射
+    toneMappingExposure: 0.8, // 曝光度（控制整体亮度）
   })
 
-  // 创建控制器
+  // ============ 创建控制器 ============
+  // 创建轨道控制器，允许用户通过鼠标控制相机
   controls = sceneUtils.createControls(camera, renderer)
 
-  // 设置灯光系统
+  // ============ 设置灯光系统 ============
   lightingUtils.setupLighting(scene, {
-    ambientLight: true,
-    ambientIntensity: 0.8,
+    ambientLight: true, // 启用环境光
+    ambientIntensity: 0.8, // 环境光强度
+    // 配置三个方向光
     directionalLights: [
       {
-        color: 0xFFFFFF,
-        intensity: 1.5,
-        position: { x: 10, y: 15, z: 10 },
-        castShadow: true,
+        color: 0xFFFFFF, // 白色主光源
+        intensity: 1.5, // 光照强度
+        position: { x: 10, y: 15, z: 10 }, // 光源位置（右上前方）
+        castShadow: true, // 产生阴影
       },
       {
-        color: 0x4488FF,
+        color: 0x4488FF, // 蓝色补光
         intensity: 0.8,
-        position: { x: -10, y: 10, z: -10 },
-        castShadow: false,
+        position: { x: -10, y: 10, z: -10 }, // 左上后方
+        castShadow: false, // 不产生阴影（避免性能开销）
       },
       {
-        color: 0xFFFFFF,
+        color: 0xFFFFFF, // 白色补光
         intensity: 0.6,
-        position: { x: 0, y: 5, z: -15 },
+        position: { x: 0, y: 5, z: -15 }, // 后方
         castShadow: false,
       },
     ],
+    // 配置两个点光源（用于局部照明）
     pointLights: [
       {
-        color: 0x00FFFF,
+        color: 0x00FFFF, // 青色点光源
         intensity: 2,
-        distance: 20,
-        position: { x: -8, y: 3, z: -8 },
+        distance: 20, // 光照距离
+        position: { x: -8, y: 3, z: -8 }, // 左后方
       },
       {
-        color: 0x00FFFF,
+        color: 0x00FFFF, // 青色点光源
         intensity: 2,
         distance: 20,
-        position: { x: 8, y: 3, z: -8 },
+        position: { x: 8, y: 3, z: -8 }, // 右后方
       },
     ],
   })
 
-  // 创建有厚度的地板
+  // ============ 创建地板 ============
+  // 创建有厚度的立体地板
   const ground = envUtils.createThickGround(100, 0.8, 0x2C3E50)
   scene.add(ground)
 
-  // 添加地板流动效果
+  // 添加地板流动光效（动态光流效果）
   flowingGround = envUtils.createFlowingGroundEffect(100)
   scene.add(flowingGround.mesh)
 
-  // 创建网格辅助线
+  // 创建网格辅助线（帮助理解空间关系）
   const grid = envUtils.createGrid(100, 50, 0x00FFFF, 0x004D80)
-  grid.position.y = 0.02
+  grid.position.y = 0.02 // 稍微抬高，避免 z-fighting
   scene.add(grid)
 
-  // 设置后期处理
+  // ============ 设置后期处理 ============
+  // 创建后期处理合成器
   composer = postUtils.createComposer(renderer, scene, camera)
 
-  // 配置轮廓描边
+  // 配置轮廓描边效果（用于高亮选中的物体）
   outlinePass = postUtils.createOutlinePass(width, height, scene, camera)
-  outlinePass.renderToScreen = false
+  outlinePass.renderToScreen = false // 不直接输出到屏幕
   outlinePass.selectedObjects = [] // 初始化为空数组
 
-  composer.addPass(outlinePass)
+  composer.addPass(outlinePass) // 添加轮廓描边 Pass
 
+  // 添加输出 Pass（最终输出）
   const outputPass = new OutputPass()
   composer.addPass(outputPass)
 
-  // 初始化射线检测
+  // ============ 初始化射线检测 ============
+  // 用于鼠标点击物体检测
   raycaster = new THREE.Raycaster()
   mouse = new THREE.Vector2()
 
-  // 加载模型
+  // ============ 加载 3D 模型 ============
   loadModel(particleUtils)
 
-  // 事件监听
-  renderer.domElement.addEventListener('click', onCanvasClick)
-  window.addEventListener('resize', onResize)
+  // ============ 事件监听 ============
+  renderer.domElement.addEventListener('click', onCanvasClick) // 监听画布点击
+  window.addEventListener('resize', onResize) // 监听窗口大小变化
 
+  // ============ 启动动画循环 ============
   animate()
 }
 
+/**
+ * 加载 GLTF 3D 模型
+ * @param particleUtils - 粒子系统工具（用于创建蒸汽和火焰效果）
+ */
 function loadModel(particleUtils: any) {
   const loader = new GLTFLoader()
+
+  // 加载模型文件
   loader.load('/mzjc_bansw.glb', (gltf) => {
     model = gltf.scene
 
-    // 统计网格总数
+    // 统计模型中的网格总数（用于火焰蔓延进度判断）
     totalMeshCount = 0
+
+    // 遍历模型中的所有子对象
     model.traverse((child) => {
+      // 只处理网格对象
       if (child instanceof THREE.Mesh) {
         totalMeshCount++
-        child.castShadow = true
-        child.receiveShadow = true
+
+        // 配置阴影
+        child.castShadow = true // 产生阴影
+        child.receiveShadow = true // 接收阴影
+
+        // 设置用户数据（用于后续查询和交互）
         child.userData.objectType = '建筑构件'
         child.userData.objectName = child.name || '未命名物体'
 
-        // 找到特定设备 kzf_peij_18
+        // ============ 找到特定设备 kzf_peij_18（用于告警和蒸汽效果） ============
         if (child.name === 'kzf_peij_18') {
           alertMesh = child
 
-          // 为该设备创建粒子发射器
+          // 计算物体的包围盒和顶部位置
           const box = new THREE.Box3().setFromObject(child)
           const center = box.getCenter(new THREE.Vector3())
           const topPosition = new THREE.Vector3(center.x, box.max.y, center.z)
 
+          // 在设备顶部创建蒸汽粒子发射器
           particleEmitter = particleUtils.createEmitter(scene, topPosition, 3)
           isEmitting.value = true // 默认开启蒸汽效果
 
-          // 标记为告警设备
+          // 标记为可告警设备
           child.userData.canAlert = true
           child.userData.status = 'normal'
         }
 
-        // 找到 pingt01_0019_pCylinder10001 添加火焰效果
+        // ============ 找到 pingt01_0019_pCylinder10001（初始着火点） ============
         if (child.name === 'pingt01_0019_pCylinder10001') {
           const box = new THREE.Box3().setFromObject(child)
           const center = box.getCenter(new THREE.Vector3())
           const topPosition = new THREE.Vector3(center.x, box.max.y, center.z)
 
+          // 创建火焰粒子发射器
           flameEmitter = particleUtils.createFlameEmitter(scene, topPosition, 8)
           flameEmitters.push({ emitter: flameEmitter, mesh: child })
-          burningMeshes.add(child)
+          burningMeshes.add(child) // 添加到已着火集合
           isFlaming.value = true // 默认开启火焰效果
 
-          // 给着火物体添加发光效果
+          // 给着火物体添加发光效果（模拟火光）
           if (child.material) {
             const material = child.material as THREE.MeshStandardMaterial
-            material.emissive = new THREE.Color(0xFF4400)
-            material.emissiveIntensity = 0.5
+            material.emissive = new THREE.Color(0xFF4400) // 橙红色发光
+            material.emissiveIntensity = 0.5 // 发光强度
           }
         }
       }
     })
 
+    // 将模型添加到场景中
     scene.add(model)
   })
 }
 
-// 火焰蔓延函数
+/**
+ * 火焰蔓延函数
+ * 每隔 spreadInterval 秒执行一次，检测已着火物体周围的物体
+ * 如果距离小于阈值，则点燃该物体
+ */
 function spreadFire() {
   if (!model)
     return
 
   const particleUtils = useParticleSystem()
-  const spreadDistance = 3 // 蔓延距离阈值
+  const spreadDistance = 3 // 火焰蔓延距离阈值（单位：Three.js 世界单位）
 
   // 遍历所有已着火的物体
   burningMeshes.forEach((burningMesh) => {
+    // 获取着火物体的包围盒和中心点
     const burningBox = new THREE.Box3().setFromObject(burningMesh)
     const burningCenter = burningBox.getCenter(new THREE.Vector3())
 
-    // 遍历模型中的所有网格
+    // 遍历模型中的所有网格，查找未着火的物体
     model.traverse((child) => {
       if (child instanceof THREE.Mesh && !burningMeshes.has(child)) {
         // 计算与着火物体的距离
@@ -281,11 +329,12 @@ function spreadFire() {
 
         // 如果距离小于阈值，点燃该物体
         if (distance < spreadDistance) {
+          // 在物体顶部创建火焰发射器
           const topPosition = new THREE.Vector3(childCenter.x, childBox.max.y, childCenter.z)
           const newFlameEmitter = particleUtils.createFlameEmitter(scene, topPosition, 6)
 
           flameEmitters.push({ emitter: newFlameEmitter, mesh: child })
-          burningMeshes.add(child)
+          burningMeshes.add(child) // 添加到已着火集合
 
           // 给新着火物体添加发光效果
           if (child.material) {
@@ -299,59 +348,66 @@ function spreadFire() {
   })
 
   // 检查是否已经蔓延到整个模型（80%以上的网格着火）
+  // 如果是，则创建中心大火效果
   if (burningMeshes.size >= totalMeshCount * 0.8 && !centerFireEmitter) {
     createCenterFire()
   }
 }
 
-// 移除初始着火点的火焰
+/**
+ * 移除初始着火点的火焰
+ * 在创建中心大火时调用，避免重复的火焰效果
+ */
 function removeInitialFire() {
   // 找到并移除 pingt01_0019_pCylinder10001 的火焰发射器
   for (let i = flameEmitters.length - 1; i >= 0; i--) {
     const { emitter, mesh } = flameEmitters[i]
     if (mesh && mesh.name === 'pingt01_0019_pCylinder10001') {
-      emitter.stop()
-      flameEmitters.splice(i, 1)
+      emitter.stop() // 停止粒子发射
+      flameEmitters.splice(i, 1) // 从数组中移除
       break
     }
   }
 }
 
-// 创建中心大火效果
+/**
+ * 创建中心大火效果
+ * 当火焰蔓延到整个模型（80%以上）时触发
+ * 将所有小火焰替换为一个覆盖整个模型的大型火焰效果
+ */
 function createCenterFire() {
   if (!model)
     return
 
   const particleUtils = useParticleSystem()
 
-  // 先移除初始着火点
+  // 先移除初始着火点的火焰
   removeInitialFire()
 
-  // 移除所有小火焰发射器
+  // 停止所有小火焰发射器（但保留发光效果）
   flameEmitters.forEach(({ emitter }) => {
     emitter.stop()
-    // 保留发光效果
   })
-  flameEmitters.length = 0
+  flameEmitters.length = 0 // 清空数组
 
-  // 计算模型中心和范围
+  // 计算模型的包围盒、中心点和尺寸
   const modelBox = new THREE.Box3().setFromObject(model)
   const modelCenter = modelBox.getCenter(new THREE.Vector3())
   const modelSize = modelBox.getSize(new THREE.Vector3())
 
-  // 在中心创建大型火焰发射器 - 使用增强版
+  // ============ 在中心创建主火焰发射器 ============
   centerFireEmitter = particleUtils.createIntenseFireEmitter(
     scene,
-    new THREE.Vector3(modelCenter.x, modelBox.min.y, modelCenter.z),
-    80, // 更多粒子
-    modelSize.x * 0.5, // 扩散范围
+    new THREE.Vector3(modelCenter.x, modelBox.min.y, modelCenter.z), // 从地面开始
+    80, // 粒子数量
+    modelSize.x * 0.5, // 扩散范围（模型宽度的一半）
   )
 
-  // 添加多层火焰效果，模拟整体燃烧
+  // ============ 添加多层火焰效果，模拟整体燃烧 ============
   const layers = [
-    { y: modelBox.min.y, count: 60, spread: modelSize.x * 0.4 },
-    { y: modelBox.min.y + modelSize.y * 0.3, count: 50, spread: modelSize.x * 0.3 },
-    { y: modelBox.min.y + modelSize.y * 0.6, count: 40, spread: modelSize.x * 0.2 },
+    { y: modelBox.min.y, count: 60, spread: modelSize.x * 0.4 }, // 底层
+    { y: modelBox.min.y + modelSize.y * 0.3, count: 50, spread: modelSize.x * 0.3 }, // 中层
+    { y: modelBox.min.y + modelSize.y * 0.6, count: 40, spread: modelSize.x * 0.2 }, // 上层
   ]
 
   layers.forEach((layer) => {
@@ -364,12 +420,12 @@ function createCenterFire() {
     flameEmitters.push({ emitter, mesh: null })
   })
 
-  // 四周添加火焰柱
+  // ============ 在四周添加火焰柱 ============
   const positions = [
-    new THREE.Vector3(modelBox.min.x, modelBox.min.y, modelCenter.z),
-    new THREE.Vector3(modelBox.max.x, modelBox.min.y, modelCenter.z),
-    new THREE.Vector3(modelCenter.x, modelBox.min.y, modelBox.min.z),
-    new THREE.Vector3(modelCenter.x, modelBox.min.y, modelBox.max.z),
+    new THREE.Vector3(modelBox.min.x, modelBox.min.y, modelCenter.z), // 左侧
+    new THREE.Vector3(modelBox.max.x, modelBox.min.y, modelCenter.z), // 右侧
+    new THREE.Vector3(modelCenter.x, modelBox.min.y, modelBox.min.z), // 前侧
+    new THREE.Vector3(modelCenter.x, modelBox.min.y, modelBox.max.z), // 后侧
   ]
 
   positions.forEach((pos) => {
@@ -377,64 +433,70 @@ function createCenterFire() {
     flameEmitters.push({ emitter, mesh: null })
   })
 
-  // 添加主中心发射器
+  // 添加主中心发射器到数组
   flameEmitters.push({ emitter: centerFireEmitter, mesh: null })
 }
 
+/**
+ * 动画循环函数
+ * 每帧调用一次，更新场景中的所有动画效果
+ */
 function animate() {
-  animationId = requestAnimationFrame(animate)
-  controls.update()
+  animationId = requestAnimationFrame(animate) // 请求下一帧
+  controls.update() // 更新控制器
 
-  const time = performance.now() * 0.001
+  const time = performance.now() * 0.001 // 获取当前时间（秒）
 
-  // 更新地板流动效果
+  // ============ 更新地板流动效果 ============
   if (flowingGround) {
     flowingGround.update(time)
   }
 
-  // 更新粒子系统
+  // ============ 更新蒸汽粒子系统 ============
   if (isEmitting.value && particleEmitter) {
     particleEmitter.update()
   }
 
-  // 更新火焰粒子系统
+  // ============ 更新火焰粒子系统 ============
   if (isFlaming.value) {
-    // 更新所有火焰发射器
+    // 更新所有火焰发射器的粒子
     flameEmitters.forEach(({ emitter }) => {
       emitter.update()
     })
 
-    // 火焰蔓延逻辑
+    // ============ 火焰蔓延逻辑 ============
     if (model) {
-      spreadTimer += 1 / 60 // 每帧增加约1/60秒
+      spreadTimer += 1 / 60 // 每帧增加约1/60秒（假设60fps）
 
+      // 如果达到蔓延间隔时间，执行火焰蔓延
       if (spreadTimer >= spreadInterval) {
-        spreadTimer = 0
-        spreadFire()
+        spreadTimer = 0 // 重置计时器
+        spreadFire() // 执行蔓延
       }
     }
   }
 
-  // 更新告警闪烁效果
+  // ============ 更新告警闪烁效果 ============
   if (isAlerting.value && alertMesh) {
-    alertTime += 0.05
-    const intensity = (Math.sin(alertTime * 5) + 1) / 2
+    alertTime += 0.05 // 增加时间
+    const intensity = (Math.sin(alertTime * 5) + 1) / 2 // 计算闪烁强度（0-1之间）
 
-    // 材质闪烁
+    // 更新材质的发光效果
     if (alertMesh.material) {
       const material = alertMesh.material as THREE.MeshStandardMaterial
       if (material.emissive) {
-        material.emissive.setRGB(intensity, 0, 0)
-        material.emissiveIntensity = intensity * 2
+        material.emissive.setRGB(intensity, 0, 0) // 红色闪烁
+        material.emissiveIntensity = intensity * 2 // 发光强度随闪烁变化
       }
     }
   }
 
-  // 更新选中物体标签位置
+  // ============ 更新选中物体标签位置 ============
   if (selectedObject.value) {
-    updateLabelPosition()
+    updateLabelPosition() // 实时更新标签位置（跟随相机移动）
   }
 
+  // 使用合成器渲染（包含后期处理效果）
   composer.render()
   // if (outlinePass.enabled) {
   //   composer.render()
@@ -444,48 +506,71 @@ function animate() {
   // }
 }
 
+/**
+ * 更新物体信息标签的屏幕位置
+ * 将 3D 世界坐标转换为 2D 屏幕坐标
+ */
 function updateLabelPosition() {
   if (!selectedObject.value)
     return
 
+  // 获取物体的包围盒
   const box = new THREE.Box3().setFromObject(selectedObject.value.mesh)
-  const height = box.max.y - box.min.y
-  const position = selectedObject.value.position.clone()
-  position.y = box.max.y + height * 0.3
+  const height = box.max.y - box.min.y // 物体高度
 
+  // 计算标签位置（物体顶部上方一定距离）
+  const position = selectedObject.value.position.clone()
+  position.y = box.max.y + height * 0.3 // 在物体顶部上方30%高度处显示
+
+  // 将 3D 坐标投影到屏幕坐标
   position.project(camera)
 
+  // 转换为屏幕像素坐标
   labelPosition.value = {
-    x: (position.x * 0.5 + 0.5) * threeRef.value!.clientWidth,
-    y: (-(position.y * 0.5) + 0.5) * threeRef.value!.clientHeight,
+    x: (position.x * 0.5 + 0.5) * threeRef.value!.clientWidth, // -1~1 转换为 0~width
+    y: (-(position.y * 0.5) + 0.5) * threeRef.value!.clientHeight, // -1~1 转换为 0~height（Y轴反转）
   }
 }
 
+/**
+ * 画布点击事件处理函数
+ * 使用射线检测选中点击的物体
+ * @param event - 鼠标事件对象
+ */
 function onCanvasClick(event: MouseEvent) {
+  // 获取画布的位置和尺寸
   const rect = renderer.domElement.getBoundingClientRect()
+
+  // 将鼠标位置转换为归一化设备坐标（-1 到 1）
   mouse.x = ((event.clientX - rect.left) / rect.width) * 2 - 1
   mouse.y = -((event.clientY - rect.top) / rect.height) * 2 + 1
 
+  // 从相机位置发射射线
   raycaster.setFromCamera(mouse, camera)
 
   if (model) {
+    // 检测射线与模型的交点（递归检测所有子对象）
     const intersects = raycaster.intersectObject(model, true)
 
     if (intersects.length > 0 && intersects[0]) {
+      // 获取第一个（最近的）交点的物体
       const object = intersects[0].object as THREE.Mesh
-      const point = intersects[0].point
+      const point = intersects[0].point // 交点的世界坐标
 
-      // 获取材质信息
+      // ============ 获取材质信息 ============
       let materialName = '未知材质'
       if (object.material) {
         if (Array.isArray(object.material)) {
+          // 多材质：拼接所有材质类型
           materialName = object.material.map((m: THREE.Material) => m.type).join(', ')
         }
         else {
+          // 单材质
           materialName = object.material.type
         }
       }
 
+      // ============ 保存选中物体信息 ============
       selectedObject.value = {
         name: object.userData.objectName || object.name || '未命名物体',
         material: materialName,
@@ -493,24 +578,27 @@ function onCanvasClick(event: MouseEvent) {
         mesh: object,
       }
 
-      // 添加轮廓描边（绿色）
+      // ============ 添加绿色轮廓描边 ============
       outlinePass.selectedObjects = [object]
-      outlinePass.visibleEdgeColor.set('#00ff00')
-      outlinePass.hiddenEdgeColor.set('#00ff00')
-      // outlinePass.enabled = true
+      outlinePass.visibleEdgeColor.set('#00ff00') // 可见边缘颜色
+      outlinePass.hiddenEdgeColor.set('#00ff00') // 隐藏边缘颜色
 
-      // 如果点击的是告警设备
+      // ============ 如果点击的是告警设备，显示详情弹窗 ============
       if (object === alertMesh) {
         showDeviceDialog(object)
       }
     }
     else {
-      // 点击空白处
+      // 点击空白处：清除选择
       clearSelection()
     }
   }
 }
 
+/**
+ * 显示设备详情弹窗
+ * @param mesh - 设备的网格对象
+ */
 function showDeviceDialog(mesh: THREE.Mesh) {
   const status = isAlerting.value ? 'alert' : 'normal'
   dialogContent.value = {
@@ -523,12 +611,19 @@ function showDeviceDialog(mesh: THREE.Mesh) {
   showDialog.value = true
 }
 
+/**
+ * 清除物体选择
+ * 隐藏标签和轮廓描边
+ */
 function clearSelection() {
   selectedObject.value = null
   outlinePass.selectedObjects = []
-  // outlinePass.enabled = false
 }
 
+/**
+ * 切换设备告警状态
+ * 触发红色闪烁效果和轮廓描边
+ */
 function toggleAlert() {
   if (!alertMesh) {
     console.warn('模型尚未加载或未找到设备 kzf_peij_18')
@@ -539,49 +634,56 @@ function toggleAlert() {
   alertMesh.userData.status = isAlerting.value ? 'alert' : 'normal'
 
   if (isAlerting.value) {
-    // 开启告警：红色轮廓
+    // ============ 开启告警 ============
+    // 添加红色轮廓描边
     outlinePass.selectedObjects = [alertMesh]
     outlinePass.visibleEdgeColor.set('#ff0000')
     outlinePass.hiddenEdgeColor.set('#ff0000')
-    // outlinePass.enabled = true
 
-    // 设置材质发光
+    // 设置材质为红色发光
     if (alertMesh.material) {
       const material = alertMesh.material as THREE.MeshStandardMaterial
-      material.emissive = new THREE.Color(0xFF0000)
+      material.emissive = new THREE.Color(0xFF0000) // 红色发光
       material.emissiveIntensity = 1
     }
   }
   else {
-    // 关闭告警
-    alertTime = 0
+    // ============ 关闭告警 ============
+    alertTime = 0 // 重置时间
+
+    // 移除发光效果
     if (alertMesh.material) {
       const material = alertMesh.material as THREE.MeshStandardMaterial
-      material.emissive = new THREE.Color(0x000000)
+      material.emissive = new THREE.Color(0x000000) // 黑色（无发光）
       material.emissiveIntensity = 0
     }
-    if (selectedObject.value?.mesh !== alertMesh) {
-      // outlinePass.enabled = false
-    }
   }
 }
 
+/**
+ * 切换蒸汽粒子效果
+ */
 function toggleParticles() {
   isEmitting.value = !isEmitting.value
   if (!isEmitting.value && particleEmitter) {
-    particleEmitter.stop()
+    particleEmitter.stop() // 停止粒子发射
   }
 }
 
+/**
+ * 切换火焰效果
+ * 包含火焰的开启/关闭以及火焰蔓延的重置
+ */
 function toggleFlame() {
   isFlaming.value = !isFlaming.value
 
   if (!isFlaming.value) {
+    // ============ 关闭火焰 ============
     // 停止所有火焰发射器
     flameEmitters.forEach(({ emitter, mesh }) => {
       emitter.stop()
 
-      // 移除发光效果
+      // 移除物体的发光效果
       if (mesh && mesh.material) {
         const material = mesh.material as THREE.MeshStandardMaterial
         material.emissive = new THREE.Color(0x000000)
@@ -589,12 +691,12 @@ function toggleFlame() {
       }
     })
 
-    // 停止中心大火
+    // 清空中心大火
     if (centerFireEmitter) {
       centerFireEmitter = null
     }
 
-    // 移除所有物体的发光效果
+    // 移除所有已着火物体的发光效果
     burningMeshes.forEach((mesh) => {
       if (mesh.material) {
         const material = mesh.material as THREE.MeshStandardMaterial
@@ -603,13 +705,14 @@ function toggleFlame() {
       }
     })
 
-    // 清空数组和集合
+    // 清空数组和集合，重置状态
     flameEmitters.length = 0
     burningMeshes.clear()
     spreadTimer = 0
   }
   else {
-    // 重新点燃初始物体
+    // ============ 开启火焰 ============
+    // 重新点燃初始物体（pingt01_0019_pCylinder10001）
     if (model) {
       const particleUtils = useParticleSystem()
       model.traverse((child) => {
@@ -618,6 +721,7 @@ function toggleFlame() {
           const center = box.getCenter(new THREE.Vector3())
           const topPosition = new THREE.Vector3(center.x, box.max.y, center.z)
 
+          // 创建火焰发射器
           const newFlameEmitter = particleUtils.createFlameEmitter(scene, topPosition, 8)
           flameEmitters.push({ emitter: newFlameEmitter, mesh: child })
           burningMeshes.add(child)
@@ -634,31 +738,53 @@ function toggleFlame() {
   }
 }
 
+/**
+ * 关闭设备详情弹窗
+ */
 function closeDialog() {
   showDialog.value = false
 }
 
+/**
+ * 窗口大小变化处理函数
+ * 更新相机和渲染器的尺寸
+ */
 function onResize() {
   if (!threeRef.value)
     return
+
   const width = threeRef.value.clientWidth
   const height = threeRef.value.clientHeight
+
+  // 更新相机宽高比
   camera.aspect = width / height
   camera.updateProjectionMatrix()
+
+  // 更新渲染器尺寸
   renderer.setSize(width, height)
   composer.setSize(width, height)
 }
 
+// ============ 生命周期钩子 ============
+// 组件挂载时初始化场景
 onMounted(init)
+
+// 组件卸载时清理资源
 onUnmounted(() => {
+  // 取消动画循环
   cancelAnimationFrame(animationId)
+
+  // 移除事件监听器
   window.removeEventListener('resize', onResize)
   if (renderer.domElement) {
     renderer.domElement.removeEventListener('click', onCanvasClick)
   }
+
+  // 停止蒸汽粒子发射器
   if (particleEmitter) {
     particleEmitter.stop()
   }
+
   // 停止所有火焰发射器
   flameEmitters.forEach(({ emitter }) => {
     emitter.stop()
@@ -666,15 +792,18 @@ onUnmounted(() => {
   flameEmitters.length = 0
   burningMeshes.clear()
 
+  // 释放渲染器资源
   renderer.dispose()
   composer.dispose()
 })
 </script>
 
 <template>
+  <!-- Three.js 渲染容器：占满整个父容器 -->
   <div ref="threeRef" class="w-full h-full" />
 
-  <!-- 物体信息标签 -->
+  <!-- ============ 物体信息标签 ============ -->
+  <!-- 当选中物体时显示，位置动态跟随物体 -->
   <div
     v-if="selectedObject"
     class="object-label"
@@ -684,13 +813,16 @@ onUnmounted(() => {
     }"
   >
     <div class="label-content">
+      <!-- 物体名称 -->
       <div class="label-title">
         {{ selectedObject.name }}
       </div>
+      <!-- 材质信息 -->
       <div class="label-item">
         <span class="label-key">材质：</span>
         <span class="label-value">{{ selectedObject.material }}</span>
       </div>
+      <!-- 坐标信息 -->
       <div class="label-item">
         <span class="label-key">坐标：</span>
         <span class="label-value">
@@ -702,20 +834,27 @@ onUnmounted(() => {
     </div>
   </div>
 
-  <!-- 设备详情弹窗 -->
+  <!-- ============ 设备详情弹窗 ============ -->
+  <!-- 点击告警设备时显示 -->
   <div v-if="showDialog" class="dialog-overlay" @click="closeDialog">
+    <!-- 弹窗主体，阻止点击事件冒泡 -->
     <div class="dialog" :class="{ alert: dialogContent.status === 'alert' }" @click.stop>
+      <!-- 弹窗头部 -->
       <div class="dialog-header">
         <h3>{{ dialogContent.title }}</h3>
+        <!-- 告警徽章（仅在告警状态显示） -->
         <div v-if="dialogContent.status === 'alert'" class="alert-badge">
           告警
         </div>
+        <!-- 关闭按钮 -->
         <button class="close-btn" @click="closeDialog">
           ×
         </button>
       </div>
+      <!-- 弹窗内容 -->
       <div class="dialog-body">
         <p>{{ dialogContent.description }}</p>
+        <!-- 告警状态信息 -->
         <div v-if="dialogContent.status === 'alert'" class="alert-info">
           <div class="alert-icon">
             ⚠️
@@ -726,6 +865,7 @@ onUnmounted(() => {
             <div>运行时间：152小时</div>
           </div>
         </div>
+        <!-- 正常状态信息 -->
         <div v-else class="normal-info">
           <div>✓ 温度：65°C</div>
           <div>✓ 压力：正常</div>
@@ -735,12 +875,14 @@ onUnmounted(() => {
     </div>
   </div>
 
-  <!-- 控制面板 -->
+  <!-- ============ 控制面板 ============ -->
+  <!-- 左侧固定位置的控制面板 -->
   <div class="control-panel">
     <h3 class="panel-title">
       综合场景控制
     </h3>
 
+    <!-- 场景特性列表 -->
     <div class="control-section">
       <h4>场景特性</h4>
       <ul class="feature-list">
@@ -752,19 +894,24 @@ onUnmounted(() => {
       </ul>
     </div>
 
+    <!-- 设备控制按钮 -->
     <div class="control-section">
       <h4>设备控制</h4>
+      <!-- 切换告警状态按钮 -->
       <button class="control-btn" @click="toggleAlert">
         {{ isAlerting ? '关闭' : '触发' }}设备告警
       </button>
+      <!-- 切换蒸汽效果按钮 -->
       <button class="control-btn" @click="toggleParticles">
         {{ isEmitting ? '关闭' : '开启' }}蒸汽效果
       </button>
+      <!-- 切换火焰效果按钮 -->
       <button class="control-btn flame-btn" @click="toggleFlame">
         {{ isFlaming ? '关闭' : '开启' }}火焰效果
       </button>
     </div>
 
+    <!-- 交互说明 -->
     <div class="control-section">
       <h4>交互说明</h4>
       <div class="info-item">
@@ -778,6 +925,7 @@ onUnmounted(() => {
       </div>
     </div>
 
+    <!-- 技术信息：展示使用的公共函数 -->
     <div class="tech-info">
       <strong>使用的公共函数：</strong>
       <div>useThreeScene()</div>
@@ -790,12 +938,21 @@ onUnmounted(() => {
 </template>
 
 <style scoped>
+/* ============================================
+   样式说明：
+   1. 物体信息标签：显示选中物体的详细信息
+   2. 设备详情弹窗：显示设备状态和告警信息
+   3. 控制面板：提供场景交互控制
+   4. 所有样式使用青色（#00FFFF）作为主题色
+============================================ */
+
+/* ============ 物体信息标签样式 ============ */
 .object-label {
-  position: absolute;
-  transform: translate(-50%, -100%);
-  pointer-events: none;
-  z-index: 100;
-  animation: fadeIn 0.3s ease-in-out;
+  position: absolute; /* 绝对定位，跟随物体 */
+  transform: translate(-50%, -100%); /* 居中对齐并向上偏移 */
+  pointer-events: none; /* 不响应鼠标事件，避免遮挡 */
+  z-index: 100; /* 确保在其他元素之上 */
+  animation: fadeIn 0.3s ease-in-out; /* 淡入动画 */
 }
 
 @keyframes fadeIn {
diff --git a/注释说明.md b/注释说明.md
new file mode 100644
index 0000000..fe48622
--- /dev/null
+++ b/注释说明.md
@@ -0,0 +1,175 @@
+# 12/index.vue 详细注释说明
+
+## 概述
+已为 `src/views/three/12/index.vue` 文件添加了详细的中文注释，涵盖了所有关键代码部分。
+
+## 注释内容分类
+
+### 1. 文件头部注释
+- 文件功能描述
+- 主要特性列表（8大功能点）
+- 作者信息和时间戳
+
+### 2. 导入和变量声明注释
+- **公共 Composables**：详细说明每个导入函数的用途
+  - `useThreeScene()` - 场景基础设置
+  - `useEnvironment()` - 环境相关功能
+  - `useParticleSystem()` - 粒子系统
+  - `usePostProcessing()` - 后期处理
+  - `useThreeLighting()` - 灯光系统
+
+- **状态变量**：按功能分类注释
+  - Three.js 核心对象（场景、相机、渲染器等）
+  - 粒子系统（蒸汽、火焰）
+  - 火焰蔓延相关变量
+  - 设备告警系统
+  - 物体选择与信息显示
+  - 射线检测
+
+### 3. 核心函数注释
+
+#### `init()` - 初始化函数
+- 分为多个逻辑块，每个块都有标题注释：
+  - 初始化公共工具函数
+  - 创建场景
+  - 创建环境背景
+  - 创建相机
+  - 创建渲染器
+  - 创建控制器
+  - 设置灯光系统
+  - 创建地板
+  - 设置后期处理
+  - 初始化射线检测
+  - 加载 3D 模型
+  - 事件监听
+  - 启动动画循环
+
+- 每个配置参数都有说明
+
+#### `loadModel()` - 模型加载函数
+- 遍历模型子对象的处理逻辑
+- 特定设备的识别和初始化
+- 蒸汽和火焰效果的创建
+
+#### `spreadFire()` - 火焰蔓延函数
+- 蔓延算法说明
+- 距离计算逻辑
+- 阈值判断说明
+- 中心大火触发条件
+
+#### `removeInitialFire()` - 移除初始火焰
+- 功能说明和调用时机
+
+#### `createCenterFire()` - 创建中心大火
+- 多层火焰效果的创建逻辑
+- 四周火焰柱的配置
+- 参数计算说明
+
+#### `animate()` - 动画循环函数
+- 各个系统的更新逻辑
+- 火焰蔓延时间控制
+- 告警闪烁效果计算
+- 标签位置更新
+
+#### `updateLabelPosition()` - 标签位置更新
+- 3D 到 2D 坐标转换
+- 屏幕像素坐标计算
+
+#### `onCanvasClick()` - 点击事件处理
+- 归一化设备坐标转换
+- 射线检测逻辑
+- 材质信息获取
+- 轮廓描边设置
+
+#### `showDeviceDialog()` - 显示设备弹窗
+- 弹窗内容配置
+
+#### `clearSelection()` - 清除选择
+- 状态重置
+
+#### `toggleAlert()` - 切换告警状态
+- 开启告警的视觉效果
+- 关闭告警的状态恢复
+
+#### `toggleParticles()` - 切换蒸汽效果
+- 粒子发射器控制
+
+#### `toggleFlame()` - 切换火焰效果
+- 火焰系统的完整启停逻辑
+- 状态重置和资源清理
+
+#### `closeDialog()` - 关闭弹窗
+
+#### `onResize()` - 窗口大小变化处理
+- 相机和渲染器尺寸更新
+
+#### 生命周期钩子
+- `onMounted` - 组件挂载时初始化
+- `onUnmounted` - 组件卸载时资源清理
+
+### 4. 模板部分注释
+- **Three.js 渲染容器**：说明用途
+- **物体信息标签**：
+  - 显示时机
+  - 位置动态跟随
+  - 内容结构（名称、材质、坐标）
+- **设备详情弹窗**：
+  - 触发条件
+  - 告警/正常状态展示
+  - 关闭逻辑
+- **控制面板**：
+  - 场景特性列表
+  - 设备控制按钮
+  - 交互说明
+  - 技术信息
+
+### 5. 样式部分注释
+- **文件级说明**：主题色和样式分类
+- **物体信息标签**：
+  - 定位和动画
+  - 内容样式
+- **弹窗**：
+  - 遮罩层和主体
+  - 告警状态特殊样式
+  - 动画效果
+- **控制面板**：
+  - 布局和定位
+  - 按钮样式和交互效果
+  - 自定义滚动条
+
+## 注释特点
+
+1. **结构清晰**：使用分隔线和标题组织注释
+2. **说明详细**：不仅说明"是什么"，还说明"为什么"
+3. **中文友好**：所有注释均使用中文
+4. **参数说明**：配置项都有注释解释
+5. **逻辑分组**：相关代码按功能分组并添加标题注释
+
+## 涉及的技术点
+
+1. **Three.js 核心**：场景、相机、渲染器、控制器
+2. **模型加载**：GLTFLoader
+3. **粒子系统**：蒸汽效果、火焰效果、火焰蔓延
+4. **后期处理**：轮廓描边（OutlinePass）
+5. **射线检测**：物体点击选择
+6. **材质系统**：发光效果（emissive）
+7. **动画系统**：requestAnimationFrame 循环
+8. **坐标转换**：3D 世界坐标到 2D 屏幕坐标
+9. **Vue 3**：Composition API、响应式状态、生命周期钩子
+10. **CSS 动画**：淡入、滑入、脉冲动画
+
+## 使用的公共 Composables
+
+1. `useThreeScene()` - 场景、相机、渲染器、控制器的创建
+2. `useEnvironment()` - 天空盒、地板、网格、流动光效
+3. `useThreeLighting()` - 多光源照明系统
+4. `usePostProcessing()` - 后期处理合成器和效果
+5. `useParticleSystem()` - 粒子发射器（蒸汽、火焰）
+
+## 文件统计
+
+- 总行数：约 1260 行
+- 注释覆盖：
+  - 脚本部分：每个函数和重要代码块都有注释
+  - 模板部分：每个主要组件都有说明
+  - 样式部分：添加了分类和关键样式说明