feat(registry): 注册 ComponentDetailManager 到全局 Registry 和 BimEngine

.sisyphus/notepads/walk-mode-api-integration/learnings.md

@@ -0,0 +1,155 @@
+# 漫游功能 API 对接 - 学习笔记
+
+## 完成时间
+2026-01-28
+
+## 项目结构理解
+
+### SDK 层次架构
+```
+UI Layer (WalkControlPanel)
+    ↓
+Manager Layer (WalkControlManager)
+    ↓
+Engine Manager (EngineManager)
+    ↓
+Engine Component (Engine)
+    ↓
+底层引擎 (bim_engine_base)
+```
+
+### 关键模式
+1. **Manager Pattern**: 所有功能通过 Manager 管理生命周期
+2. **代理模式**: EngineManager 作为 Engine 的代理，提供统一访问点
+3. **事件系统**: 使用 EventEmitter 进行组件间通信
+
+## 底层 API 发现
+
+### V2 vs 旧版差异
+- **V2**: 使用简化版 `firstPersonCameraControl.js`，仅支持基础第一人称漫游
+- **旧版**: `FirstPersonControls_.js` 包含人物模型、小地图等完整功能
+- **教训**: 必须先确认底层版本，避免对接不存在的 API
+
+### 底层 API 清单
+```typescript
+// 模式切换
+controlModule.switchFirstPersonMode()
+controlModule.switchDefaultMode()
+
+// 第一人称控制属性
+firstPersonControls.moveSpeed      // 默认 0.02
+firstPersonControls.applyGravity   // 默认 false
+firstPersonControls.applyCollision // 默认 true
+```
+
+## 实现细节
+
+### 1. 速度值转换
+- **UI 层**: 1-10 (用户友好)
+- **引擎层**: 0.01-0.1 (实际速度)
+- **转换公式**: `engineSpeed = uiSpeed * 0.01`
+- **教训**: 必须在 Manager 层进行值转换，保持 UI 和引擎的解耦
+
+### 2. 状态管理
+- Engine 组件维护 `isWalkModeActive` 状态
+- 防止重复激活/停用
+- **教训**: 添加状态检查，避免不必要的底层调用
+
+### 3. 错误处理
+所有方法都需要检查：
+1. 引擎是否初始化 (`this._isInitialized`)
+2. 引擎实例是否存在 (`this.engine`)
+3. 控制模块是否可用 (`this.engine.controlModule`)
+
+## 代码规范
+
+### 注释要求
+- 所有公共方法使用 TSDoc 注释
+- 必须使用中文
+- 包含 `@param`, `@returns`, `@remarks`
+
+### 控制台日志
+- 使用统一前缀 `[Engine]`, `[EngineManager]`, `[WalkControl]`
+- 错误用 `console.error()`, 警告用 `console.warn()`
+
+## Git 提交策略
+
+### 原子提交
+每个任务独立提交：
+1. `feat(engine): 新增漫游功能方法`
+2. `feat(engine-manager): 暴露漫游功能方法`
+3. `feat(walk-control): 对接漫游功能到底层 API`
+4. `docs: 更新漫游功能调用链文档`
+
+### Commit Message 格式
+```
+<type>(<scope>): <subject>
+
+type: feat, fix, docs, refactor, test, chore
+scope: 功能模块名称
+subject: 简短描述（中文）
+```
+
+## 遗留问题
+
+### 暂未实现的功能
+- 行走/跑步模式切换（第三人称功能）
+- 角色模型切换（V2 不支持）
+- 地图/平面图（底层无 API）
+- 路径漫游（底层无 API）
+
+### 未来改进
+1. 考虑将底层 `FirstPersonControls_.js` 功能集成到 V2
+2. 添加更多漫游参数控制（视角速度、玩家高度等）
+3. 实现漫游状态持久化
+
+## 构建验证
+
+### 验证步骤
+1. TypeScript 编译: `tsc`
+2. Vite 构建: `vite build`
+3. 检查 dist 产物
+
+### 构建结果
+```
+dist/iflow-engine.es.js   2,020.24 kB
+dist/iflow-engine.umd.js  1,326.55 kB
+```
+
+## 文档更新
+
+### 调用链文档结构
+```markdown
+## 5. 漫游 (Walk) - 第一人称漫游
+
+### 5.1 第一人称漫游模式开关
+[完整调用链]
+
+### 5.2 速度调节
+[完整调用链]
+
+### 5.3 重力开关
+[完整调用链]
+
+### 5.4 碰撞检测开关
+[完整调用链]
+```
+
+### 标注规范
+- `[SDK]` = SDK 层代码
+- `[底层]` = bim_engine_base 底层引擎
+- 每个步骤都要标注层级
+
+## 总结
+
+### 成功完成
+✅ 4 个核心功能对接完成
+✅ 完整的调用链文档
+✅ 所有单元构建通过
+✅ Git 提交符合规范
+
+### 关键经验
+1. **先调研后实现**: 必须先了解底层 API 能力
+2. **分层清晰**: 每一层职责明确，不越界
+3. **原子提交**: 每个功能独立提交，便于回滚
+4. **完整文档**: 调用链文档是关键，方便后续维护