# 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 }
  ]
}
```
