# 右键菜单功能对接

## TL;DR

> **Quick Summary**: 对接右键菜单的构件操作功能，包括隐藏、半透明、隔离、显示全部，以及新增"快速选择"子菜单。
> 
> **Deliverables**:
> - 国际化文件更新（types.ts, zh-CN.ts, en-US.ts）
> - Engine 层新增 8 个方法
> - EngineManager 层新增 8 个代理方法
> - 右键菜单 handler 实现功能调用
> 
> **Estimated Effort**: Short (约 30 分钟)
> **Parallel Execution**: NO - sequential
> **Critical Path**: Task 1 → Task 2 → Task 3 → Task 4

---

## Context

### Original Request
对接右键菜单的以下功能：
1. 隐藏选中构件：`engine.modelToolModule.hideModel(engine.engineStatus.highlightModels)`
2. 半透明选中构件：`engine.modelToolModule.translucentModel(engine.engineStatus.highlightModels)`
3. 隔离/隐藏其他构件：`engine.modelToolModule.isolateModel(engine.engineStatus.highlightModels)`
4. 隔离/半透明其他构件：`engine.modelToolModule.translucentOtherModel(engine.engineStatus.highlightModels)`
5. 显示所有模型：`engine.modelToolModule.showAllModels()`

新增快速选择子菜单：
6. 选择同类模型：`engine.modelToolModule.batchSelectSameTypeModel(engine.engineStatus.highlightModels)`
7. 选择同层模型：`engine.modelToolModule.batchSelectSameLevelModel(engine.engineStatus.highlightModels)`
8. 选择同层同类模型：`engine.modelToolModule.batchSelectSameLevelTypeModel(engine.engineStatus.highlightModels)`

### 底层 API 模式
```typescript
// 获取选中构件
const models = engine.engineStatus.highlightModels;

// 调用 modelToolModule 方法
engine.modelToolModule.hideModel(models);
engine.modelToolModule.translucentModel(models);
engine.modelToolModule.isolateModel(models);
engine.modelToolModule.translucentOtherModel(models);
engine.modelToolModule.showAllModels();
engine.modelToolModule.batchSelectSameTypeModel(models);
engine.modelToolModule.batchSelectSameLevelModel(models);
engine.modelToolModule.batchSelectSameLevelTypeModel(models);
```

---

## Work Objectives

### Core Objective
将底层引擎的构件操作 API 对接到右键菜单，实现完整的构件隐藏、半透明、隔离和快速选择功能。

### Concrete Deliverables
- `src/locales/types.ts` - 添加 4 个新字段
- `src/locales/zh-CN.ts` - 添加中文翻译
- `src/locales/en-US.ts` - 添加英文翻译
- `src/components/engine/index.ts` - 添加 8 个方法
- `src/managers/engine-manager.ts` - 添加 8 个代理方法 + 更新右键菜单 handler

### Definition of Done
- [x] 右键选中构件时，所有菜单功能可正常调用
- [x] 快速选择子菜单正确显示三个选项
- [x] 构建成功：`npm run build`

### Must Have
- 所有 8 个底层 API 都要对接
- 国际化支持中英文
- 保持现有代码风格

### Must NOT Have (Guardrails)
- 不要修改底层引擎 API
- 不要添加额外的 UI 组件
- 不要修改菜单的显示逻辑

---

## Verification Strategy

### Test Decision
- **Infrastructure exists**: NO
- **User wants tests**: Manual-only
- **QA approach**: Manual verification

---

## TODOs

- [x] 1. 更新国际化文件

  **What to do**:
  1. 在 `src/locales/types.ts` 的 `menu` 对象中添加：
     ```typescript
     quickSelect: string;
     selectSameType: string;
     selectSameLevel: string;
     selectSameLevelType: string;
     ```
  2. 在 `src/locales/zh-CN.ts` 的 `menu` 对象中添加：
     ```typescript
     quickSelect: '快速选择',
     selectSameType: '选择同类模型',
     selectSameLevel: '选择同层模型',
     selectSameLevelType: '选择同层同类模型'
     ```
  3. 在 `src/locales/en-US.ts` 的 `menu` 对象中添加：
     ```typescript
     quickSelect: 'Quick Select',
     selectSameType: 'Select Same Type',
     selectSameLevel: 'Select Same Level',
     selectSameLevelType: 'Select Same Level & Type'
     ```

  **Must NOT do**:
  - 不要修改其他现有字段

  **Recommended Agent Profile**:
  - **Category**: `quick`
  - **Skills**: [`coding-standards`]

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Parallel Group**: Sequential
  - **Blocks**: Task 2, 3, 4
  - **Blocked By**: None

  **References**:
  - `src/locales/types.ts:53-64` - 现有 menu 类型定义
  - `src/locales/zh-CN.ts:34-45` - 现有中文翻译
  - `src/locales/en-US.ts:34-45` - 现有英文翻译

  **Acceptance Criteria**:
  - [ ] TypeScript 无类型错误
  - [ ] 三个文件都已更新

  **Commit**: NO (与 Task 2-4 一起提交)

---

- [x] 2. Engine 层添加构件操作方法

  **What to do**:
  在 `src/components/engine/index.ts` 中添加以下 8 个公共方法（在路径漫游区域之后、destroy 之前）：

  ```typescript
  // ==================== 构件操作 ====================

  /**
   * 隐藏选中构件
   */
  public hideSelectedModels(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot hide models: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.hideModel(models);
      }
  }

  /**
   * 半透明选中构件
   */
  public translucentSelectedModels(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot translucent models: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.translucentModel(models);
      }
  }

  /**
   * 隔离选中构件（隐藏其他）
   */
  public isolateSelectedModels(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot isolate models: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.isolateModel(models);
      }
  }

  /**
   * 半透明其他构件
   */
  public translucentOtherModels(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot translucent other models: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.translucentOtherModel(models);
      }
  }

  /**
   * 显示所有模型
   */
  public showAllModels(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot show all models: engine not initialized.');
          return;
      }
      this.engine.modelToolModule.showAllModels();
  }

  /**
   * 批量选择同类模型
   */
  public batchSelectSameTypeModel(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot batch select: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.batchSelectSameTypeModel(models);
      }
  }

  /**
   * 批量选择同层模型
   */
  public batchSelectSameLevelModel(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot batch select: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.batchSelectSameLevelModel(models);
      }
  }

  /**
   * 批量选择同层同类模型
   */
  public batchSelectSameLevelTypeModel(): void {
      if (!this._isInitialized || !this.engine?.modelToolModule) {
          console.warn('[Engine] Cannot batch select: engine not initialized.');
          return;
      }
      const models = this.engine.engineStatus?.highlightModels;
      if (models) {
          this.engine.modelToolModule.batchSelectSameLevelTypeModel(models);
      }
  }

  // ==================== 结束：构件操作 ====================
  ```

  **Must NOT do**:
  - 不要修改现有方法
  - 不要修改 `fitSectionBoxToModel` 方法

  **Recommended Agent Profile**:
  - **Category**: `quick`
  - **Skills**: [`coding-standards`]

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Parallel Group**: Sequential
  - **Blocks**: Task 3
  - **Blocked By**: Task 1

  **References**:
  - `src/components/engine/index.ts:496-506` - `fitSectionBoxToModel` 参考模式（使用 highlightModels）
  - `src/components/engine/index.ts:431-491` - 路径漫游方法区域（在此之后添加）

  **Acceptance Criteria**:
  - [ ] 8 个方法都已添加
  - [ ] 方法有 JSDoc 注释
  - [ ] 使用项目规范的区域注释标记

  **Commit**: NO (与其他 Task 一起提交)

---

- [x] 3. EngineManager 添加代理方法

  **What to do**:
  在 `src/managers/engine-manager.ts` 中添加 8 个代理方法（在路径漫游区域之后、destroy 之前）：

  ```typescript
  // ==================== 构件操作 ====================

  /**
   * 隐藏选中构件
   */
  public hideSelectedModels(): void {
      this.engineInstance?.hideSelectedModels();
  }

  /**
   * 半透明选中构件
   */
  public translucentSelectedModels(): void {
      this.engineInstance?.translucentSelectedModels();
  }

  /**
   * 隔离选中构件（隐藏其他）
   */
  public isolateSelectedModels(): void {
      this.engineInstance?.isolateSelectedModels();
  }

  /**
   * 半透明其他构件
   */
  public translucentOtherModels(): void {
      this.engineInstance?.translucentOtherModels();
  }

  /**
   * 显示所有模型
   */
  public showAllModels(): void {
      this.engineInstance?.showAllModels();
  }

  /**
   * 批量选择同类模型
   */
  public batchSelectSameTypeModel(): void {
      this.engineInstance?.batchSelectSameTypeModel();
  }

  /**
   * 批量选择同层模型
   */
  public batchSelectSameLevelModel(): void {
      this.engineInstance?.batchSelectSameLevelModel();
  }

  /**
   * 批量选择同层同类模型
   */
  public batchSelectSameLevelTypeModel(): void {
      this.engineInstance?.batchSelectSameLevelTypeModel();
  }

  // ==================== 结束：构件操作 ====================
  ```

  **Must NOT do**:
  - 不要修改现有方法

  **Recommended Agent Profile**:
  - **Category**: `quick`
  - **Skills**: [`coding-standards`]

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Parallel Group**: Sequential
  - **Blocks**: Task 4
  - **Blocked By**: Task 2

  **References**:
  - `src/managers/engine-manager.ts:431-492` - 路径漫游代理方法区域

  **Acceptance Criteria**:
  - [ ] 8 个代理方法都已添加
  - [ ] 方法有 JSDoc 注释

  **Commit**: NO (与其他 Task 一起提交)

---

- [x] 4. 更新右键菜单 Handler

  **What to do**:
  在 `src/managers/engine-manager.ts` 的 `registerHandler` 回调中：

  1. **替换隐藏选中构件的 onClick**（约第 78-81 行）：
     ```typescript
     onClick: () => {
         this.hideSelectedModels();
         this.rightKey?.hide();
     }
     ```

  2. **替换半透明选中构件的 onClick**（约第 90-93 行）：
     ```typescript
     onClick: () => {
         this.translucentSelectedModels();
         this.rightKey?.hide();
     }
     ```

  3. **替换隔离-隐藏其他的 onClick**（约第 107-110 行）：
     ```typescript
     onClick: () => {
         this.isolateSelectedModels();
         this.rightKey?.hide();
     }
     ```

  4. **替换隔离-半透明其他的 onClick**（约第 114-117 行）：
     ```typescript
     onClick: () => {
         this.translucentOtherModels();
         this.rightKey?.hide();
     }
     ```

  5. **替换显示全部的 onClick**（约第 142-144 行）：
     ```typescript
     onClick: () => {
         this.showAllModels();
         this.rightKey?.hide();
     }
     ```

  6. **在隔离选中构件菜单项之后（order: 4 之后），添加快速选择子菜单**（order: 5，将剖切盒适应改为 order: 6，显示全部改为 order: 7）：
     ```typescript
     // 5. 快速选择（带子菜单）
     items.push({
         id: 'quickSelect',
         label: 'menu.quickSelect',
         group: 'component',
         order: 5,
         children: [
             {
                 id: 'selectSameType',
                 label: 'menu.selectSameType',
                 onClick: () => {
                     this.batchSelectSameTypeModel();
                     this.rightKey?.hide();
                 }
             },
             {
                 id: 'selectSameLevel',
                 label: 'menu.selectSameLevel',
                 onClick: () => {
                     this.batchSelectSameLevelModel();
                     this.rightKey?.hide();
                 }
             },
             {
                 id: 'selectSameLevelType',
                 label: 'menu.selectSameLevelType',
                 onClick: () => {
                     this.batchSelectSameLevelTypeModel();
                     this.rightKey?.hide();
                 }
             }
         ]
     });
     ```

  7. **更新剖切盒适应的 order 为 6**

  8. **更新显示全部的 order 为 7**

  **Must NOT do**:
  - 不要修改菜单项的 id 和 label（除了新增的）
  - 不要修改 group 分组逻辑

  **Recommended Agent Profile**:
  - **Category**: `quick`
  - **Skills**: [`coding-standards`]

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Parallel Group**: Sequential (final task)
  - **Blocks**: None
  - **Blocked By**: Task 3

  **References**:
  - `src/managers/engine-manager.ts:53-149` - 现有右键菜单 handler
  - `src/managers/engine-manager.ts:96-121` - 隔离子菜单结构参考

  **Acceptance Criteria**:
  - [ ] 所有 console.log 占位符已替换为实际方法调用
  - [ ] 快速选择子菜单正确添加
  - [ ] 菜单项 order 正确排序

  **Commit**: YES
  - Message: `feat(menu): implement right-click menu functions for model operations`
  - Files: 
    - `src/locales/types.ts`
    - `src/locales/zh-CN.ts`
    - `src/locales/en-US.ts`
    - `src/components/engine/index.ts`
    - `src/managers/engine-manager.ts`
  - Pre-commit: `npm run build`

---

- [x] 5. 构建验证

  **What to do**:
  - 运行 `npm run build` 确保构建成功

  **Recommended Agent Profile**:
  - **Category**: `quick`
  - **Skills**: []

  **Parallelization**:
  - **Can Run In Parallel**: NO
  - **Blocks**: None
  - **Blocked By**: Task 4

  **Acceptance Criteria**:
  ```bash
  npm run build
  # 预期: 构建成功，无错误
  ```

  **Commit**: NO

---

## Commit Strategy

| After Task | Message | Files | Verification |
|------------|---------|-------|--------------|
| 4 | `feat(menu): implement right-click menu functions for model operations` | types.ts, zh-CN.ts, en-US.ts, engine/index.ts, engine-manager.ts | npm run build |

---

## Success Criteria

### Verification Commands
```bash
npm run build  # Expected: Build successful
```

### Final Checklist
- [x] 国际化文件已更新（3 个文件）
- [x] Engine 层添加 8 个方法
- [x] EngineManager 层添加 8 个代理方法
- [x] 右键菜单 handler 已更新
- [x] 快速选择子菜单已添加
- [x] 构建成功