refactor: slim down EngineManager from 861 to 290 lines by removing passthrough proxy pattern

- EngineManager now only exposes public SDK API (initialize, loadModel, pause/resumeRendering, getEngineComponent, destroy)
- Internal managers access Engine component directly via this.engineComponent getter on BaseManager
- Non-manager components use registry.engine3d.getEngineComponent() for direct Engine access
- Replaced getEngine() with onRawEvent()/offRawEvent() for raw engine event access
- Migrated 62 call sites across 13 files (9 managers, 1 panel, 3 toolbar buttons)
- Updated all architecture docs, API docs, and README to reflect new patterns

src/components/button-group/toolbar/buttons/home/index.ts

@@ -12,7 +12,7 @@ export const createHomeButton = (registry: ManagerRegistry): ButtonConfig => {
         keepActive: false,
         onClick: (button) => {
             console.log('首页按钮被点击:', button.id);
-            registry.engine3d?.CameraGoHome();
+            registry.engine3d?.getEngineComponent()?.CameraGoHome();
         }
     };
 };

src/components/button-group/toolbar/buttons/map/index.ts

@@ -14,7 +14,7 @@ export const createMapButton = (registry: ManagerRegistry): ButtonConfig => {
         keepActive: true,
         icon: getIcon('地图'),
         onClick: () => {
-            registry.engine3d?.toggleMiniMap();
+            registry.engine3d?.getEngineComponent()?.toggleMiniMap();
         }
     };
 };

src/components/button-group/toolbar/buttons/zoom-box/index.ts

@@ -11,7 +11,7 @@ export const createZoomBoxButton = (registry: ManagerRegistry): ButtonConfig =>
         label: 'toolbar.zoomBox',
         icon: getIcon('框选放大'),
         onClick: () => {
-            registry.engine3d?.activateZoomBox();
+            registry.engine3d?.getEngineComponent()?.activateZoomBox();
         }
     };
 };

src/components/engine/index.ts

@@ -204,10 +204,22 @@ export class Engine implements IBimComponent {
     }
 
     /**
-     * 获取原始 3D 引擎实例
+     * 订阅原始引擎事件
+     * 用于需要访问底层引擎事件的场景（如测量回调、剖切移动等）
+     * @param event 事件名称
+     * @param handler 事件处理函数
      */
-    public getEngine(): any {
-        return this.engine;
+    public onRawEvent(event: string, handler: (...args: any[]) => void): void {
+        this.engine?.events?.on(event, handler);
+    }
+
+    /**
+     * 取消订阅原始引擎事件
+     * @param event 事件名称
+     * @param handler 事件处理函数
+     */
+    public offRawEvent(event: string, handler: (...args: any[]) => void): void {
+        this.engine?.events?.off(event, handler);
     }
 
     /**
@@ -612,6 +624,202 @@ export class Engine implements IBimComponent {
 
     // ==================== 结束：渲染模式 ====================
 
+    // ==================== 设置功能 ====================
+
+    // ---- 边线 ----
+
+    /** 启用模型边线显示 */
+    public activeModelEdge(): void {
+        if (!this._isInitialized || !this.engine?.modelEdge) {
+            console.warn('[Engine] Cannot active model edge: engine not initialized.');
+            return;
+        }
+        this.engine.modelEdge.active();
+    }
+
+    /** 关闭模型边线显示 */
+    public disActiveModelEdge(): void {
+        if (!this._isInitialized || !this.engine?.modelEdge) {
+            return;
+        }
+        this.engine.modelEdge.disActive();
+    }
+
+    /** 获取边线显示状态 */
+    public getModelEdgeActive(): boolean {
+        if (!this._isInitialized || !this.engine?.modelEdge) {
+            return false;
+        }
+        return this.engine.modelEdge.getActive?.() ?? false;
+    }
+
+    // ---- 光照强度 ----
+
+    /**
+     * 设置环境光照强度
+     * @param intensity 0-100
+     */
+    public setAmbientLightIntensity(intensity: number): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set ambient light intensity: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setAmbientLightIntensity(intensity);
+    }
+
+    /** 获取当前环境光照强度 */
+    public getAmbientLightIntensity(): number {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return 50;
+        }
+        return this.engine.setting.getAmbientLightIntensity?.() ?? 50;
+    }
+
+    // ---- 对比度 ----
+
+    /**
+     * 设置场景对比度
+     * @param contrast 0-100
+     */
+    public setSceneContrast(contrast: number): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set scene contrast: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setSceneContrast(contrast);
+    }
+
+    /** 获取当前场景对比度 */
+    public getSceneContrast(): number {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return 50;
+        }
+        return this.engine.setting.getSceneContrast?.() ?? 50;
+    }
+
+    // ---- 饾和度 ----
+
+    /**
+     * 设置场景饾和度
+     * @param saturation 0-100
+     */
+    public setSceneSaturation(saturation: number): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set scene saturation: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setSceneSaturation(saturation);
+    }
+
+    /** 获取当前场景饾和度 */
+    public getSceneSaturation(): number {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return 50;
+        }
+        return this.engine.setting.getSceneSaturation?.() ?? 50;
+    }
+
+    // ---- 环境背景 ----
+
+    /** 获取 HDR 背景列表 */
+    public getHDRBackgroundList(): { name: string; id: string }[] {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return [];
+        }
+        return this.engine.setting.getHDRBackground?.() ?? [];
+    }
+
+    /**
+     * 设置当前 HDR 背景
+     * @param id 背景 ID
+     */
+    public setHDRBackgroundId(id: string): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set HDR background: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setHDRBackgroundId(id);
+    }
+
+    /** 获取当前 HDR 背景 ID */
+    public getHDRBackgroundId(): string {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return '';
+        }
+        return this.engine.setting.getHDRBackgroundId?.() ?? '';
+    }
+
+    /**
+     * 设置 HDR 背景可见性
+     * @param visible 是否可见
+     */
+    public setHDRBackgroundVisibility(visible: boolean): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set HDR background visibility: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setHDRBackgroundVisibility(visible);
+    }
+
+    /** 获取 HDR 背景可见性 */
+    public getHDRBackgroundVisibility(): boolean {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return true;
+        }
+        return this.engine.setting.getHDRBackgroundVisibility?.() ?? true;
+    }
+
+    // ---- 地面 ----
+
+    /** 获取地面列表 */
+    public getGroundList(): { name: string; id: string }[] {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return [];
+        }
+        return this.engine.setting.getGroundList?.() ?? [];
+    }
+
+    /**
+     * 设置当前地面类型
+     * @param id 地面 ID
+     */
+    public setGroundId(id: string): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set ground: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setGroundId(id);
+    }
+
+    /** 获取当前地面 ID */
+    public getGroundId(): string {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return '';
+        }
+        return this.engine.setting.getGroundId?.() ?? '';
+    }
+
+    /**
+     * 设置地面高度（单位：m）
+     * @param elevation 地面高度值
+     */
+    public setGroundElevation(elevation: number): void {
+        if (!this._isInitialized || !this.engine?.setting) {
+            console.warn('[Engine] Cannot set ground elevation: engine not initialized.');
+            return;
+        }
+        this.engine.setting.setGroundElevation(elevation);
+    }
+
+    /** 获取当前地面高度（单位：m） */
+    public getGroundElevation(): number {
+        if (!this._isInitialized || !this.engine?.setting) {
+            return 0;
+        }
+        return this.engine.setting.getGroundElevation?.() ?? 0;
+    }
+
+    // ==================== 结束：设置功能 ====================
     // ==================== 漫游功能 ====================
 
     /** 漫游模式是否激活 */

src/components/walk-path-panel/index.ts

@@ -66,7 +66,7 @@ export class WalkPathPanel implements IBimComponent {
      * 在面板打开时调用，获取底层引擎中已存在的漫游点
      */
     private loadPointsFromEngine(): void {
-        const enginePoints = this.registry.engine3d?.pathRoamingGetPoints() ?? [];
+        const enginePoints = this.registry.engine3d?.getEngineComponent()?.pathRoamingGetPoints() ?? [];
         // 将引擎返回的点转换为本地格式
         this.points = enginePoints.map((_: any, index: number) => ({
             index: index
@@ -288,7 +288,7 @@ export class WalkPathPanel implements IBimComponent {
      */
     private addPoint(): void {
         // 调用引擎添加漫游点
-        this.registry.engine3d?.pathRoamingAddPoint();
+        this.registry.engine3d?.getEngineComponent()?.pathRoamingAddPoint();
         // 更新本地状态
         const newIndex = this.points.length;
         this.points.push({ index: newIndex });
@@ -302,7 +302,7 @@ export class WalkPathPanel implements IBimComponent {
      */
     private deletePoint(index: number): void {
         // 调用引擎删除漫游点
-        this.registry.engine3d?.pathRoamingRemovePoint(index);
+        this.registry.engine3d?.getEngineComponent()?.pathRoamingRemovePoint(index);
         // 从本地列表中移除
         this.points.splice(index, 1);
         // 重新索引
@@ -316,7 +316,7 @@ export class WalkPathPanel implements IBimComponent {
      */
     private deleteAllPoints(): void {
         // 调用引擎清除所有漫游点
-        this.registry.engine3d?.pathRoamingClearPoints();
+        this.registry.engine3d?.getEngineComponent()?.pathRoamingClearPoints();
         // 清空本地列表
         this.points = [];
         // 重新渲染
@@ -328,7 +328,7 @@ export class WalkPathPanel implements IBimComponent {
      * @param index 目标漫游点索引
      */
     private jumpToPoint(index: number): void {
-        this.registry.engine3d?.pathRoamingJumpToPoint(index);
+        this.registry.engine3d?.getEngineComponent()?.pathRoamingJumpToPoint(index);
     }
 
     /**
@@ -343,7 +343,7 @@ export class WalkPathPanel implements IBimComponent {
 
         console.log('[WalkPathPanel] 开始播放漫游', { duration: this.duration, loop: this.loop, pointsCount: this.points.length });
 
-        this.registry.engine3d?.pathRoamingPlay({
+        this.registry.engine3d?.getEngineComponent()?.pathRoamingPlay({
             duration: this.duration,
             loop: this.loop,
             onPointComplete: (pointIndex: number) => {
@@ -365,7 +365,7 @@ export class WalkPathPanel implements IBimComponent {
      */
     private stopPath(): void {
         console.log('[WalkPathPanel] 停止漫游');
-        this.registry.engine3d?.pathRoamingStop();
+        this.registry.engine3d?.getEngineComponent()?.pathRoamingStop();
         this.isPlaying = false;
         this.playingPointIndex = -1;
         this.render();