MianyVue/docs/功能点4-模型查看与3D交互.md

5.2.XX管理模块设计说明

5.2.1.XX设计说明。

5.2.1.1.模块描述。

本模块实现“模型查看-查看”能力，支持在轻量化工具箱业务场景中打开 3D 模型文件进行查看，并提供 3D 交互操作（旋转/缩放/选择）。

当前项目的查看能力由两条链路构成：

1. CAD 业务链路查看：通过侧边栏打开 CAD 模型后进入 ModelViewerPage（按 Creo/Revit/PDMS 切换对应查看组件）。
2. 通用 3D 文件查看：通过 ModelGalleryPage 打开/拖拽本地模型文件，使用 online-3d-viewer 渲染与交互。

“轻量化工具箱”场景说明：

1. 轻量化分析在 AnalysisToolsPage（含 Revit/PDMS 轻量化页）中执行。
2. 结果模型可回到模型查看链路（MODEL_VIEWER/MODEL_GALLERY）进行可视化检查。

·5.2.1.2.功能·。

1. 支持在查看页打开 3D 模型文件：
   • 点击“打开模型”按钮选择文件。
   • 支持拖拽文件到查看区域加载。
2. 支持 3D 基础交互：
   • 旋转：由 online-3d-viewer 内置交互控制提供。
   • 缩放：由 online-3d-viewer 内置交互控制提供。
   • 选择：通过鼠标点击拾取 mesh，并维护选中状态。
3. 支持模型树联动：
   • 模型加载后构建树结构。
   • 点击树节点可高亮并聚焦到对应 mesh（相机 Fit）。
4. 支持模型信息展示：
   • 文件名、顶点数、面数、网格数。
5. 支持多格式导入：
   • obj/stl/gltf/glb/ply/3ds/fbx/ifc/off/3dm。

5.2.1.3.性能。

1. 渲染与交互由 3D 引擎执行，前端业务层只做状态管理和事件转发。
2. 模型加载为异步流程，加载中使用遮罩，避免阻塞页面操作。
3. 仅在模型加载完成后统计网格信息并构建模型树，减少无效计算。
4. 拖拽态仅更新 isDragging，UI 高亮代价低。

5.2.1.4.输入输出项·。

1.字段输入输出。

输入字段：

1. File[]（本地文件选择或拖拽文件集）
2. supportedExtensions[]（允许加载的扩展名白名单）
3. 鼠标事件参数 button/mouseCoords
4. 树节点 mesh 标识：{ nodeId, meshIndex }

输出字段：

1. hasModel（是否已加载）
2. modelInfo（fileName/vertices/faces/meshes）
3. selectedMeshId（当前选中 mesh）
4. modelTree（树形结构数据）

2.界面交互输入输出。

输入交互：

1. 点击“打开模型”按钮。
2. 拖拽文件到查看区。
3. 鼠标在 3D 视图中旋转/缩放/点击。
4. 点击模型树节点。

输出交互：

1. 加载中遮罩、拖拽高亮。
2. 模型渲染显示与统计信息更新。
3. 选中状态更新（3D 点击与树点击双向联动）。
4. 聚焦目标部件（相机自动定位）。

5.2.1.5.算法

模型加载算法：

1. 收集用户输入文件（按钮或拖拽）。
2. 按扩展名白名单过滤有效文件。
3. 调用 viewer.LoadModelFromFileList(validFiles) 异步加载。
4. 加载完成回调中统计 mesh 数据并构建模型树。

选择算法：

1. 注册 SetMouseClickHandler(handleMeshClick)。
2. 左键点击时通过 GetMeshUserDataUnderMouse 拾取 mesh。
3. 提取 nodeId/meshIndex 写入 selectedMeshId。
4. 点击空白区域则清空选中。

树联动聚焦算法：

1. 树点击获得 meshId。
2. 使用 mesh 过滤条件计算包围球。
3. 调用 FitSphereToWindow 实现相机聚焦。

5.2.1.6.流程逻辑

1. 用户从导航进入模型查看链路（模型查看/模型库）。
2. 在查看页打开或拖拽模型文件。
3. 系统加载模型并建立树结构与统计信息。
4. 用户执行旋转/缩放/选择交互检查模型。
5. 在轻量化工具箱场景中，可将处理后的模型回到查看页进行可视化验证。

·5.2.1.7.接口。

页面路由/事件接口：

1. PAGE_TYPES.MODEL_VIEWER、PAGE_TYPES.MODEL_GALLERY
2. CadSidebar -> emit('show-model-viewer', modelData)
3. DashboardView.handleShowModelViewer(modelData) 切换到查看页

3D 查看接口（ModelGalleryPage）：

1. openModel()（文件选择）
2. handleDragOver/handleDragLeave/handleDrop（拖拽加载）
3. viewer.LoadModelFromFileList(files)（模型加载）
4. internalViewer.SetMouseClickHandler(handleMeshClick)（选择）
5. internalViewer.FitSphereToWindow(...)（聚焦）

5.2.1.8.注释设计

建议注释重点：

1. 标注“旋转/缩放由 3D 引擎内置交互提供”，避免误解为自研控制器。
2. 标注“选择功能为项目自定义拾取逻辑（mesh user data）”。
3. 标注“轻量化工具箱与查看模块的关系为前后处理链路，不是同一渲染实现”。
4. 对格式白名单与加载失败分支增加说明，便于扩展新格式。

5.2.1.9.数据结构。

选中 mesh 标识结构：

{
  "nodeId": 12,
  "meshIndex": 5
}

模型信息结构：

{
  "fileName": "sample.glb",
  "vertices": 125000,
  "faces": 240000,
  "meshes": 64
}

模型树节点结构（示意）：

{
  "name": "Root",
  "type": "node",
  "children": [
    { "name": "Part_A", "type": "mesh", "nodeId": 1, "meshIndex": 0 }
  ]
}