bim_engine/.sisyphus/plans/refactor-model-operations.md

# 重构构件操作方法 - 参数化设计

## TL;DR

> **Quick Summary**: 重构 Engine 组件的构件操作方法，将内部获取 highlightModels 改为接受参数传入，并新增 getHighlightModels() 方法。
> 
> **Deliverables**:
> - Engine 层：新增 1 个方法 + 修改 7 个方法签名
> - EngineManager 层：新增 1 个方法 + 修改 7 个代理方法
> - 右键菜单：更新 7 处调用方式
> 
> **Estimated Effort**: Short (~20 分钟)
> **Parallel Execution**: NO - sequential

---

## Context

### 当前实现问题

当前 7 个方法内部获取 `highlightModels`：
```typescript
public hideSelectedModels(): void {
    const models = this.engine.engineStatus?.highlightModels;
    if (models) {
        this.engine.modelToolModule.hideModel(models);
    }
}
```

### 目标设计

分离获取和操作，提高 API 灵活性：
```typescript
// 新增获取方法
public getHighlightModels(): any { ... }

// 操作方法接受参数
public hideModels(models: any): void { ... }

// 调用方式
const models = engine.getHighlightModels();
if (models) engine.hideModels(models);
```

---

## 方法重命名映射

| 原方法名 | 新方法名 | 参数 |
|----------|----------|------|
| `hideSelectedModels()` | `hideModels(models)` | `models: any` |
| `translucentSelectedModels()` | `translucentModels(models)` | `models: any` |
| `isolateSelectedModels()` | `isolateModels(models)` | `models: any` |
| `translucentOtherModels()` | `translucentOtherModels(models)` | `models: any` |
| `batchSelectSameTypeModel()` | `batchSelectSameTypeModel(models)` | `models: any` |
| `batchSelectSameLevelModel()` | `batchSelectSameLevelModel(models)` | `models: any` |
| `batchSelectSameLevelTypeModel()` | `batchSelectSameLevelTypeModel(models)` | `models: any` |
| (新增) | `getHighlightModels()` | 无参数，返回 `any` |

---

## TODOs

- [x] 1. Engine 层 - 新增 getHighlightModels 方法

  **What to do**:
  在 `src/components/engine/index.ts` 的构件操作区域开头添加：
  
  ```typescript
  /**
   * 获取当前高亮（选中）的模型
   * @returns 高亮模型对象，未选中时返回 null
   */
  public getHighlightModels(): any {
      if (!this._isInitialized || !this.engine) {
          return null;
      }
      return this.engine.engineStatus?.highlightModels ?? null;
  }
  ```

  **位置**: 在 `// ==================== 构件操作 ====================` 之后，`hideSelectedModels` 之前

---

- [x] 2. Engine 层 - 重构 hideSelectedModels

  **What to do**:
  修改 `hideSelectedModels` 为 `hideModels`：
  
  ```typescript
  /**
   * 隐藏指定模型
   * @param models 要隐藏的模型对象
   */
  public hideModels(models: any): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot hide models: engine not initialized.');
          return;
      }
      if (models) {
          this.engine.modelToolModule.hideModel(models);
      }
  }
  ```

---

- [x] 3. Engine 层 - 重构 translucentSelectedModels

  **What to do**:
  修改为 `translucentModels(models: any)`，移除内部获取逻辑。

---

- [x] 4. Engine 层 - 重构 isolateSelectedModels

  **What to do**:
  修改为 `isolateModels(models: any)`，移除内部获取逻辑。

---

- [x] 5. Engine 层 - 重构 translucentOtherModels

  **What to do**:
  添加 `models: any` 参数，移除内部获取逻辑。

---

- [x] 6. Engine 层 - 重构 batch 系列方法

  **What to do**:
  为以下 3 个方法添加 `models: any` 参数：
  - `batchSelectSameTypeModel(models: any)`
  - `batchSelectSameLevelModel(models: any)`
  - `batchSelectSameLevelTypeModel(models: any)`

---

- [x] 7. EngineManager 层 - 新增 getHighlightModels 代理

  **What to do**:
  在 `src/managers/engine-manager.ts` 添加：
  
  ```typescript
  /**
   * 获取当前高亮（选中）的模型
   * @returns 高亮模型对象，未选中时返回 null
   */
  public getHighlightModels(): any {
      return this.engineInstance?.getHighlightModels() ?? null;
  }
  ```

---

- [x] 8. EngineManager 层 - 更新 7 个代理方法签名

  **What to do**:
  更新以下方法签名以接受 `models` 参数：
  - `hideModels(models: any)`
  - `translucentModels(models: any)`
  - `isolateModels(models: any)`
  - `translucentOtherModels(models: any)`
  - `batchSelectSameTypeModel(models: any)`
  - `batchSelectSameLevelModel(models: any)`
  - `batchSelectSameLevelTypeModel(models: any)`

---

- [x] 9. 右键菜单 - 更新调用方式

  **What to do**:
  更新 `registerHandler` 中的 7 处调用，从：
  ```typescript
  onClick: () => {
      this.hideSelectedModels();
      this.rightKey?.hide();
  }
  ```
  
  改为：
  ```typescript
  onClick: () => {
      const models = this.getHighlightModels();
      if (models) {
          this.hideModels(models);
      }
      this.rightKey?.hide();
  }
  ```
  
  需要更新的菜单项：
  1. hideSelected → hideModels
  2. transparentSelected → translucentModels
  3. hideOthers → isolateModels
  4. transparentOthers → translucentOtherModels
  5. selectSameType → batchSelectSameTypeModel
  6. selectSameLevel → batchSelectSameLevelModel
  7. selectSameLevelType → batchSelectSameLevelTypeModel

---

- [x] 10. 构建验证 + 提交

  **Commit Message**: 
  ```
  refactor(engine): parameterize model operation methods
  
  - Add getHighlightModels() to retrieve selected models
  - Rename hideSelectedModels → hideModels(models)
  - Rename translucentSelectedModels → translucentModels(models)
  - Rename isolateSelectedModels → isolateModels(models)
  - Update translucentOtherModels to accept models parameter
  - Update batch select methods to accept models parameter
  - Update right-click menu to use new API pattern
  ```

---

## Success Criteria

- [x] 构建成功：`npm run build`
- [x] 新增 `getHighlightModels()` 方法
- [x] 7 个方法都接受 `models` 参数
- [x] 右键菜单正常工作