bim_engine/docs/MODULES/管理器模块.md

# Managers 模块文档

## 模块概述

`src/managers/` 负责业务编排与生命周期管理，不直接承载底层 3D 细节。

2026-03 更新后，管理器层的核心变化：

- `EngineManager` 从“全量透传”改为“对外公共 API + 初始化编排”
- `BaseManager` 新增 `engineComponent` getter，内部管理器直接调用 `Engine` 组件
- Manager 层统一收敛为“编排者”，而不是“透传中间层”

---

## 代码地图

```text
src/managers/
├── engine-manager.ts
├── toolbar-manager.ts
├── dialog-manager.ts
├── button-group-manager.ts
├── right-key-manager.ts
├── component-detail-manager.ts
├── construct-tree-manager-btn.ts
├── walk-control-manager.ts
├── measure-dialog-manager.ts
├── section-plane-dialog-manager.ts
├── section-axis-dialog-manager.ts
├── section-box-dialog-manager.ts
├── map-dialog-manager.ts
├── walk-path-dialog-manager.ts
├── walk-plan-view-dialog-manager.ts
├── setting-dialog-manager.ts
├── engine-info-dialog-manager.ts
└── ai-chat-manager.ts
```

---

## 继承关系

```text
BaseManager
├── EngineManager
├── ToolbarManager
├── DialogManager
├── ButtonGroupManager
├── RightKeyManager
├── ComponentDetailManager
├── ConstructTreeManagerBtn
├── WalkControlManager
├── SettingDialogManager
├── EngineInfoDialogManager
└── AiChatManager

BaseDialogManager (extends BaseManager)
├── MeasureDialogManager
├── SectionPlaneDialogManager
├── SectionAxisDialogManager
├── SectionBoxDialogManager
├── MapDialogManager
├── WalkPathDialogManager
└── WalkPlanViewDialogManager
```

---

## BaseManager 统一能力

文件：`src/core/base-manager.ts`

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

用途：

- 内部 manager 直接调用 `Engine` 组件能力
- 替代历史写法 `this.registry.engine3d?.xxx()`

示例：

```ts
this.engineComponent?.activeSection('box');
this.engineComponent?.setWalkSpeed(speed);
```

---

## EngineManager（最新职责）

文件：`src/managers/engine-manager.ts`

### 职责

1. 创建/销毁 `Engine` 组件
2. 创建/销毁 `RightKeyManager`
3. 组装右键菜单逻辑
4. 暴露外部公共 API

### 公共 API

```ts
class EngineManager extends BaseManager {
  rightKey: RightKeyManager | null;

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

说明：

- 不再提供 `activateMeasure()/activeSection()/setWalkSpeed()` 等透传 API
- 这些能力由内部 manager 直接调用 `engineComponent`

---

## 各管理器职责分层

| 类别 | 代表 Manager | 主要职责 |
|---|---|---|
| 核心入口 | `EngineManager` | 引擎生命周期与外部 API |
| UI 容器 | `ToolbarManager`, `DialogManager`, `ButtonGroupManager` | UI 容器与通用交互 |
| 业务编排 | `MeasureDialogManager`, `Section*DialogManager`, `WalkControlManager`, `SettingDialogManager` | 对话框/面板回调与引擎能力编排 |
| 数据/交互 | `ConstructTreeManagerBtn`, `ComponentDetailManager`, `RightKeyManager` | 构件树、属性、右键菜单 |

---

## 推荐调用方式

### Manager 内部

```ts
// 推荐
this.engineComponent?.setSectionBoxRange(range);

// 不推荐
this.registry.engine3d?.setSectionBoxRange(range);
```

### 非 Manager 组件

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

---

## 迁移约束（团队规范）

新增功能时遵循：

1. 先在 `Engine` 组件实现能力
2. 内部 manager 通过 `engineComponent` 访问
3. 仅当确有外部 SDK 需求时，才新增 `EngineManager` 公共方法
4. 不新增大规模透传方法