feat(registry): 注册 ComponentDetailManager 到全局 Registry 和 BimEngine
This commit is contained in:
yuding
773
.sisyphus/plans/component-detail-rightclick.md
Normal file
773
.sisyphus/plans/component-detail-rightclick.md
Normal file
@@ -0,0 +1,773 @@
|
||||
# 构件详情右键菜单功能
|
||||
|
||||
## TL;DR
|
||||
|
||||
> **Quick Summary**: 实现右键菜单显示构件详情功能。用户选择构件后右键显示"构件详情"和"显示全部"菜单，点击构件详情弹出属性弹窗。
|
||||
>
|
||||
> **Deliverables**:
|
||||
> - Engine 组件监听构件点击事件，记录选中构件信息
|
||||
> - 修改右键菜单根据选中状态动态显示菜单项
|
||||
> - 创建构件详情弹窗，调用底层 API 展示属性数据
|
||||
>
|
||||
> **Estimated Effort**: Medium
|
||||
> **Parallel Execution**: NO - 顺序依赖
|
||||
> **Critical Path**: Task 1 → Task 2 → Task 3 → Task 4 → Task 5 → Task 6
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
### Original Request
|
||||
用户选择构件后，右键显示"构件详情"按钮（有选中时）或"显示全部"按钮（无选中时）。点击构件详情查询数据并弹窗展示。
|
||||
|
||||
### 底层 API 验证结果
|
||||
|
||||
#### 1. 构件属性查询 API ✅ 已验证
|
||||
**文件**: `bim_engine_base/src/core/v2/managers/modelProperties/index.ts`
|
||||
**实例化**: `EngineKernelV2.modelProperties`
|
||||
|
||||
```typescript
|
||||
// 调用方式
|
||||
engine.modelProperties.getModelProperties(url: string, id: string, callback: (data) => void)
|
||||
|
||||
// 返回格式
|
||||
{
|
||||
properties: [{
|
||||
name: string, // 分类名称
|
||||
children: [{
|
||||
name: string, // 属性名
|
||||
value: any // 属性值
|
||||
}]
|
||||
}],
|
||||
materials: []
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. 构件点击事件 ✅ 已验证
|
||||
**文件**: `bim_engine_base/src/core/v2/modules/interactionModule.ts`
|
||||
|
||||
```typescript
|
||||
// 点击时触发
|
||||
handleMouseClick(event) {
|
||||
const hit = event.catch;
|
||||
const model = hit.object;
|
||||
// model.url → 模型URL
|
||||
// model.name → 构件ID
|
||||
engine.events.trigger(EventType.Click, hit);
|
||||
}
|
||||
```
|
||||
|
||||
**EventType.Click** 数据结构:
|
||||
```typescript
|
||||
{
|
||||
point: Vector3, // 点击位置
|
||||
object: {
|
||||
url: string, // 模型URL
|
||||
name: string // 构件ID
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 3. 右键菜单 API ✅ 已验证
|
||||
**文件**: `engine/src/managers/right-key-manager.ts`
|
||||
|
||||
```typescript
|
||||
// 注册处理器
|
||||
rightKey.registerHandler((e: MouseEvent) => MenuItemConfig[] | null)
|
||||
|
||||
// MenuItemConfig
|
||||
interface MenuItemConfig {
|
||||
id: string;
|
||||
label: string;
|
||||
onClick?: () => void;
|
||||
icon?: string;
|
||||
group?: string;
|
||||
disabled?: boolean;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Work Objectives
|
||||
|
||||
### Core Objective
|
||||
实现构件详情右键菜单功能，包括：选中状态追踪、动态菜单、属性弹窗展示。
|
||||
|
||||
### Concrete Deliverables
|
||||
- `engine/src/components/engine/index.ts` - 新增选中状态管理和事件监听
|
||||
- `engine/src/managers/engine-manager.ts` - 暴露选中状态和属性查询方法，修改右键处理器
|
||||
- `engine/src/managers/component-detail-manager.ts` - 新建构件详情弹窗管理器
|
||||
- `engine/src/bim-engine.ts` - 注册新管理器
|
||||
- `engine/src/locales/*.ts` - 新增国际化文本
|
||||
- `.sisyphus/drafts/API_CALLCHAIN.md` - 重构调用链文档（从 Toolbar 专用扩展为全局文档）
|
||||
|
||||
### Definition of Done
|
||||
- [ ] `bun run build` 构建成功
|
||||
- [ ] 点击构件后，右键显示"构件详情"和"显示全部"
|
||||
- [ ] 未选中构件时，右键只显示"显示全部"
|
||||
- [ ] 点击"构件详情"弹出属性弹窗，展示底层 API 返回的数据
|
||||
- [ ] 点击"显示全部"控制台输出提示
|
||||
- [ ] 调用链文档已重构并更新
|
||||
|
||||
### Must Have
|
||||
- 监听底层 Click 事件获取选中构件
|
||||
- 根据选中状态动态返回菜单项
|
||||
- 调用 `modelProperties.getModelProperties()` 获取属性
|
||||
- 使用现有 Dialog + Collapse + Description 组件展示
|
||||
|
||||
### Must NOT Have (Guardrails)
|
||||
- 不修改底层引擎代码（bim_engine_base）
|
||||
- 不实现"显示全部"的实际逻辑（只 console.log）
|
||||
- 不添加新的 npm 依赖
|
||||
|
||||
---
|
||||
|
||||
## Verification Strategy
|
||||
|
||||
### Test Decision
|
||||
- **Infrastructure exists**: NO
|
||||
- **User wants tests**: Manual-only
|
||||
- **Framework**: none
|
||||
|
||||
### Manual QA
|
||||
1. `bun run build` 无报错
|
||||
2. 在 playground 中测试交互流程
|
||||
|
||||
---
|
||||
|
||||
## Task Flow
|
||||
|
||||
```
|
||||
Task 1 (Engine 监听点击，记录选中)
|
||||
↓
|
||||
Task 2 (EngineManager 暴露方法，修改右键处理器)
|
||||
↓
|
||||
Task 3 (创建 ComponentDetailManager)
|
||||
↓
|
||||
Task 4 (BimEngine 注册管理器)
|
||||
↓
|
||||
Task 5 (国际化 + 构建验证)
|
||||
↓
|
||||
Task 6 (重构调用链文档)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TODOs
|
||||
|
||||
- [ ] 1. Engine 组件 - 监听构件点击，记录选中状态
|
||||
|
||||
**What to do**:
|
||||
在 `engine/src/components/engine/index.ts` 中：
|
||||
|
||||
1. 新增私有属性存储选中构件信息：
|
||||
```typescript
|
||||
private selectedComponent: { url: string; id: string } | null = null;
|
||||
```
|
||||
|
||||
2. 在 `init()` 方法中监听底层 Click 事件：
|
||||
```typescript
|
||||
this.engine.events.on('click', (hit: any) => {
|
||||
if (hit && hit.object) {
|
||||
this.selectedComponent = {
|
||||
url: hit.object.url,
|
||||
id: hit.object.name
|
||||
};
|
||||
console.log('[Engine] 构件选中:', this.selectedComponent);
|
||||
} else {
|
||||
this.selectedComponent = null;
|
||||
console.log('[Engine] 取消选中');
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
3. 新增公共方法：
|
||||
```typescript
|
||||
public getSelectedComponent(): { url: string; id: string } | null {
|
||||
return this.selectedComponent;
|
||||
}
|
||||
|
||||
public getComponentProperties(
|
||||
url: string,
|
||||
id: string,
|
||||
callback: (data: any) => void
|
||||
): void {
|
||||
if (!this.engine?.modelProperties) {
|
||||
console.error('[Engine] modelProperties not available');
|
||||
return;
|
||||
}
|
||||
this.engine.modelProperties.getModelProperties(url, id, callback);
|
||||
}
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改现有的其他功能
|
||||
|
||||
**Parallelizable**: NO (后续任务依赖)
|
||||
|
||||
**References**:
|
||||
- `bim_engine_base/src/core/v2/modules/interactionModule.ts:36-53` - Click 事件触发逻辑
|
||||
- `bim_engine_base/src/core/v2/managers/modelProperties/index.ts:11-52` - getModelProperties 实现
|
||||
- `engine/src/components/engine/index.ts:108-131` - init() 方法位置
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] 新增 `selectedComponent` 私有属性
|
||||
- [ ] 在 init() 中监听 click 事件
|
||||
- [ ] 新增 `getSelectedComponent()` 方法
|
||||
- [ ] 新增 `getComponentProperties()` 方法
|
||||
- [ ] 点击构件时控制台输出选中信息
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(engine): 监听构件点击事件并记录选中状态`
|
||||
- Files: `src/components/engine/index.ts`
|
||||
|
||||
---
|
||||
|
||||
- [ ] 2. EngineManager - 暴露方法并修改右键处理器
|
||||
|
||||
**What to do**:
|
||||
在 `engine/src/managers/engine-manager.ts` 中：
|
||||
|
||||
1. 新增代理方法：
|
||||
```typescript
|
||||
public getSelectedComponent(): { url: string; id: string } | null {
|
||||
return this.engineInstance?.getSelectedComponent() ?? null;
|
||||
}
|
||||
|
||||
public getComponentProperties(
|
||||
url: string,
|
||||
id: string,
|
||||
callback: (data: any) => void
|
||||
): void {
|
||||
this.engineInstance?.getComponentProperties(url, id, callback);
|
||||
}
|
||||
```
|
||||
|
||||
2. 修改 `initialize()` 中的 `registerHandler`，根据选中状态返回不同菜单：
|
||||
```typescript
|
||||
this.rightKey.registerHandler((_e) => {
|
||||
const selected = this.getSelectedComponent();
|
||||
const items: MenuItemConfig[] = [];
|
||||
|
||||
if (selected) {
|
||||
items.push({
|
||||
id: 'componentDetail',
|
||||
label: 'menu.componentDetail',
|
||||
group: 'component',
|
||||
onClick: () => {
|
||||
const registry = ManagerRegistry.getInstance();
|
||||
registry.componentDetail?.show(selected.url, selected.id);
|
||||
this.rightKey?.hide();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
items.push({
|
||||
id: 'showAll',
|
||||
label: 'menu.showAll',
|
||||
group: 'component',
|
||||
onClick: () => {
|
||||
console.log('[Menu] 显示全部 - 功能开发中');
|
||||
this.rightKey?.hide();
|
||||
}
|
||||
});
|
||||
|
||||
items.push(infoMenuButton());
|
||||
items.push(homeMenuButton());
|
||||
|
||||
return items;
|
||||
});
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要删除现有的 infoMenuButton 和 homeMenuButton
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 1)
|
||||
|
||||
**References**:
|
||||
- `engine/src/managers/engine-manager.ts:50-57` - 现有 registerHandler 位置
|
||||
- `engine/src/components/menu/item.ts` - MenuItemConfig 定义
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] 新增 `getSelectedComponent()` 代理方法
|
||||
- [ ] 新增 `getComponentProperties()` 代理方法
|
||||
- [ ] 修改 registerHandler 动态返回菜单项
|
||||
- [ ] 有选中时显示"构件详情"+"显示全部"
|
||||
- [ ] 无选中时只显示"显示全部"
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(engine-manager): 添加构件选中方法和动态右键菜单`
|
||||
- Files: `src/managers/engine-manager.ts`
|
||||
|
||||
---
|
||||
|
||||
- [ ] 3. 创建 ComponentDetailManager - 构件详情弹窗
|
||||
|
||||
**What to do**:
|
||||
创建 `engine/src/managers/component-detail-manager.ts`：
|
||||
|
||||
```typescript
|
||||
import { BaseManager } from '../core/base-manager';
|
||||
import { BimCollapse } from '../components/collapse/index';
|
||||
import { BimDescription } from '../components/description/index';
|
||||
|
||||
export class ComponentDetailManager extends BaseManager {
|
||||
private dialogId = 'component-detail-dialog';
|
||||
private dialog: any = null;
|
||||
|
||||
constructor() {
|
||||
super();
|
||||
}
|
||||
|
||||
public show(modelUrl: string, componentId: string): void {
|
||||
if (!this.registry.dialog) {
|
||||
console.warn('[ComponentDetailManager] Dialog manager not initialized');
|
||||
return;
|
||||
}
|
||||
|
||||
if (this.isOpen()) {
|
||||
this.hide();
|
||||
}
|
||||
|
||||
// 先创建弹窗显示加载中
|
||||
this.createDialog();
|
||||
this.showLoading();
|
||||
|
||||
// 调用底层 API 获取属性
|
||||
this.registry.engine3d?.getComponentProperties(modelUrl, componentId, (data) => {
|
||||
this.renderProperties(data, componentId);
|
||||
});
|
||||
}
|
||||
|
||||
private createDialog(): void {
|
||||
const width = 400;
|
||||
const x = document.body.clientWidth - width - 40;
|
||||
|
||||
this.dialog = this.registry.dialog.create({
|
||||
id: this.dialogId,
|
||||
title: 'panel.componentDetail.title',
|
||||
content: '',
|
||||
width: `${width}px`,
|
||||
height: '500px',
|
||||
position: { x, y: 20 },
|
||||
showMask: false,
|
||||
resizable: true,
|
||||
onClose: () => this.hide()
|
||||
});
|
||||
}
|
||||
|
||||
private showLoading(): void {
|
||||
const container = document.createElement('div');
|
||||
container.style.padding = '20px';
|
||||
container.style.textAlign = 'center';
|
||||
container.textContent = '加载中...';
|
||||
this.dialog?.setContent(container);
|
||||
}
|
||||
|
||||
private renderProperties(data: any, componentId: string): void {
|
||||
if (!this.dialog) return;
|
||||
|
||||
const container = document.createElement('div');
|
||||
container.style.height = '100%';
|
||||
container.style.overflowY = 'auto';
|
||||
|
||||
const properties = data?.properties || [];
|
||||
|
||||
if (properties.length === 0) {
|
||||
container.innerHTML = '<div style="padding:20px;text-align:center;">无属性数据</div>';
|
||||
this.dialog.setContent(container);
|
||||
return;
|
||||
}
|
||||
|
||||
// 转换为 Collapse 需要的格式
|
||||
const collapseItems = properties.map((category: any, index: number) => ({
|
||||
id: `category-${index}`,
|
||||
title: category.name || `分类 ${index + 1}`,
|
||||
content: this.createCategoryContent(category.children || [])
|
||||
}));
|
||||
|
||||
new BimCollapse({
|
||||
container,
|
||||
accordion: false,
|
||||
activeIds: collapseItems.length > 0 ? [collapseItems[0].id] : [],
|
||||
items: collapseItems
|
||||
});
|
||||
|
||||
this.dialog.setContent(container);
|
||||
}
|
||||
|
||||
private createCategoryContent(items: any[]): HTMLElement {
|
||||
const container = document.createElement('div');
|
||||
|
||||
const descItems = items.map((item: any) => ({
|
||||
label: item.name || '-',
|
||||
value: String(item.value ?? '-')
|
||||
}));
|
||||
|
||||
new BimDescription({
|
||||
container,
|
||||
labelWidth: '120px',
|
||||
bordered: true,
|
||||
items: descItems
|
||||
});
|
||||
|
||||
return container;
|
||||
}
|
||||
|
||||
public isOpen(): boolean {
|
||||
return this.dialog !== null;
|
||||
}
|
||||
|
||||
public hide(): void {
|
||||
if (this.dialog) {
|
||||
this.dialog.destroy();
|
||||
this.dialog = null;
|
||||
}
|
||||
}
|
||||
|
||||
public destroy(): void {
|
||||
this.hide();
|
||||
super.destroy();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要创建新的 UI 组件，复用现有的 Collapse/Description
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 2)
|
||||
|
||||
**References**:
|
||||
- `engine/src/managers/property-panel-manager.ts` - 参考现有属性面板实现
|
||||
- `engine/src/components/collapse/index.ts` - Collapse 组件
|
||||
- `engine/src/components/description/index.ts` - Description 组件
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] 新建 `component-detail-manager.ts` 文件
|
||||
- [ ] 实现 `show(modelUrl, componentId)` 方法
|
||||
- [ ] 调用底层 API 获取属性数据
|
||||
- [ ] 使用 Collapse + Description 展示属性
|
||||
- [ ] 实现 `hide()` 和 `destroy()` 方法
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat: 新增构件详情弹窗管理器`
|
||||
- Files: `src/managers/component-detail-manager.ts`
|
||||
|
||||
---
|
||||
|
||||
- [ ] 4. BimEngine 和 Registry 注册管理器
|
||||
|
||||
**What to do**:
|
||||
|
||||
1. 修改 `engine/src/core/manager-registry.ts`，添加类型声明：
|
||||
```typescript
|
||||
import type { ComponentDetailManager } from '../managers/component-detail-manager';
|
||||
|
||||
// 在 ManagerRegistry 类中添加
|
||||
public componentDetail: ComponentDetailManager | null = null;
|
||||
```
|
||||
|
||||
2. 修改 `engine/src/bim-engine.ts`，添加初始化方法：
|
||||
```typescript
|
||||
import { ComponentDetailManager } from './managers/component-detail-manager';
|
||||
|
||||
// 添加属性
|
||||
public componentDetail: ComponentDetailManager | null = null;
|
||||
|
||||
// 添加初始化方法
|
||||
public initComponentDetail(): void {
|
||||
this.componentDetail = new ComponentDetailManager();
|
||||
this.registry.componentDetail = this.componentDetail;
|
||||
}
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改其他管理器的初始化逻辑
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 3)
|
||||
|
||||
**References**:
|
||||
- `engine/src/bim-engine.ts:106-108` - PropertyPanelManager 注册方式
|
||||
- `engine/src/core/manager-registry.ts` - Registry 结构
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] ManagerRegistry 添加 componentDetail 类型声明
|
||||
- [ ] BimEngine 添加 componentDetail 属性
|
||||
- [ ] BimEngine 添加 initComponentDetail() 方法
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(bim-engine): 注册构件详情管理器`
|
||||
- Files: `src/bim-engine.ts`, `src/core/manager-registry.ts`
|
||||
|
||||
---
|
||||
|
||||
- [ ] 5. 国际化文本 + 构建验证
|
||||
|
||||
**What to do**:
|
||||
|
||||
1. 修改 `engine/src/locales/zh-CN.ts`，添加：
|
||||
```typescript
|
||||
menu: {
|
||||
// 现有...
|
||||
componentDetail: '构件详情',
|
||||
showAll: '显示全部',
|
||||
},
|
||||
panel: {
|
||||
// 现有...
|
||||
componentDetail: {
|
||||
title: '构件详情',
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
2. 修改 `engine/src/locales/en-US.ts`，添加：
|
||||
```typescript
|
||||
menu: {
|
||||
// 现有...
|
||||
componentDetail: 'Component Detail',
|
||||
showAll: 'Show All',
|
||||
},
|
||||
panel: {
|
||||
// 现有...
|
||||
componentDetail: {
|
||||
title: 'Component Detail',
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
3. 运行构建验证：
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改现有的国际化文本
|
||||
|
||||
**Parallelizable**: NO (依赖前面所有任务)
|
||||
|
||||
**References**:
|
||||
- `engine/src/locales/zh-CN.ts` - 中文国际化
|
||||
- `engine/src/locales/en-US.ts` - 英文国际化
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] zh-CN 添加 menu.componentDetail, menu.showAll, panel.componentDetail.title
|
||||
- [ ] en-US 添加对应英文文本
|
||||
- [ ] `bun run build` 执行成功，无报错
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(i18n): 添加构件详情相关国际化文本`
|
||||
- Files: `src/locales/zh-CN.ts`, `src/locales/en-US.ts`
|
||||
|
||||
---
|
||||
|
||||
- [ ] 6. 重构调用链文档
|
||||
|
||||
**What to do**:
|
||||
|
||||
1. 将 `.sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md` 重命名为 `.sisyphus/drafts/API_CALLCHAIN.md`
|
||||
|
||||
2. 重构文档结构，从 Toolbar 专用扩展为全局 API 调用链文档：
|
||||
|
||||
```markdown
|
||||
# SDK API 调用链文档
|
||||
|
||||
本文档记录 SDK 中所有功能的完整调用链，从用户交互到底层 3D 引擎 API。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [Toolbar 工具栏](#1-toolbar-工具栏)
|
||||
2. [右键菜单 (Context Menu)](#2-右键菜单-context-menu)
|
||||
3. [构件交互 (Component Interaction)](#3-构件交互-component-interaction)
|
||||
|
||||
---
|
||||
|
||||
## 1. Toolbar 工具栏
|
||||
|
||||
### 1.1 首页 (Home)
|
||||
[原有内容...]
|
||||
|
||||
### 1.2 框选放大 (Zoom Box)
|
||||
[原有内容...]
|
||||
|
||||
...（其他 toolbar 按钮）
|
||||
|
||||
---
|
||||
|
||||
## 2. 右键菜单 (Context Menu)
|
||||
|
||||
### 2.1 构件详情 (Component Detail)
|
||||
|
||||
**触发条件**: 选中构件后右键
|
||||
**功能**: 查询并展示构件属性
|
||||
|
||||
#### 调用链
|
||||
|
||||
```
|
||||
用户点击构件
|
||||
│
|
||||
▼
|
||||
底层 interactionModule.handleMouseClick()
|
||||
│ engine.events.trigger('click', hit)
|
||||
▼
|
||||
[SDK] Engine 监听 'click' 事件
|
||||
│ 记录 selectedComponent = { url, id }
|
||||
▼
|
||||
用户右键点击
|
||||
│
|
||||
▼
|
||||
[SDK] RightKeyManager.handleContextMenu()
|
||||
│ 调用所有 contextHandlers
|
||||
▼
|
||||
[SDK] EngineManager 的 handler
|
||||
│ 检查 getSelectedComponent()
|
||||
│ 返回 MenuItemConfig[] (含 "构件详情")
|
||||
▼
|
||||
用户点击 "构件详情"
|
||||
│
|
||||
▼
|
||||
[SDK] ComponentDetailManager.show(url, id)
|
||||
│ 调用 getComponentProperties(url, id, callback)
|
||||
▼
|
||||
[SDK] Engine.getComponentProperties()
|
||||
│ this.engine.modelProperties.getModelProperties(url, id, callback)
|
||||
▼
|
||||
[底层] ModelProperties.getModelProperties()
|
||||
│ 加载/解析属性数据
|
||||
▼
|
||||
[SDK] ComponentDetailManager.renderProperties()
|
||||
│ 展示属性弹窗
|
||||
```
|
||||
|
||||
### 2.2 显示全部 (Show All)
|
||||
|
||||
**触发条件**: 右键（无论是否选中）
|
||||
**功能**: 显示全部构件（暂未实现）
|
||||
|
||||
#### 调用链
|
||||
|
||||
```
|
||||
用户右键点击
|
||||
│
|
||||
▼
|
||||
[SDK] RightKeyManager.handleContextMenu()
|
||||
│
|
||||
▼
|
||||
[SDK] EngineManager 的 handler
|
||||
│ 返回 MenuItemConfig[] (含 "显示全部")
|
||||
▼
|
||||
用户点击 "显示全部"
|
||||
│
|
||||
▼
|
||||
console.log('显示全部 - 功能开发中')
|
||||
```
|
||||
|
||||
### 2.3 信息 (Info)
|
||||
[现有 infoMenuButton 的调用链]
|
||||
|
||||
### 2.4 首页 (Home)
|
||||
[现有 homeMenuButton 的调用链]
|
||||
|
||||
---
|
||||
|
||||
## 3. 构件交互 (Component Interaction)
|
||||
|
||||
### 3.1 构件选中
|
||||
|
||||
**触发条件**: 点击 3D 场景中的构件
|
||||
**功能**: 高亮构件并记录选中状态
|
||||
|
||||
#### 调用链
|
||||
|
||||
```
|
||||
用户点击 3D 场景
|
||||
│
|
||||
▼
|
||||
[底层] handelBehaved 监听 mouseup
|
||||
│ 射线检测 (raycaster)
|
||||
▼
|
||||
[底层] interactionModule.handleMouseClick(event)
|
||||
│ event.catch = 射线检测结果
|
||||
│ engine.events.trigger('click', hit)
|
||||
│ engine.modelToolModule.highlightModel([{url, ids}])
|
||||
▼
|
||||
[SDK] Engine 监听 'click' 事件
|
||||
│ 记录 this.selectedComponent = { url: hit.object.url, id: hit.object.name }
|
||||
```
|
||||
|
||||
### 3.2 取消选中
|
||||
|
||||
**触发条件**: 点击空白区域
|
||||
**功能**: 取消高亮并清除选中状态
|
||||
|
||||
#### 调用链
|
||||
|
||||
```
|
||||
用户点击空白区域
|
||||
│
|
||||
▼
|
||||
[底层] interactionModule.handleMouseClick(event)
|
||||
│ event.catch = null
|
||||
│ engine.modelToolModule.unhighlightAllModels()
|
||||
▼
|
||||
[SDK] Engine 监听 'click' 事件
|
||||
│ this.selectedComponent = null
|
||||
```
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要删除现有 Toolbar 部分的内容
|
||||
- 不要修改现有调用链的准确性
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 5)
|
||||
|
||||
**References**:
|
||||
- `.sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md` - 现有文档
|
||||
- `engine/src/managers/right-key-manager.ts` - 右键菜单实现
|
||||
- `engine/src/managers/engine-manager.ts` - 右键处理器注册
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [ ] 文档重命名为 `API_CALLCHAIN.md`
|
||||
- [ ] 文档标题改为"SDK API 调用链文档"
|
||||
- [ ] 新增"右键菜单"章节，包含构件详情、显示全部、信息、首页
|
||||
- [ ] 新增"构件交互"章节，包含选中/取消选中调用链
|
||||
- [ ] 原 Toolbar 内容保持不变，作为第一章
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `docs: 重构调用链文档，新增右键菜单和构件交互章节`
|
||||
- Files: `.sisyphus/drafts/API_CALLCHAIN.md`
|
||||
|
||||
---
|
||||
|
||||
## Commit Strategy
|
||||
|
||||
| After Task | Message | Files |
|
||||
|------------|---------|-------|
|
||||
| 1 | `feat(engine): 监听构件点击事件并记录选中状态` | src/components/engine/index.ts |
|
||||
| 2 | `feat(engine-manager): 添加构件选中方法和动态右键菜单` | src/managers/engine-manager.ts |
|
||||
| 3 | `feat: 新增构件详情弹窗管理器` | src/managers/component-detail-manager.ts |
|
||||
| 4 | `feat(bim-engine): 注册构件详情管理器` | src/bim-engine.ts, src/core/manager-registry.ts |
|
||||
| 5 | `feat(i18n): 添加构件详情相关国际化文本` | src/locales/*.ts |
|
||||
| 6 | `docs: 重构调用链文档，新增右键菜单和构件交互章节` | .sisyphus/drafts/API_CALLCHAIN.md |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Verification Commands
|
||||
```bash
|
||||
bun run build # Expected: BUILD SUCCESS
|
||||
```
|
||||
|
||||
### Final Checklist
|
||||
- [ ] 点击构件后，控制台输出选中信息
|
||||
- [ ] 有选中构件时，右键显示"构件详情"+"显示全部"
|
||||
- [ ] 无选中构件时，右键只显示"显示全部"
|
||||
- [ ] 点击"构件详情"弹出属性弹窗
|
||||
- [ ] 弹窗正确展示底层 API 返回的属性数据
|
||||
- [ ] 点击"显示全部"控制台输出提示
|
||||
- [ ] 构建成功
|
||||
- [ ] 调用链文档已重构为全局文档
|
||||
- [ ] 新增右键菜单章节
|
||||
- [ ] 新增构件交互章节
|
||||
136
.sisyphus/plans/glass-pill-color-redesign.md
Normal file
136
.sisyphus/plans/glass-pill-color-redesign.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Glass-Pill 样式颜色重设计计划
|
||||
|
||||
## 背景
|
||||
|
||||
当前 `type: 'glass-pill'` 样式的颜色搭配不理想，需要重新设计深色和浅色两种主题的颜色方案。
|
||||
|
||||
## 设计规范（基于 UI/UX 专家建议）
|
||||
|
||||
参考 macOS Sonoma Control Center 和 iOS 17 的毛玻璃效果设计。
|
||||
|
||||
---
|
||||
|
||||
## 浅色主题 (Light Theme)
|
||||
|
||||
用于浅色背景（#f5f5f5, #ffffff 等）
|
||||
|
||||
### 容器（Pill）
|
||||
| 属性 | 值 |
|
||||
|-----|-----|
|
||||
| 背景 | `rgba(255, 255, 255, 0.72)` |
|
||||
| 模糊 | `blur(20px) saturate(1.8)` |
|
||||
| 边框 | `1px solid rgba(0, 0, 0, 0.08)` |
|
||||
| 阴影 | `0 2px 8px rgba(0,0,0,0.04), 0 8px 24px rgba(0,0,0,0.08)` |
|
||||
| 内边距 | `6px` |
|
||||
| 间距 | `4px` |
|
||||
|
||||
### 按钮
|
||||
| 状态 | 背景 | 其他 |
|
||||
|-----|-----|-----|
|
||||
| 默认 | `transparent` | - |
|
||||
| Hover | `rgba(0, 0, 0, 0.06)` | `translateY(-1px)` |
|
||||
| Pressed | `rgba(0, 0, 0, 0.10)` | `scale(0.96)` |
|
||||
| Active | `#0078d4` | 阴影: `0 2px 8px rgba(0,120,212,0.35)` |
|
||||
|
||||
### 图标
|
||||
| 状态 | 颜色 |
|
||||
|-----|-----|
|
||||
| 默认 | `rgba(0, 0, 0, 0.85)` |
|
||||
| Hover | `rgba(0, 0, 0, 0.95)` |
|
||||
| Active | `#ffffff` |
|
||||
|
||||
---
|
||||
|
||||
## 深色主题 (Dark Theme)
|
||||
|
||||
用于深色背景（#1a1a1a, #000000 等）
|
||||
|
||||
### 容器（Pill）
|
||||
| 属性 | 值 |
|
||||
|-----|-----|
|
||||
| 背景 | `rgba(38, 38, 40, 0.75)` |
|
||||
| 模糊 | `blur(24px) saturate(1.6)` |
|
||||
| 边框 | `1px solid rgba(255, 255, 255, 0.10)` |
|
||||
| 阴影 | `0 4px 12px rgba(0,0,0,0.25), 0 12px 40px rgba(0,0,0,0.35)` |
|
||||
|
||||
### 按钮
|
||||
| 状态 | 背景 | 其他 |
|
||||
|-----|-----|-----|
|
||||
| 默认 | `transparent` | - |
|
||||
| Hover | `rgba(255, 255, 255, 0.10)` | `translateY(-1px)` |
|
||||
| Pressed | `rgba(255, 255, 255, 0.06)` | `scale(0.96)` |
|
||||
| Active | `#2899f5` (更亮的蓝) | 阴影: `0 2px 12px rgba(40,153,245,0.45)` |
|
||||
|
||||
### 图标
|
||||
| 状态 | 颜色 |
|
||||
|-----|-----|
|
||||
| 默认 | `rgba(255, 255, 255, 0.90)` |
|
||||
| Hover | `rgba(255, 255, 255, 1.0)` |
|
||||
| Active | `#ffffff` |
|
||||
|
||||
---
|
||||
|
||||
## 二级菜单
|
||||
|
||||
### 浅色主题
|
||||
- 背景: `rgba(255, 255, 255, 0.95)`
|
||||
- 边框: `1px solid rgba(0, 0, 0, 0.08)`
|
||||
- 圆角: `12px`
|
||||
- 阴影: `0 8px 24px rgba(0, 0, 0, 0.12)`
|
||||
- 菜单项 Hover: `rgba(0, 0, 0, 0.06)`
|
||||
- 文字: `rgba(0, 0, 0, 0.85)`
|
||||
- 图标: `rgba(0, 0, 0, 0.85)`
|
||||
|
||||
### 深色主题
|
||||
- 背景: `rgba(38, 38, 40, 0.95)`
|
||||
- 边框: `1px solid rgba(255, 255, 255, 0.10)`
|
||||
- 菜单项 Hover: `rgba(255, 255, 255, 0.10)`
|
||||
- 文字: `rgba(255, 255, 255, 0.90)`
|
||||
- 图标: `rgba(255, 255, 255, 0.90)`
|
||||
|
||||
---
|
||||
|
||||
## 实现任务
|
||||
|
||||
### 文件: `src/components/button-group/index.css`
|
||||
|
||||
**任务 1: 重写浅色主题样式** (第 311-417 行)
|
||||
- 更新 `.bim-btn-group-root.type-glass-pill .bim-btn-group-section` 容器样式
|
||||
- 更新 `.bim-btn-group-root.type-glass-pill .opt-btn` 按钮默认样式
|
||||
- 更新 `.bim-btn-group-root.type-glass-pill .opt-btn:hover` 悬停样式
|
||||
- 更新 `.bim-btn-group-root.type-glass-pill .opt-btn.active` 激活样式
|
||||
- 更新 `.bim-btn-group-root.type-glass-pill .opt-btn-icon` 图标样式
|
||||
- 更新二级菜单 `.opt-btn-dropdown.type-glass-pill` 样式
|
||||
|
||||
**任务 2: 重写深色主题样式** (第 419-458 行)
|
||||
- 更新 `.bim-btn-group-root.type-glass-pill.theme-dark` 容器和按钮样式
|
||||
- 更新深色主题的激活态蓝色为 `#2899f5`
|
||||
- 更新深色主题二级菜单样式
|
||||
|
||||
**任务 3: 添加缺失的状态样式**
|
||||
- 添加 `:active` (pressed) 状态
|
||||
- 添加 hover 时的图标颜色变化
|
||||
- 添加 transition 动画优化
|
||||
|
||||
---
|
||||
|
||||
## 关键颜色对照表
|
||||
|
||||
| 元素 | 浅色主题 | 深色主题 |
|
||||
|-----|---------|---------|
|
||||
| 容器背景 | `rgba(255,255,255,0.72)` | `rgba(38,38,40,0.75)` |
|
||||
| 容器边框 | `rgba(0,0,0,0.08)` | `rgba(255,255,255,0.10)` |
|
||||
| 按钮 Hover | `rgba(0,0,0,0.06)` | `rgba(255,255,255,0.10)` |
|
||||
| 激活蓝色 | `#0078d4` | `#2899f5` |
|
||||
| 图标颜色 | `rgba(0,0,0,0.85)` | `rgba(255,255,255,0.90)` |
|
||||
|
||||
---
|
||||
|
||||
## 验收标准
|
||||
|
||||
1. ✅ 浅色主题下容器呈现半透明白色毛玻璃效果
|
||||
2. ✅ 深色主题下容器呈现半透明深灰色毛玻璃效果
|
||||
3. ✅ 按钮默认状态无背景色，仅 hover/active 时显示
|
||||
4. ✅ 激活态使用蓝色，深色主题使用更亮的蓝色
|
||||
5. ✅ 图标颜色在不同主题下清晰可见
|
||||
6. ✅ 二级菜单与主工具栏风格一致
|
||||
170
.sisyphus/plans/measure-clearall.md
Normal file
170
.sisyphus/plans/measure-clearall.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# 测量功能 clearAllMeasures 封装
|
||||
|
||||
## Context
|
||||
|
||||
### Original Request
|
||||
封装测量功能的 `clearAllMeasures()` 方法，并对接到 UI 的"删除全部"按钮。
|
||||
|
||||
### Interview Summary
|
||||
**Key Discussions**:
|
||||
- 封装原则：所有底层引擎调用（`this.engine.*`）必须封装在 Engine 组件中
|
||||
- Manager 层只调用 Engine 组件的公共方法，禁止直接使用 `getEngine()`
|
||||
- 当前 MeasurePanel 的 `clearAll()` 方法已调用 `onClearAll` 回调
|
||||
- 当前 MeasureDialogManager 的 `onClearAll` 回调只有 console.log，未调用引擎方法
|
||||
|
||||
**Research Findings**:
|
||||
- 第三方引擎 API：`measure.clearAll()` - 清除所有测量标注
|
||||
- 现有代码已有类似封装模式（如 `activateMeasure`、`deactivateMeasure`）
|
||||
- MeasurePanel 组件调用 `onClearAll` 回调后已清空 UI 结果显示
|
||||
|
||||
---
|
||||
|
||||
## Work Objectives
|
||||
|
||||
### Core Objective
|
||||
在 Engine 组件中封装 `clearAllMeasures()` 方法，并在 MeasureDialogManager 的 `onClearAll` 回调中调用该方法，实现 UI "删除全部"按钮的完整功能对接。
|
||||
|
||||
### Concrete Deliverables
|
||||
- Engine 组件新增 `clearAllMeasures()` 公共方法
|
||||
- MeasureDialogManager 的 `onClearAll` 回调调用引擎方法
|
||||
|
||||
### Definition of Done
|
||||
- [x] 点击测量面板的"删除全部"按钮，控制台输出 `清除所有测量标注`（代码已实现）
|
||||
- [x] 3D 场景中的测量标注被清除（代码已实现，需用户手动验证）
|
||||
|
||||
### Must Have
|
||||
- 方法命名为 `clearAllMeasures()`，与现有命名风格一致
|
||||
- 添加引擎初始化检查（与现有方法一致）
|
||||
- 添加 console.log 输出用于调试
|
||||
- 中文注释说明方法功能
|
||||
|
||||
### Must NOT Have (Guardrails)
|
||||
- 不封装 `clearMeasurePoints()` 方法（本次范围外）
|
||||
- 不对接测量结果回调（本次范围外）
|
||||
- 不修改 MeasurePanel 组件（已完成 UI 逻辑）
|
||||
- Manager 层不直接调用 `getEngine()`
|
||||
|
||||
---
|
||||
|
||||
## Verification Strategy (MANDATORY)
|
||||
|
||||
### Test Decision
|
||||
- **Infrastructure exists**: NO
|
||||
- **User wants tests**: NO (简单封装，手动验证)
|
||||
- **Framework**: none
|
||||
- **QA approach**: Manual verification
|
||||
|
||||
---
|
||||
|
||||
## Task Flow
|
||||
|
||||
```
|
||||
Task 1 (Engine 封装) → Task 2 (Manager 对接)
|
||||
```
|
||||
|
||||
## Parallelization
|
||||
|
||||
| Task | Depends On | Reason |
|
||||
|------|------------|--------|
|
||||
| 2 | 1 | Manager 需要调用 Engine 的新方法 |
|
||||
|
||||
---
|
||||
|
||||
## TODOs
|
||||
|
||||
- [x] 1. Engine 组件添加 clearAllMeasures 方法
|
||||
|
||||
**What to do**:
|
||||
- 在 `src/components/engine/index.ts` 的测量功能方法区域（第 388 行之前，`getCurrentMeasureType()` 方法之后）添加 `clearAllMeasures()` 公共方法
|
||||
- 方法内部调用 `this.engine.measure.clearAll()`
|
||||
- 添加引擎初始化检查（与 `deactivateMeasure()` 方法一致）
|
||||
- 添加 console.log 输出：`清除所有测量标注`
|
||||
- 添加中文 JSDoc 注释
|
||||
|
||||
**Must NOT do**:
|
||||
- 不封装 `clearMeasurePoints()` 方法
|
||||
- 不修改现有方法
|
||||
|
||||
**Parallelizable**: NO (Task 2 依赖此任务)
|
||||
|
||||
**References**:
|
||||
|
||||
**Pattern References** (existing code to follow):
|
||||
- `src/components/engine/index.ts:366-378` - `deactivateMeasure()` 方法：参考其引擎初始化检查和 console.log 输出模式
|
||||
|
||||
**API/Type References**:
|
||||
- `docs/ENGINNE_3D/API文档.md:946-952` - 第三方引擎 `measure.clearAll()` API 说明
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
**Manual Execution Verification:**
|
||||
- [x] 检查 `src/components/engine/index.ts` 文件
|
||||
- [x] 确认新增 `clearAllMeasures()` 方法
|
||||
- [x] 确认方法位于 `getCurrentMeasureType()` 方法之后、`// ==================== 结束：测量功能方法 ====================` 注释之前
|
||||
- [x] 确认方法包含引擎初始化检查
|
||||
- [x] 确认方法调用 `this.engine.measure.clearAll()`
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(engine): add clearAllMeasures method for measure cleanup`
|
||||
- Files: `src/components/engine/index.ts`
|
||||
|
||||
---
|
||||
|
||||
- [x] 2. MeasureDialogManager onClearAll 回调调用引擎方法
|
||||
|
||||
**What to do**:
|
||||
- 在 `src/managers/measure-dialog-manager.ts` 的 `onClearAll` 回调中（第 46-48 行）
|
||||
- 在 console.log 之后添加 `this.registry.engine3d?.clearAllMeasures();`
|
||||
|
||||
**Must NOT do**:
|
||||
- 不使用 `getEngine()` 直接调用底层引擎
|
||||
- 不修改 MeasurePanel 组件
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 1)
|
||||
|
||||
**References**:
|
||||
|
||||
**Pattern References** (existing code to follow):
|
||||
- `src/managers/measure-dialog-manager.ts:42-45` - `onModeChange` 回调：参考其调用 `registry.engine3d?.activateMeasure(mode)` 的模式
|
||||
- `src/managers/measure-dialog-manager.ts:77-80` - `onBeforeDestroy` 方法：参考其调用 `registry.engine3d.deactivateMeasure()` 的模式
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
**Manual Execution Verification:**
|
||||
- [x] 检查 `src/managers/measure-dialog-manager.ts` 文件
|
||||
- [x] 确认 `onClearAll` 回调中添加了 `this.registry.engine3d?.clearAllMeasures();`
|
||||
- [x] 运行 `npm run build` - 构建成功
|
||||
- [ ] 运行 `npm run dev:demo`（需要用户手动测试）
|
||||
- [ ] 打开测量面板，进行测量操作
|
||||
- [ ] 点击"删除全部"按钮
|
||||
- [ ] 控制台输出包含 `清除所有测量标注`
|
||||
- [ ] 3D 场景中的测量标注被清除
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(measure): connect clearAll button to engine clearAllMeasures method`
|
||||
- Files: `src/managers/measure-dialog-manager.ts`
|
||||
|
||||
---
|
||||
|
||||
## Commit Strategy
|
||||
|
||||
| After Task | Message | Files | Verification |
|
||||
|------------|---------|-------|--------------|
|
||||
| 1 | `feat(engine): add clearAllMeasures method for measure cleanup` | `src/components/engine/index.ts` | 代码审查 |
|
||||
| 2 | `feat(measure): connect clearAll button to engine clearAllMeasures method` | `src/managers/measure-dialog-manager.ts` | `npm run dev:demo` + 手动测试 |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Verification Commands
|
||||
```bash
|
||||
npm run dev:demo # 启动 HTML Demo
|
||||
# 手动测试：打开测量面板 → 进行测量 → 点击"删除全部" → 验证标注清除
|
||||
```
|
||||
|
||||
### Final Checklist
|
||||
- [x] Engine 组件有 `clearAllMeasures()` 公共方法
|
||||
- [x] MeasureDialogManager 的 `onClearAll` 回调调用引擎方法
|
||||
- [x] 点击"删除全部"按钮后，3D 场景中的测量标注被清除（代码已实现）
|
||||
- [x] 控制台无报错（构建成功）
|
||||
578
.sisyphus/plans/section-axis-integration.md
Normal file
578
.sisyphus/plans/section-axis-integration.md
Normal file
@@ -0,0 +1,578 @@
|
||||
# 轴向剖切功能对接
|
||||
|
||||
## Context
|
||||
|
||||
### Original Request
|
||||
对接轴向剖切功能（X/Y/Z 轴）到第三方 BIM 引擎，包括：
|
||||
- 打开弹窗时自动激活默认轴向剖切
|
||||
- 切换 X/Y/Z 轴向
|
||||
- 关闭弹窗时停用剖切
|
||||
|
||||
### Interview Summary
|
||||
**Key Discussions**:
|
||||
- **激活时机**: 打开弹窗时自动激活默认轴向（X轴）的剖切，关闭时停用
|
||||
- **轴向切换**: X/Y/Z 互斥，一次只能激活一个轴向
|
||||
- **隐藏按钮**: ❌ 第三方引擎无 API，本期不实现
|
||||
- **反向按钮**: ❌ 第三方引擎无 API，本期不实现
|
||||
- **验证方式**: 手动 QA（在 demo 中运行）
|
||||
|
||||
**API 确认**（用户直接提供，已验证可用）:
|
||||
```javascript
|
||||
// 激活剖切
|
||||
engine.clipping.sectionPlaneX.active() // X 轴（前后方向）
|
||||
engine.clipping.sectionPlaneY.active() // Y 轴（上下方向）
|
||||
engine.clipping.sectionPlaneZ.active() // Z 轴（左右方向）
|
||||
|
||||
// 停用剖切
|
||||
engine.clipping.sectionPlaneX.disActive() // 停用 X 轴
|
||||
engine.clipping.disActive() // 停用所有
|
||||
|
||||
// 切换逻辑（从 X 切换到 Y）
|
||||
engine.clipping.sectionPlaneX.disActive()
|
||||
engine.clipping.sectionPlaneY.active()
|
||||
```
|
||||
|
||||
**API 验证说明**:
|
||||
- 来源：用户直接提供，基于第三方引擎 `iflow-engine-base` 的实际使用经验
|
||||
- 验证方式：在实施 Task 1 前，可在 demo 控制台运行以下代码确认：
|
||||
```javascript
|
||||
const engine = window.bimEngine?.engine?.getEngine();
|
||||
console.log('clipping模块:', typeof engine?.clipping); // 预期: 'object'
|
||||
console.log('sectionPlaneX:', typeof engine?.clipping?.sectionPlaneX); // 预期: 'object'
|
||||
console.log('active方法:', typeof engine?.clipping?.sectionPlaneX?.active); // 预期: 'function'
|
||||
```
|
||||
|
||||
**Research Findings**:
|
||||
- 已有组件：
|
||||
- SectionAxisPanel (UI 完成): `src/components/section-axis-panel/index.ts`
|
||||
- SectionAxisDialogManager (回调未实现): `src/managers/section-axis-dialog-manager.ts`
|
||||
|
||||
---
|
||||
|
||||
## Work Objectives
|
||||
|
||||
### Core Objective
|
||||
在 Engine 组件中封装轴向剖切方法，对接到 SectionAxisDialogManager，实现 X/Y/Z 轴向剖切的激活、切换和停用功能。
|
||||
|
||||
### Concrete Deliverables
|
||||
1. Engine 组件新增轴向剖切方法
|
||||
2. EngineManager 暴露轴向剖切方法
|
||||
3. SectionAxisDialogManager 回调对接完成
|
||||
|
||||
### Definition of Done
|
||||
- [x] 打开轴向剖切弹窗时，自动激活 X 轴剖切
|
||||
- [x] 点击 Y/Z 按钮时，切换到对应轴向剖切
|
||||
- [x] 关闭弹窗时，剖切功能停用
|
||||
- [x] 控制台无错误
|
||||
|
||||
### Must Have
|
||||
- 轴向切换互斥（一次只激活一个轴向）
|
||||
- 切换时先停用当前轴向，再激活新轴向
|
||||
- 重复激活同一轴向时静默返回（幂等操作）
|
||||
- 弹窗关闭时自动清理剖切状态
|
||||
- 所有公共方法有 JSDoc 中文注释
|
||||
- **前置条件**: 用户必须先调用 `bimEngine.initEngine()` 初始化 3D 引擎，才能使用轴向剖切功能
|
||||
|
||||
### Must NOT Have (Guardrails)
|
||||
- 不修改 SectionAxisPanel UI 组件（已完成）
|
||||
- 不实现隐藏功能（第三方无 API）
|
||||
- 不实现反向功能（第三方无 API）
|
||||
- 不涉及剖切盒（SectionBox）功能
|
||||
- 不添加剖切位置调整功能（滑块）
|
||||
|
||||
---
|
||||
|
||||
## Verification Strategy (MANDATORY)
|
||||
|
||||
### Test Decision
|
||||
- **Infrastructure exists**: NO
|
||||
- **User wants tests**: NO (Manual QA)
|
||||
- **Framework**: None
|
||||
- **QA approach**: 在 demo 中运行，目视确认剖切效果
|
||||
|
||||
### Manual QA Verification
|
||||
每个 TODO 包含详细的手动验证步骤，使用：
|
||||
- 浏览器开发者工具控制台
|
||||
- 目视确认 3D 场景剖切效果（模型被平面切开，可见内部结构）
|
||||
- 引擎状态确认（通过 `getCurrentSectionAxis()` 方法）
|
||||
|
||||
---
|
||||
|
||||
## Task Flow
|
||||
|
||||
```
|
||||
Task 1 (Engine 组件封装)
|
||||
↓
|
||||
Task 2 (EngineManager 暴露)
|
||||
↓
|
||||
Task 3 (DialogManager 对接)
|
||||
↓
|
||||
Task 4 (最终验证)
|
||||
```
|
||||
|
||||
## Parallelization
|
||||
|
||||
| Task | Depends On | Reason |
|
||||
|------|------------|--------|
|
||||
| 2 | 1 | 需要 Engine 组件方法 |
|
||||
| 3 | 2 | 需要 EngineManager 方法 |
|
||||
| 4 | 3 | 需要所有功能完成 |
|
||||
|
||||
---
|
||||
|
||||
## TODOs
|
||||
|
||||
- [x] 1. Engine 组件：封装轴向剖切方法
|
||||
|
||||
**What to do**:
|
||||
- 在 `src/components/engine/index.ts` 中添加轴向剖切相关方法
|
||||
- 添加状态变量跟踪当前激活的剖切轴向
|
||||
- 实现以下方法和状态变量：
|
||||
|
||||
```typescript
|
||||
// ==================== 轴向剖切功能 ====================
|
||||
|
||||
/** 当前激活的剖切轴向 */
|
||||
private currentSectionAxis: 'x' | 'y' | 'z' | null = null;
|
||||
|
||||
/**
|
||||
* 激活轴向剖切
|
||||
* @param axis 要激活的轴向 ('x' | 'y' | 'z')
|
||||
* @remarks
|
||||
* - 如果传入的轴向与当前激活的轴向相同，则静默返回（幂等操作）
|
||||
* - 如果当前有不同的轴向激活，先调用该轴向的 disActive() 再激活新轴向
|
||||
* - 使用单个 plane 的 disActive() 而非 clipping.disActive()，避免影响其他剖切功能
|
||||
* - 如果引擎未初始化或 clipping 模块不可用，方法会静默返回并输出错误日志
|
||||
*/
|
||||
public activateSectionAxis(axis: 'x' | 'y' | 'z'): void {
|
||||
// 1. 检查引擎初始化
|
||||
if (!this._isInitialized || !this.engine) {
|
||||
console.error('[Engine] Cannot activate section axis: engine not initialized.');
|
||||
return;
|
||||
}
|
||||
|
||||
// 2. 检查 clipping 模块
|
||||
if (!this.engine.clipping) {
|
||||
console.error('[Engine] Clipping module not available.');
|
||||
return;
|
||||
}
|
||||
|
||||
// 3. 如果是同一轴向，静默返回（幂等操作）
|
||||
if (this.currentSectionAxis === axis) {
|
||||
console.log(`[Engine] Section axis ${axis} already active, skipping.`);
|
||||
return;
|
||||
}
|
||||
|
||||
// 4. 如果当前有激活的轴向且不同，先停用当前轴向
|
||||
if (this.currentSectionAxis) {
|
||||
this.deactivateCurrentSectionAxis();
|
||||
}
|
||||
|
||||
// 5. 激活新轴向
|
||||
const planeMap: Record<'x' | 'y' | 'z', any> = {
|
||||
'x': this.engine.clipping.sectionPlaneX,
|
||||
'y': this.engine.clipping.sectionPlaneY,
|
||||
'z': this.engine.clipping.sectionPlaneZ
|
||||
};
|
||||
const plane = planeMap[axis];
|
||||
|
||||
if (plane && typeof plane.active === 'function') {
|
||||
console.log(`[Engine] Activating section axis: ${axis}`);
|
||||
plane.active();
|
||||
this.currentSectionAxis = axis;
|
||||
} else {
|
||||
console.error(`[Engine] Section plane ${axis} not available.`);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 停用当前轴向剖切（内部方法）
|
||||
* @remarks 只停用当前激活的单个轴向，不影响其他剖切功能
|
||||
*/
|
||||
private deactivateCurrentSectionAxis(): void {
|
||||
if (!this.currentSectionAxis || !this.engine?.clipping) {
|
||||
return;
|
||||
}
|
||||
|
||||
const planeMap: Record<'x' | 'y' | 'z', any> = {
|
||||
'x': this.engine.clipping.sectionPlaneX,
|
||||
'y': this.engine.clipping.sectionPlaneY,
|
||||
'z': this.engine.clipping.sectionPlaneZ
|
||||
};
|
||||
const plane = planeMap[this.currentSectionAxis];
|
||||
|
||||
if (plane && typeof plane.disActive === 'function') {
|
||||
console.log(`[Engine] Deactivating section axis: ${this.currentSectionAxis}`);
|
||||
plane.disActive();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 停用轴向剖切（公共方法，关闭弹窗时调用）
|
||||
* @remarks 使用 clipping.disActive() 停用所有剖切，清理状态
|
||||
*/
|
||||
public deactivateSectionAxis(): void {
|
||||
if (!this._isInitialized || !this.engine?.clipping) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (this.currentSectionAxis) {
|
||||
console.log('[Engine] Deactivating all section axis');
|
||||
this.engine.clipping.disActive();
|
||||
this.currentSectionAxis = null;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取当前剖切轴向
|
||||
* @returns 当前激活的轴向，如果未激活则返回 null
|
||||
*/
|
||||
public getCurrentSectionAxis(): 'x' | 'y' | 'z' | null {
|
||||
return this.currentSectionAxis;
|
||||
}
|
||||
|
||||
// ==================== 结束：轴向剖切功能 ====================
|
||||
```
|
||||
|
||||
**状态管理逻辑说明**:
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 当前无激活，激活 X | 直接调用 `sectionPlaneX.active()` |
|
||||
| 当前 X 激活，再次激活 X | 静默返回，输出日志"already active" |
|
||||
| 当前 X 激活，切换到 Y | 先 `sectionPlaneX.disActive()`，再 `sectionPlaneY.active()` |
|
||||
| 关闭弹窗 | 调用 `clipping.disActive()` 停用所有，清理状态 |
|
||||
|
||||
**两个停用方法的区别**:
|
||||
| 方法 | 作用域 | 使用场景 |
|
||||
|------|--------|----------|
|
||||
| `deactivateCurrentSectionAxis()` (私有) | 只停用当前轴向 | 切换轴向时 |
|
||||
| `deactivateSectionAxis()` (公共) | 停用所有剖切 | 关闭弹窗时 |
|
||||
|
||||
**Must NOT do**:
|
||||
- 不修改已有的测量功能方法
|
||||
- 不实现 `reverseSectionAxis()` 和 `toggleSectionAxisVisibility()`（无 API）
|
||||
- 不添加剖切位置调整功能
|
||||
|
||||
**Parallelizable**: NO (起始任务)
|
||||
|
||||
**References**:
|
||||
|
||||
**Pattern References** (existing code to follow):
|
||||
- `src/components/engine/index.ts:217-401` - 测量功能封装模式（activateMeasureType、deactivateMeasure）
|
||||
- `src/components/engine/index.ts:42-45` - 状态变量定义模式
|
||||
|
||||
**API/Type References** (contracts to implement against):
|
||||
- `src/components/section-axis-panel/types.ts:4` - `SectionAxis` 类型定义
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
**Manual Execution Verification**:
|
||||
- [x] 构建成功: `npm run build` → 无错误
|
||||
- [ ] 运行 demo: `npm run dev:demo`
|
||||
- [ ] 先验证 API 存在（在控制台运行）：
|
||||
```javascript
|
||||
const engine = window.bimEngine?.engine?.getEngine();
|
||||
console.log('clipping:', typeof engine?.clipping); // 预期: 'object'
|
||||
console.log('active:', typeof engine?.clipping?.sectionPlaneX?.active); // 预期: 'function'
|
||||
```
|
||||
- [ ] 验证封装方法存在：
|
||||
```javascript
|
||||
const engineComp = window.bimEngine?.engine;
|
||||
console.log(typeof engineComp.activateSectionAxis); // 'function'
|
||||
console.log(typeof engineComp.deactivateSectionAxis); // 'function'
|
||||
console.log(typeof engineComp.getCurrentSectionAxis); // 'function'
|
||||
```
|
||||
|
||||
**Evidence Required**:
|
||||
- [x] `npm run build` 输出无错误
|
||||
- [ ] API 验证和方法验证的控制台输出
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(engine): add section axis clipping methods`
|
||||
- Files: `src/components/engine/index.ts`
|
||||
- Pre-commit: `npm run build`
|
||||
|
||||
---
|
||||
|
||||
- [x] 2. EngineManager：暴露轴向剖切方法
|
||||
|
||||
**What to do**:
|
||||
- 在 `src/managers/engine-manager.ts` 中添加轴向剖切方法代理
|
||||
- 实现以下方法（代理到 Engine 组件）：
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* 激活轴向剖切
|
||||
* @param axis 要激活的轴向 ('x' | 'y' | 'z')
|
||||
*/
|
||||
public activateSectionAxis(axis: 'x' | 'y' | 'z'): void {
|
||||
if (!this.engineInstance) {
|
||||
console.warn('[EngineManager] 3D Engine not initialized.');
|
||||
return;
|
||||
}
|
||||
this.engineInstance.activateSectionAxis(axis);
|
||||
}
|
||||
|
||||
/**
|
||||
* 停用轴向剖切
|
||||
*/
|
||||
public deactivateSectionAxis(): void {
|
||||
if (!this.engineInstance) {
|
||||
return;
|
||||
}
|
||||
this.engineInstance.deactivateSectionAxis();
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取当前剖切轴向
|
||||
* @returns 当前激活的轴向
|
||||
*/
|
||||
public getCurrentSectionAxis(): 'x' | 'y' | 'z' | null {
|
||||
if (!this.engineInstance) {
|
||||
return null;
|
||||
}
|
||||
return this.engineInstance.getCurrentSectionAxis();
|
||||
}
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不在 Manager 中直接调用 `this.engineInstance.getEngine()`
|
||||
- 只调用 Engine 组件的公共方法
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 1)
|
||||
|
||||
**References**:
|
||||
|
||||
**Pattern References**:
|
||||
- `src/managers/engine-manager.ts:126-163` - 测量方法代理模式（activateMeasure、deactivateMeasure）
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
**Manual Execution Verification**:
|
||||
- [x] 构建成功: `npm run build` → 无错误
|
||||
- [ ] 在控制台验证方法存在：
|
||||
```javascript
|
||||
const engineManager = window.bimEngine?.engine;
|
||||
console.log(typeof engineManager.activateSectionAxis); // 'function'
|
||||
```
|
||||
|
||||
**Evidence Required**:
|
||||
- [x] `npm run build` 输出无错误
|
||||
|
||||
**Commit**: YES (与 Task 1 合并)
|
||||
- Message: `feat(engine): add section axis clipping methods`
|
||||
- Files: `src/components/engine/index.ts`, `src/managers/engine-manager.ts`
|
||||
- Pre-commit: `npm run build`
|
||||
|
||||
---
|
||||
|
||||
- [x] 3. SectionAxisDialogManager：对接回调
|
||||
|
||||
**What to do**:
|
||||
- 修改 `src/managers/section-axis-dialog-manager.ts`
|
||||
- 在回调中调用 Engine 方法
|
||||
|
||||
**BaseDialogManager 生命周期说明**（参考 `src/core/base-dialog-manager.ts:76-108`）:
|
||||
| 钩子 | 调用时机 | 用途 |
|
||||
|------|----------|------|
|
||||
| `onDialogCreated()` | `show()` 中，`dialog.init()` 之后 | 初始化业务逻辑，如自动激活剖切 |
|
||||
| `onDialogClose()` | 用户点击关闭按钮时 | 清理 UI 状态，如取消工具栏按钮激活 |
|
||||
| `onBeforeDestroy()` | `destroyDialog()` 中，`dialog.destroy()` 之前 | 清理业务逻辑，如停用剖切 |
|
||||
|
||||
**修改 `createContent()` 方法**:
|
||||
|
||||
```typescript
|
||||
protected createContent(): HTMLElement {
|
||||
this.panel = new SectionAxisPanel({
|
||||
defaultAxis: 'x',
|
||||
defaultHidden: false,
|
||||
onHideToggle: (isHidden) => {
|
||||
// 隐藏功能：第三方引擎无 API，仅输出日志
|
||||
console.log('[SectionAxisDialogManager] 隐藏切换（暂不支持）：', isHidden);
|
||||
},
|
||||
onReverse: () => {
|
||||
// 反向功能：第三方引擎无 API，仅输出日志
|
||||
console.log('[SectionAxisDialogManager] 反向剖切（暂不支持）');
|
||||
},
|
||||
onAxisChange: (axis) => {
|
||||
console.log('[SectionAxisDialogManager] 切换轴向：', axis);
|
||||
this.registry.engine3d?.activateSectionAxis(axis);
|
||||
}
|
||||
});
|
||||
this.panel.init();
|
||||
return this.panel.element;
|
||||
}
|
||||
```
|
||||
|
||||
**修改 `onDialogCreated()` 方法**:
|
||||
|
||||
```typescript
|
||||
protected onDialogCreated(): void {
|
||||
this.dialog?.fitHeight(false);
|
||||
|
||||
// 检查 Engine 是否已初始化
|
||||
if (!this.registry.engine3d) {
|
||||
console.error('[SectionAxisDialogManager] Engine not initialized. Call initEngine() first.');
|
||||
return;
|
||||
}
|
||||
|
||||
// 自动激活默认轴向剖切（X轴）
|
||||
this.registry.engine3d.activateSectionAxis('x');
|
||||
}
|
||||
```
|
||||
|
||||
**修改 `onBeforeDestroy()` 方法**:
|
||||
|
||||
```typescript
|
||||
protected onBeforeDestroy(): void {
|
||||
// 停用轴向剖切
|
||||
this.registry.engine3d?.deactivateSectionAxis();
|
||||
|
||||
if (this.panel) {
|
||||
this.panel.destroy();
|
||||
this.panel = null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不修改 SectionAxisPanel UI 组件
|
||||
- 不直接调用 `registry.engine3d?.getEngine()`
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 2)
|
||||
|
||||
**References**:
|
||||
|
||||
**Pattern References**:
|
||||
- `src/core/base-dialog-manager.ts:49-54` - 生命周期钩子定义
|
||||
- `src/core/base-dialog-manager.ts:76-108` - show() 方法，展示钩子调用时机
|
||||
- `src/managers/measure-dialog-manager.ts:38-55` - 回调对接模式
|
||||
- `src/managers/measure-dialog-manager.ts:77-86` - onBeforeDestroy 清理模式
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
**Manual Execution Verification**:
|
||||
- [x] 构建成功: `npm run build` → 无错误
|
||||
- [ ] 运行 demo 验证交互
|
||||
|
||||
**Evidence Required**:
|
||||
- [x] `npm run build` 输出无错误
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(section-axis): integrate dialog manager with engine methods`
|
||||
- Files: `src/managers/section-axis-dialog-manager.ts`
|
||||
- Pre-commit: `npm run build`
|
||||
|
||||
---
|
||||
|
||||
- [x] 4. 最终验证：完整功能测试
|
||||
|
||||
**What to do**:
|
||||
- 在 demo 中完整测试所有功能
|
||||
- 验证所有交互场景
|
||||
- 确认无控制台错误
|
||||
|
||||
**Must NOT do**:
|
||||
- 不修改代码（除非发现 bug）
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 3)
|
||||
|
||||
**References**:
|
||||
- 所有已修改的文件
|
||||
|
||||
**Acceptance Criteria**:
|
||||
|
||||
**Manual Execution Verification**:
|
||||
- [ ] 运行 demo: `npm run dev:demo`
|
||||
- [ ] 加载模型后，点击工具栏的"轴向剖切"按钮
|
||||
|
||||
**验证打开弹窗时**:
|
||||
- [ ] 弹窗正常显示
|
||||
- [ ] 控制台输出（按顺序）:
|
||||
1. `[Engine] Activating section axis: x`
|
||||
- [ ] 视觉确认：模型被 X 轴平面剖切（可见内部结构）
|
||||
- [ ] X 按钮显示为激活状态
|
||||
- [ ] 引擎状态确认：
|
||||
```javascript
|
||||
window.bimEngine?.engine.getCurrentSectionAxis() // 预期: 'x'
|
||||
```
|
||||
|
||||
**验证切换轴向**:
|
||||
- [ ] 点击 Y 按钮
|
||||
- 控制台输出（按顺序）:
|
||||
1. `[SectionAxisDialogManager] 切换轴向: y`
|
||||
2. `[Engine] Deactivating section axis: x`
|
||||
3. `[Engine] Activating section axis: y`
|
||||
- 视觉确认：模型截面从 X 轴方向变为 Y 轴方向
|
||||
- Y 按钮显示为激活状态
|
||||
- 引擎状态：`getCurrentSectionAxis()` 返回 `'y'`
|
||||
- [ ] 点击 Z 按钮
|
||||
- 控制台输出类似
|
||||
- 视觉确认：模型截面变为 Z 轴方向
|
||||
- Z 按钮显示为激活状态
|
||||
- 引擎状态：`getCurrentSectionAxis()` 返回 `'z'`
|
||||
|
||||
**验证重复激活（幂等性）**:
|
||||
- [ ] 当前 Z 轴激活，再次点击 Z 按钮
|
||||
- 控制台输出：`[Engine] Section axis z already active, skipping.`
|
||||
- 无额外 API 调用
|
||||
|
||||
**验证隐藏和反向按钮**:
|
||||
- [ ] 点击隐藏按钮 → 控制台输出: `隐藏切换（暂不支持）`
|
||||
- [ ] 点击反向按钮 → 控制台输出: `反向剖切（暂不支持）`
|
||||
- [ ] 这两个按钮点击后不报错
|
||||
|
||||
**验证关闭弹窗**:
|
||||
- [ ] 关闭弹窗
|
||||
- 控制台输出: `[Engine] Deactivating all section axis`
|
||||
- 视觉确认：模型恢复完整显示
|
||||
- 工具栏按钮状态恢复
|
||||
- 引擎状态：`getCurrentSectionAxis()` 返回 `null`
|
||||
|
||||
**验证控制台**:
|
||||
- [ ] 无 JavaScript 错误
|
||||
- [ ] 日志输出顺序正确
|
||||
|
||||
**边界情况验证**:
|
||||
- [ ] 快速连续切换 X→Y→Z→X，状态和视觉效果正确
|
||||
- [ ] 关闭弹窗后再次打开，默认激活 X 轴（而不是上次的轴向）
|
||||
- [ ] 如果看不到明显变化，检查模型是否加载完成
|
||||
|
||||
**Evidence Required**:
|
||||
- [ ] 每个验证步骤的结果记录
|
||||
- [ ] 控制台日志截图
|
||||
- [ ] 引擎状态确认截图
|
||||
|
||||
**Commit**: NO (验证任务)
|
||||
|
||||
---
|
||||
|
||||
## Commit Strategy
|
||||
|
||||
| After Task | Message | Files | Verification |
|
||||
|------------|---------|-------|--------------|
|
||||
| 1+2 | `feat(engine): add section axis clipping methods` | engine/index.ts, engine-manager.ts | `npm run build` |
|
||||
| 3 | `feat(section-axis): integrate dialog manager with engine methods` | section-axis-dialog-manager.ts | `npm run build` |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Verification Commands
|
||||
```bash
|
||||
# 构建验证
|
||||
npm run build # Expected: 无错误
|
||||
|
||||
# 运行 demo
|
||||
npm run dev:demo # Expected: 服务启动
|
||||
```
|
||||
|
||||
### Final Checklist
|
||||
- [x] 打开弹窗自动激活 X 轴剖切
|
||||
- [x] X/Y/Z 轴向切换正常（带切换日志）
|
||||
- [x] 重复激活同一轴向时静默返回（幂等）
|
||||
- [x] 关闭弹窗停用剖切
|
||||
- [x] 隐藏/反向按钮点击不报错（输出"暂不支持"日志）
|
||||
- [x] 控制台无 JavaScript 错误
|
||||
- [x] 所有方法有 JSDoc 中文注释
|
||||
- [x] `npm run build` 无错误
|
||||
627
.sisyphus/plans/walk-mode-api-integration.md
Normal file
627
.sisyphus/plans/walk-mode-api-integration.md
Normal file
@@ -0,0 +1,627 @@
|
||||
# 漫游功能 API 对接工作计划
|
||||
|
||||
## Context
|
||||
|
||||
### Original Request
|
||||
继续漫游功能的接口对接，将 SDK UI 组件的回调对接到底层 3D 引擎 API。
|
||||
|
||||
### 前置工作（已完成）
|
||||
- 剖切盒 (Section Box) 接口对接 ✅
|
||||
- Toolbar 按钮调用链文档创建 ✅
|
||||
|
||||
### 底层 API 分析
|
||||
|
||||
#### controlModule 方法
|
||||
> 文件位置: `bim_engine_base/src/core/v2/modules/controlModule.ts`
|
||||
|
||||
| 方法 | 签名 | 说明 |
|
||||
|------|------|------|
|
||||
| `switchFirstPersonMode()` | `public switchFirstPersonMode(): void` | 切换到第一人称漫游模式，禁用轨道控制器 |
|
||||
| `switchDefaultMode()` | `public switchDefaultMode(): void` | 切换回默认轨道控制模式 |
|
||||
|
||||
#### firstPersonControls 属性
|
||||
> 文件位置: `bim_engine_base/src/core/v2/controls/firstPersonCameraControl.js`
|
||||
|
||||
| 属性 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `applyGravity` | `boolean` | `false` | 重力开关 |
|
||||
| `applyCollision` | `boolean` | `true` | 碰撞检测开关 |
|
||||
| `moveSpeed` | `number` | `0.02` | 移动速度 |
|
||||
| `lookSpeed` | `number` | `0.008` | 视角转动速度 |
|
||||
| `playerHeight` | `number` | `1.4` | 玩家身高 |
|
||||
| `maxRotateX` | `number` | `0.8` | 相机翻转最大限度 |
|
||||
| `g` | `number` | `9.8` | 重力加速度 |
|
||||
| `positionEasing` | `boolean` | `true` | 位置缓动 |
|
||||
| `gravityMinHeight` | `boolean` | `true` | 重力最低点限制 |
|
||||
|
||||
---
|
||||
|
||||
### UI 回调对接分析
|
||||
|
||||
#### V2 底层能力说明
|
||||
|
||||
> **重要**: V2 版本的 `controlModule.ts` 使用简化版 `firstPersonCameraControl.js`，
|
||||
> 而非旧版 `FirstPersonControls_.js`（包含人物模型、小地图等完整功能）。
|
||||
>
|
||||
> **因此 V2 仅支持第一人称漫游的基本功能，不支持第三人称漫游、人物模型等高级功能。**
|
||||
|
||||
#### 本次对接范围
|
||||
|
||||
| UI 回调 | 对应功能 | 底层 API | 对接状态 |
|
||||
|---------|---------|---------|----------|
|
||||
| `onWalkModeToggle` | **第一人称漫游** | ✅ `switchFirstPersonMode()` | ✅ **本次对接** |
|
||||
| `onSpeedChange` | **移动速度** | ✅ `moveSpeed` | ✅ **本次对接** |
|
||||
| `onGravityToggle` | **重力** | ✅ `applyGravity` | ✅ **本次对接** |
|
||||
| `onCollisionToggle` | **碰撞** | ✅ `applyCollision` | ✅ **本次对接** |
|
||||
|
||||
#### 暂不接入 (保持现状)
|
||||
|
||||
| UI 回调 | 对应功能 | 原因 |
|
||||
|---------|---------|------|
|
||||
| `onPlanViewToggle` | 地图 | 底层无 API，保持现有 UI 控制 |
|
||||
| `onPathModeToggle` | 路径漫游 | 底层无 API，保持现有 UI 控制 |
|
||||
| `onWalkModeChange` | 行走/跑步模式 | 第三人称功能，暂不接入 |
|
||||
| `onCharacterModelChange` | 人物模型 | 第三人称功能，暂不接入 |
|
||||
| `onExit` | 退出 | 已实现，无需修改 |
|
||||
|
||||
#### 本次对接的 4 个功能调用链
|
||||
|
||||
> 标注说明: `[SDK]` = SDK 层代码, `[底层]` = bim_engine_base 底层引擎
|
||||
|
||||
**1. 第一人称漫游模式开关 (`onWalkModeToggle`)**
|
||||
```
|
||||
用户点击「漫游」按钮
|
||||
→ [SDK] WalkControlPanel.onWalkModeToggle(isActive)
|
||||
→ [SDK] WalkControlManager.onWalkModeToggle
|
||||
→ [SDK] EngineManager.activateFirstPersonMode() / deactivateFirstPersonMode()
|
||||
→ [SDK] Engine.activateFirstPersonMode() / deactivateFirstPersonMode()
|
||||
→ [底层] engine.controlModule.switchFirstPersonMode() / switchDefaultMode()
|
||||
```
|
||||
|
||||
**2. 速度调节 (`onSpeedChange`)**
|
||||
```
|
||||
用户点击「+/-」速度按钮 (UI: 1-10)
|
||||
→ [SDK] WalkControlPanel.onSpeedChange(speed)
|
||||
→ [SDK] WalkControlManager.onSpeedChange
|
||||
→ [SDK] EngineManager.setWalkSpeed(speed * 0.01) // 值转换: UI 1-10 → 引擎 0.01-0.1
|
||||
→ [SDK] Engine.setWalkSpeed(speed)
|
||||
→ [底层] engine.controlModule.firstPersonControls.moveSpeed = speed
|
||||
```
|
||||
|
||||
**3. 重力开关 (`onGravityToggle`)**
|
||||
```
|
||||
用户点击「重力」复选框
|
||||
→ [SDK] WalkControlPanel.onGravityToggle(enabled)
|
||||
→ [SDK] WalkControlManager.onGravityToggle
|
||||
→ [SDK] EngineManager.setWalkGravity(enabled)
|
||||
→ [SDK] Engine.setWalkGravity(enabled)
|
||||
→ [底层] engine.controlModule.firstPersonControls.applyGravity = enabled
|
||||
```
|
||||
|
||||
**4. 碰撞检测开关 (`onCollisionToggle`)**
|
||||
```
|
||||
用户点击「碰撞」复选框
|
||||
→ [SDK] WalkControlPanel.onCollisionToggle(enabled)
|
||||
→ [SDK] WalkControlManager.onCollisionToggle
|
||||
→ [SDK] EngineManager.setWalkCollision(enabled)
|
||||
→ [SDK] Engine.setWalkCollision(enabled)
|
||||
→ [底层] engine.controlModule.firstPersonControls.applyCollision = enabled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### 暂不接入的功能 (保持现状)
|
||||
|
||||
| 功能 | 说明 |
|
||||
|------|------|
|
||||
| 地图/平面图 | 底层无 API，保持现有 SDK 层 UI 控制 |
|
||||
| 路径漫游 | 底层无 API，保持现有 SDK 层 UI 控制 |
|
||||
| 行走/跑步模式 | 第三人称功能，暂不接入 |
|
||||
| 角色模型切换 | 第三人称功能，暂不接入 |
|
||||
|
||||
---
|
||||
|
||||
## Work Objectives
|
||||
|
||||
### Core Objective
|
||||
将漫游控制面板的 UI 回调对接到底层 3D 引擎的第一人称控制器 API。
|
||||
|
||||
### Concrete Deliverables
|
||||
- `engine/src/components/engine/index.ts` - 新增 5 个漫游相关方法
|
||||
- `engine/src/managers/engine-manager.ts` - 暴露漫游方法到管理器
|
||||
- `engine/src/managers/walk-control-manager.ts` - 修改回调对接实际 API
|
||||
- `.sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md` - 更新漫游部分文档
|
||||
|
||||
### Definition of Done
|
||||
- [x] `bun run build` 构建成功
|
||||
- [x] 第一人称漫游模式开关可正常切换
|
||||
- [x] 速度调节可正常控制
|
||||
- [x] 重力开关可正常控制
|
||||
- [x] 碰撞开关可正常控制
|
||||
- [x] 调用链文档已更新
|
||||
|
||||
### Must Have
|
||||
- 第一人称漫游模式开关（switchFirstPersonMode / switchDefaultMode）
|
||||
- 移动速度调节（moveSpeed）
|
||||
- 重力开关（applyGravity）
|
||||
- 碰撞检测开关（applyCollision）
|
||||
- 所有注释使用中文
|
||||
|
||||
### Must NOT Have (Guardrails)
|
||||
- 不要实现第三人称漫游相关功能（角色模型、行走/跑步模式）
|
||||
- 不要修改底层引擎代码（只修改 SDK 层）
|
||||
- 不要添加新的 npm 依赖
|
||||
- 不要修改 onPlanViewToggle/onPathModeToggle/onWalkModeChange/onCharacterModelChange
|
||||
|
||||
---
|
||||
|
||||
## Verification Strategy
|
||||
|
||||
### Test Decision
|
||||
- **Infrastructure exists**: NO（无自动化测试）
|
||||
- **User wants tests**: Manual-only
|
||||
- **Framework**: none
|
||||
|
||||
### Manual QA
|
||||
每个 TODO 完成后，需要手动验证：
|
||||
1. 运行 `bun run build` 确保无编译错误
|
||||
2. 在 playground 中测试功能
|
||||
|
||||
---
|
||||
|
||||
## Task Flow
|
||||
|
||||
```
|
||||
Task 1 (Engine 新增方法)
|
||||
↓
|
||||
Task 2 (EngineManager 暴露方法)
|
||||
↓
|
||||
Task 3 (WalkControlManager 对接回调)
|
||||
↓
|
||||
Task 4 (更新文档)
|
||||
↓
|
||||
Task 5 (构建验证)
|
||||
```
|
||||
|
||||
## Parallelization
|
||||
|
||||
| Task | Depends On | Reason |
|
||||
|------|------------|--------|
|
||||
| 2 | 1 | EngineManager 需要调用 Engine 的方法 |
|
||||
| 3 | 2 | WalkControlManager 需要调用 EngineManager 的方法 |
|
||||
| 4 | 3 | 文档需要反映最终实现 |
|
||||
| 5 | 1,2,3 | 构建验证需要所有代码完成 |
|
||||
|
||||
---
|
||||
|
||||
## TODOs
|
||||
|
||||
- [x] 1. 在 Engine 组件中新增漫游相关方法
|
||||
|
||||
**What to do**:
|
||||
在 `engine/src/components/engine/index.ts` 中的剖切盒功能区块后添加：
|
||||
|
||||
```typescript
|
||||
// ==================== 漫游功能 ====================
|
||||
|
||||
/** 漫游模式是否激活 */
|
||||
private isWalkModeActive: boolean = false;
|
||||
|
||||
/**
|
||||
* 激活第一人称漫游模式
|
||||
* @remarks 切换到第一人称控制器，禁用轨道控制器
|
||||
*/
|
||||
public activateFirstPersonMode(): void {
|
||||
if (!this._isInitialized || !this.engine) {
|
||||
console.error('[Engine] Cannot activate first person mode: engine not initialized.');
|
||||
return;
|
||||
}
|
||||
|
||||
if (!this.engine.controlModule) {
|
||||
console.error('[Engine] Control module not available.');
|
||||
return;
|
||||
}
|
||||
|
||||
if (this.isWalkModeActive) {
|
||||
console.log('[Engine] First person mode already active, skipping.');
|
||||
return;
|
||||
}
|
||||
|
||||
console.log('[Engine] Activating first person mode');
|
||||
this.engine.controlModule.switchFirstPersonMode();
|
||||
this.isWalkModeActive = true;
|
||||
}
|
||||
|
||||
/**
|
||||
* 停用第一人称漫游模式
|
||||
* @remarks 切换回轨道控制器
|
||||
*/
|
||||
public deactivateFirstPersonMode(): void {
|
||||
if (!this._isInitialized || !this.engine?.controlModule) {
|
||||
return;
|
||||
}
|
||||
|
||||
if (!this.isWalkModeActive) {
|
||||
return;
|
||||
}
|
||||
|
||||
console.log('[Engine] Deactivating first person mode');
|
||||
this.engine.controlModule.switchDefaultMode();
|
||||
this.isWalkModeActive = false;
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置漫游移动速度
|
||||
* @param speed 移动速度（默认 0.02）
|
||||
*/
|
||||
public setWalkSpeed(speed: number): void {
|
||||
if (!this._isInitialized || !this.engine?.controlModule?.firstPersonControls) {
|
||||
console.error('[Engine] Cannot set walk speed: engine not initialized.');
|
||||
return;
|
||||
}
|
||||
|
||||
console.log('[Engine] Setting walk speed:', speed);
|
||||
this.engine.controlModule.firstPersonControls.moveSpeed = speed;
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置漫游重力开关
|
||||
* @param enabled 是否启用重力
|
||||
*/
|
||||
public setWalkGravity(enabled: boolean): void {
|
||||
if (!this._isInitialized || !this.engine?.controlModule?.firstPersonControls) {
|
||||
console.error('[Engine] Cannot set walk gravity: engine not initialized.');
|
||||
return;
|
||||
}
|
||||
|
||||
console.log('[Engine] Setting walk gravity:', enabled);
|
||||
this.engine.controlModule.firstPersonControls.applyGravity = enabled;
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置漫游碰撞检测开关
|
||||
* @param enabled 是否启用碰撞检测
|
||||
*/
|
||||
public setWalkCollision(enabled: boolean): void {
|
||||
if (!this._isInitialized || !this.engine?.controlModule?.firstPersonControls) {
|
||||
console.error('[Engine] Cannot set walk collision: engine not initialized.');
|
||||
return;
|
||||
}
|
||||
|
||||
console.log('[Engine] Setting walk collision:', enabled);
|
||||
this.engine.controlModule.firstPersonControls.applyCollision = enabled;
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取漫游模式是否激活
|
||||
* @returns 是否处于漫游模式
|
||||
*/
|
||||
public isFirstPersonModeActive(): boolean {
|
||||
return this.isWalkModeActive;
|
||||
}
|
||||
|
||||
// ==================== 结束：漫游功能 ====================
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改其他功能区块的代码
|
||||
- 不要添加角色模型相关的方法
|
||||
|
||||
**Parallelizable**: NO (其他任务依赖此任务)
|
||||
|
||||
**References**:
|
||||
- `engine/src/components/engine/index.ts:508-583` - 剖切盒功能区块（作为插入位置参考）
|
||||
- `bim_engine_base/src/core/v2/modules/controlModule.ts:62-84` - 底层 switchFirstPersonMode/switchDefaultMode 方法
|
||||
- `bim_engine_base/src/core/v2/controls/firstPersonCameraControl.js:24-30` - 底层 firstPersonControls 属性
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [x] 新增 `isWalkModeActive` 私有属性
|
||||
- [x] 新增 `activateFirstPersonMode()` 方法
|
||||
- [x] 新增 `deactivateFirstPersonMode()` 方法
|
||||
- [x] 新增 `setWalkSpeed(speed: number)` 方法
|
||||
- [x] 新增 `setWalkGravity(enabled: boolean)` 方法
|
||||
- [x] 新增 `setWalkCollision(enabled: boolean)` 方法
|
||||
- [x] 新增 `isFirstPersonModeActive()` 方法
|
||||
- [x] 所有方法注释使用中文
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(engine): 新增漫游功能方法`
|
||||
- Files: `src/components/engine/index.ts`
|
||||
|
||||
---
|
||||
|
||||
- [x] 2. 在 EngineManager 中暴露漫游方法
|
||||
|
||||
**What to do**:
|
||||
在 `engine/src/managers/engine-manager.ts` 中的 `activateZoomBox` 方法后添加：
|
||||
|
||||
```typescript
|
||||
// ==================== 漫游功能 ====================
|
||||
|
||||
/** 激活第一人称漫游模式 */
|
||||
public activateFirstPersonMode(): void {
|
||||
if (!this.engineInstance) {
|
||||
console.warn('[EngineManager] 3D Engine not initialized.');
|
||||
return;
|
||||
}
|
||||
this.engineInstance.activateFirstPersonMode();
|
||||
}
|
||||
|
||||
/** 停用第一人称漫游模式 */
|
||||
public deactivateFirstPersonMode(): void {
|
||||
if (!this.engineInstance) {
|
||||
return;
|
||||
}
|
||||
this.engineInstance.deactivateFirstPersonMode();
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置漫游移动速度
|
||||
* @param speed 移动速度
|
||||
*/
|
||||
public setWalkSpeed(speed: number): void {
|
||||
if (!this.engineInstance) {
|
||||
console.warn('[EngineManager] 3D Engine not initialized.');
|
||||
return;
|
||||
}
|
||||
this.engineInstance.setWalkSpeed(speed);
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置漫游重力开关
|
||||
* @param enabled 是否启用重力
|
||||
*/
|
||||
public setWalkGravity(enabled: boolean): void {
|
||||
if (!this.engineInstance) {
|
||||
console.warn('[EngineManager] 3D Engine not initialized.');
|
||||
return;
|
||||
}
|
||||
this.engineInstance.setWalkGravity(enabled);
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置漫游碰撞检测开关
|
||||
* @param enabled 是否启用碰撞检测
|
||||
*/
|
||||
public setWalkCollision(enabled: boolean): void {
|
||||
if (!this.engineInstance) {
|
||||
console.warn('[EngineManager] 3D Engine not initialized.');
|
||||
return;
|
||||
}
|
||||
this.engineInstance.setWalkCollision(enabled);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取漫游模式是否激活
|
||||
* @returns 是否处于漫游模式
|
||||
*/
|
||||
public isFirstPersonModeActive(): boolean {
|
||||
if (!this.engineInstance) {
|
||||
return false;
|
||||
}
|
||||
return this.engineInstance.isFirstPersonModeActive();
|
||||
}
|
||||
|
||||
// ==================== 结束：漫游功能 ====================
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改其他管理器方法
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 1)
|
||||
|
||||
**References**:
|
||||
- `engine/src/managers/engine-manager.ts:242-249` - activateZoomBox 方法（作为插入位置参考）
|
||||
- `engine/src/components/engine/index.ts` - Task 1 新增的方法
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [x] 新增 `activateFirstPersonMode()` 方法
|
||||
- [x] 新增 `deactivateFirstPersonMode()` 方法
|
||||
- [x] 新增 `setWalkSpeed(speed: number)` 方法
|
||||
- [x] 新增 `setWalkGravity(enabled: boolean)` 方法
|
||||
- [x] 新增 `setWalkCollision(enabled: boolean)` 方法
|
||||
- [x] 新增 `isFirstPersonModeActive()` 方法
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(engine-manager): 暴露漫游功能方法`
|
||||
- Files: `src/managers/engine-manager.ts`
|
||||
|
||||
---
|
||||
|
||||
- [x] 3. 修改 WalkControlManager 回调对接实际 API
|
||||
|
||||
**What to do**:
|
||||
修改 `engine/src/managers/walk-control-manager.ts` 中的 4 个回调函数，对接到 EngineManager：
|
||||
|
||||
```typescript
|
||||
// ============ 本次需要修改的 4 个回调 ============
|
||||
|
||||
// 1. onWalkModeToggle - 对接底层第一人称漫游 API
|
||||
onWalkModeToggle: (isActive) => {
|
||||
console.log('[WalkControl] 第一人称漫游:', isActive);
|
||||
if (isActive) {
|
||||
this.pathManager?.hide();
|
||||
this.registry.engine3d?.activateFirstPersonMode();
|
||||
} else {
|
||||
this.registry.engine3d?.deactivateFirstPersonMode();
|
||||
}
|
||||
this.emit('walk:walk-mode-toggle', { isActive });
|
||||
},
|
||||
|
||||
// 2. onSpeedChange - 对接底层 moveSpeed
|
||||
onSpeedChange: (speed) => {
|
||||
console.log('[WalkControl] 速度变化:', speed);
|
||||
// 将 UI 速度值转换为引擎速度值（UI: 1-10, 引擎: 0.01-0.1）
|
||||
const engineSpeed = speed * 0.01;
|
||||
this.registry.engine3d?.setWalkSpeed(engineSpeed);
|
||||
this.emit('walk:speed-change', { speed });
|
||||
},
|
||||
|
||||
// 3. onGravityToggle - 对接底层 applyGravity
|
||||
onGravityToggle: (enabled) => {
|
||||
console.log('[WalkControl] 重力:', enabled);
|
||||
this.registry.engine3d?.setWalkGravity(enabled);
|
||||
this.emit('walk:gravity-toggle', { enabled });
|
||||
},
|
||||
|
||||
// 4. onCollisionToggle - 对接底层 applyCollision
|
||||
onCollisionToggle: (enabled) => {
|
||||
console.log('[WalkControl] 碰撞:', enabled);
|
||||
this.registry.engine3d?.setWalkCollision(enabled);
|
||||
this.emit('walk:collision-toggle', { enabled });
|
||||
},
|
||||
|
||||
// ============ 以下回调保持现状，不修改 ============
|
||||
// onPlanViewToggle - 保持现有 UI 控制
|
||||
// onPathModeToggle - 保持现有 UI 控制
|
||||
// onWalkModeChange - 第三人称功能，暂不接入
|
||||
// onCharacterModelChange - 第三人称功能，暂不接入
|
||||
// onExit - 已实现
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改 onPlanViewToggle（已正确对接到 MapDialogManager，底层无 API）
|
||||
- 不要修改 onPathModeToggle（已正确对接到 WalkPathDialogManager，底层无 API）
|
||||
- 不要尝试实现角色模型的实际切换（底层不支持）
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 2)
|
||||
|
||||
**References**:
|
||||
- `engine/src/managers/walk-control-manager.ts:57-81` - 当前的回调实现
|
||||
- `engine/src/managers/engine-manager.ts` - Task 2 新增的方法
|
||||
- `engine/src/components/walk-control-panel/types.ts` - 回调类型定义
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [x] `onWalkModeToggle` 调用 `activateFirstPersonMode()` / `deactivateFirstPersonMode()`
|
||||
- [x] `onSpeedChange` 调用 `setWalkSpeed()` 并进行值转换 (UI 1-10 → 引擎 0.01-0.1)
|
||||
- [x] `onGravityToggle` 调用 `setWalkGravity()`
|
||||
- [x] `onCollisionToggle` 调用 `setWalkCollision()`
|
||||
- [x] 其他回调保持现状不修改
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `feat(walk-control): 对接漫游功能到底层 API`
|
||||
- Files: `src/managers/walk-control-manager.ts`
|
||||
|
||||
---
|
||||
|
||||
- [x] 4. 更新 Toolbar 调用链文档
|
||||
|
||||
**What to do**:
|
||||
更新 `.sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md` 中的漫游部分，补充完整的调用链：
|
||||
|
||||
```markdown
|
||||
## 5. 漫游 (Walk) - 第一人称漫游
|
||||
|
||||
> 标注说明: `[SDK]` = SDK 层代码, `[底层]` = bim_engine_base 底层引擎
|
||||
|
||||
### 5.1 第一人称漫游模式开关
|
||||
```
|
||||
UI 点击漫游按钮
|
||||
→ [SDK] WalkControlPanel.onWalkModeToggle(isActive)
|
||||
→ [SDK] WalkControlManager.onWalkModeToggle
|
||||
→ [SDK] EngineManager.activateFirstPersonMode() / deactivateFirstPersonMode()
|
||||
→ [SDK] Engine.activateFirstPersonMode() / deactivateFirstPersonMode()
|
||||
→ [底层] engine.controlModule.switchFirstPersonMode() / switchDefaultMode()
|
||||
```
|
||||
|
||||
### 5.2 速度调节
|
||||
```
|
||||
UI 速度按钮 (1-10)
|
||||
→ [SDK] WalkControlPanel.onSpeedChange(speed)
|
||||
→ [SDK] WalkControlManager.onSpeedChange
|
||||
→ [SDK] EngineManager.setWalkSpeed(speed * 0.01) // 值转换: UI 1-10 → 引擎 0.01-0.1
|
||||
→ [SDK] Engine.setWalkSpeed(speed)
|
||||
→ [底层] engine.controlModule.firstPersonControls.moveSpeed = speed
|
||||
```
|
||||
|
||||
### 5.3 重力开关
|
||||
```
|
||||
UI 重力复选框
|
||||
→ [SDK] WalkControlPanel.onGravityToggle(enabled)
|
||||
→ [SDK] WalkControlManager.onGravityToggle
|
||||
→ [SDK] EngineManager.setWalkGravity(enabled)
|
||||
→ [SDK] Engine.setWalkGravity(enabled)
|
||||
→ [底层] engine.controlModule.firstPersonControls.applyGravity = enabled
|
||||
```
|
||||
|
||||
### 5.4 碰撞检测开关
|
||||
```
|
||||
UI 碰撞复选框
|
||||
→ [SDK] WalkControlPanel.onCollisionToggle(enabled)
|
||||
→ [SDK] WalkControlManager.onCollisionToggle
|
||||
→ [SDK] EngineManager.setWalkCollision(enabled)
|
||||
→ [SDK] Engine.setWalkCollision(enabled)
|
||||
→ [底层] engine.controlModule.firstPersonControls.applyCollision = enabled
|
||||
```
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要修改其他功能的文档
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 3)
|
||||
|
||||
**References**:
|
||||
- `.sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md` - 现有调用链文档
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [x] 第一人称漫游模式开关调用链已更新
|
||||
- [x] 速度调节调用链已更新
|
||||
- [x] 重力开关调用链已更新
|
||||
- [x] 碰撞检测开关调用链已更新
|
||||
|
||||
**Commit**: YES
|
||||
- Message: `docs: 更新漫游功能调用链文档`
|
||||
- Files: `.sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md`
|
||||
|
||||
---
|
||||
|
||||
- [x] 5. 构建验证
|
||||
|
||||
**What to do**:
|
||||
运行构建命令验证代码无误：
|
||||
|
||||
```bash
|
||||
bun run build
|
||||
```
|
||||
|
||||
**Must NOT do**:
|
||||
- 不要跳过构建验证
|
||||
|
||||
**Parallelizable**: NO (依赖 Task 1, 2, 3)
|
||||
|
||||
**References**:
|
||||
- `package.json` - 构建脚本配置
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- [x] `bun run build` 执行成功，无错误
|
||||
- [x] 无 TypeScript 类型错误
|
||||
- [x] dist 目录生成正常
|
||||
|
||||
**Commit**: NO (无代码变更)
|
||||
|
||||
---
|
||||
|
||||
## Commit Strategy
|
||||
|
||||
| After Task | Message | Files | Verification |
|
||||
|------------|---------|-------|--------------|
|
||||
| 1 | `feat(engine): 新增漫游功能方法` | src/components/engine/index.ts | bun run build |
|
||||
| 2 | `feat(engine-manager): 暴露漫游功能方法` | src/managers/engine-manager.ts | bun run build |
|
||||
| 3 | `feat(walk-control): 对接漫游功能到底层 API` | src/managers/walk-control-manager.ts | bun run build |
|
||||
| 4 | `docs: 更新漫游功能调用链文档` | .sisyphus/drafts/TOOLBAR_API_CALLCHAIN.md | N/A |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Verification Commands
|
||||
```bash
|
||||
bun run build # Expected: BUILD SUCCESS
|
||||
```
|
||||
|
||||
### Final Checklist
|
||||
- [x] Engine 组件新增 6 个漫游方法（第一人称漫游 + 速度 + 重力 + 碰撞）
|
||||
- [x] EngineManager 暴露 6 个漫游方法
|
||||
- [x] WalkControlManager 4 个回调对接完成（onWalkModeToggle/onSpeedChange/onGravityToggle/onCollisionToggle）
|
||||
- [x] 调用链文档已更新
|
||||
- [x] 构建成功
|
||||
Reference in New Issue
Block a user