bim_engine/docs/引擎API对接.md

# Engine API 对接指南（2026-03）

本文档说明 SDK 层与底层 `iflow-engine-base` 的最新对接方式。

## 核心原则

1. `Engine` 组件是底层能力封装层（状态管理 + 参数转换 + 底层调用）
2. `EngineManager` 只保留少量对外公共 API，不再做全量透传
3. 内部 Manager 直接通过 `this.engineComponent` 调 `Engine`
4. 非 Manager 组件通过 `registry.engine3d?.getEngineComponent()` 调 `Engine`
5. 不暴露 raw engine 实例，事件订阅走 `onRawEvent/offRawEvent`

---

## 对接层级

```text
L1 UI 层（Button/Panel/Dialog）
  -> L2 Manager 层（业务编排）
  -> L3 Engine 组件（统一封装）
  -> L4 iflow-engine-base（底层能力）
```

---

## A. 对外 API（EngineManager）

对外稳定入口：`bimEngine.engine`

```ts
interface EngineManagerPublicApi {
  initialize(options?: Omit<EngineOptions, 'container'>): boolean;
  isInitialized(): boolean;
  loadModel(urls: string[], options?: ModelLoadOptions): void;
  pauseRendering(): void;
  resumeRendering(): void;
  getEngineComponent(): Engine | null;
  destroy(): void;
}
```

`EngineManager` 内部仍负责：

- 创建 `Engine` 实例
- 创建并持有 `RightKeyManager`
- 组装右键菜单逻辑

---

## B. 内部 Manager 对接（推荐）

`BaseManager` 已提供：

```ts
protected get engineComponent(): Engine | null;
```

### 示例：剖切盒

```ts
this.engineComponent?.activeSection('box');
this.engineComponent?.setSectionBoxRange(range);
this.engineComponent?.deactivateSection();
```

### 示例：漫游

```ts
this.engineComponent?.activateFirstPersonMode();
this.engineComponent?.setWalkSpeed(speed);
this.engineComponent?.deactivateFirstPersonMode();
```

---

## C. 非 Manager 组件对接

适用于 toolbar 按钮、独立组件（如 `WalkPathPanel`）：

```ts
registry.engine3d?.getEngineComponent()?.CameraGoHome();
registry.engine3d?.getEngineComponent()?.activateZoomBox();
registry.engine3d?.getEngineComponent()?.toggleMiniMap();
```

---

## D. 原始事件对接（替代 getEngine）

`Engine.getEngine()` 已删除，改为事件桥接：

```ts
engineComponent?.onRawEvent('measure-changed', handler);
engineComponent?.offRawEvent('measure-changed', handler);
```

适用场景：

- 测量回调（`measure-changed` / `measure-click`）
- 剖切盒拖动回调（`section-move`）

---

## E. 新功能对接步骤（最新模板）

### Step 1: 在 Engine 组件实现能力

文件：`src/components/engine/index.ts`

```ts
public activateXx(): void {
  if (!this._isInitialized || !this.engine?.xxModule) return;
  this.engine.xxModule.active();
}

public deactivateXx(): void {
  if (!this._isInitialized || !this.engine?.xxModule) return;
  this.engine.xxModule.disActive();
}
```

### Step 2: 在 Manager 中调用（不要新增 EngineManager 透传）

文件：`src/managers/xx-dialog-manager.ts`

```ts
protected onDialogCreated(): void {
  this.engineComponent?.activateXx();
}

protected onBeforeDestroy(): void {
  this.engineComponent?.deactivateXx();
}
```

### Step 3: 若是非 Manager 组件，走 getEngineComponent

```ts
registry.engine3d?.getEngineComponent()?.activateXx();
```

### Step 4: 仅当需要“对外 SDK 公共 API”时，再考虑给 EngineManager 增加方法

判定标准：

- 该能力是否需要 `bimEngine.engine?.xxx()` 供外部用户直接调用
- 若仅为内部链路使用，不应在 `EngineManager` 再包一层

---

## F. 常见反模式

- ❌ 在 `EngineManager` 里新增大批 `this.engineInstance?.xxx()` 透传
- ❌ 内部 Manager 继续写 `this.registry.engine3d?.xxx()`
- ❌ 通过 `Engine.getEngine()` 暴露 raw engine

对应正确方式：

- ✅ 内部 Manager 使用 `this.engineComponent?.xxx()`
- ✅ 非 Manager 使用 `registry.engine3d?.getEngineComponent()?.xxx()`
- ✅ 原始事件使用 `onRawEvent/offRawEvent`

---

---

## H. 设置系统对接

设置系统通过 `SettingDialogManager` 和 `Engine` 组件协作实现。

### H.1 架构

```text
SettingDialogManager (src/managers/setting-dialog-manager.ts)
  ├── UI 管理: 设置面板生命周期、预设列表展示
  ├── 预设管理: setPresetList() / applyPresetById()
  └── 设置应用: 调用 engineComponent.setSettings()

Engine 组件 (src/components/engine/index.ts)
  ├── getSettings(): 获取当前完整设置
  ├── setSettings(patch): 应用设置补丁
  └── 各类单项设置方法 (setRenderMode, setHDRBackgroundId, etc.)
```

### H.2 第三方注入预设

```typescript
// 初始化设置管理器
bimEngine.initSetting();

// 注入第三方预设
bimEngine.setting?.setPresetList([
  {
    id: 'vendor-preset',
    presetName: '供应商预设',
    isDefault: false,
    source: 'external',
    settings: {
      render: { mode: 'advanced', contrast: 60, ... },
      display: { showEdge: true, ... },
      environment: { type: 'hdr', hdrId: 'hdr-01', ... }
    }
  }
]);
```

### H.3 设置 API 调用链

```text
// 用户点击设置按钮
Toolbar Setting Button
  -> registry.setting.toggle()
  -> SettingDialogManager.show()
      -> createContent() 创建面板 UI
      -> 用户修改设置
      -> this.engineComponent?.setSettings(patch)
          -> Engine.setSettings()
              -> 调用底层引擎 setting 模块

// 用户切换预设
Preset Select Change
  -> SettingDialogManager.applyPresetById(id)
      -> 找到对应 preset
      -> this.engineComponent?.setSettings(preset.settings)
      -> emit('setting:preset-changed', { preset, timestamp })

// 用户保存预设
Save Preset Button
  -> 弹出命名输入框
  -> SettingDialogManager.saveAsPresetWithName(name)
      -> 组装 EngineSettingPreset
      -> emit('setting:preset-saved', { preset, currentSettings, timestamp })
```

### H.4 设置相关事件

```typescript
// 预设保存
bimEngine.on('setting:preset-saved', ({ preset, currentSettings, timestamp }) => {
  // 可持久化到 localStorage 或后端
});

// 预设切换
bimEngine.on('setting:preset-changed', ({ preset, timestamp }) => {
  // 可埋点上报
});

// 预设删除
bimEngine.on('setting:preset-deleted', (preset) => {
  // 清理存储
});
```

### H.5 详细文档

- [设置系统模块文档](MODULES/设置系统.md) - 完整 API 和接入指南

---

## G. 验收清单

重构或新增功能后，至少检查：

1. `EngineManager` 是否只保留必要公共 API
2. Manager 层是否统一走 `engineComponent`
3. 是否无 `getEngine()` 调用
4. 事件订阅是否成对 `onRawEvent/offRawEvent`
5. `npm run build` 是否通过