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

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

@@ -0,0 +1,89 @@
+# 架构决策记录
+
+## 2026-01-28 - 漫游功能 API 对接
+
+### 决策背景
+需要将漫游控制面板的 UI 回调对接到底层 3D 引擎的第一人称控制器 API。
+
+### 关键决策
+
+#### 1. 只对接第一人称漫游基础功能
+**决策**: 本次只对接 4 个核心功能：
+- 第一人称漫游模式开关
+- 速度调节
+- 重力开关
+- 碰撞检测开关
+
+**理由**:
+- V2 底层引擎只支持基础第一人称漫游
+- 第三人称漫游、角色模型等功能需要底层集成 `FirstPersonControls_.js`
+- 地图和路径漫游底层无对应 API
+
+**影响**:
+- UI 层保留了完整功能界面（为未来扩展预留）
+- 暂不支持的功能保持现有行为（UI 控制或控制台输出）
+
+#### 2. 速度值在 Manager 层转换
+**决策**: 在 `WalkControlManager` 层进行 UI 速度值到引擎速度值的转换
+
+**理由**:
+- UI 层使用 1-10 的用户友好范围
+- 引擎层需要 0.01-0.1 的实际速度值
+- Manager 层负责适配不同层级的数据格式
+
+**实现**:
+```typescript
+const engineSpeed = speed * 0.01;
+this.registry.engine3d?.setWalkSpeed(engineSpeed);
+```
+
+#### 3. 状态管理在 Engine 组件
+**决策**: 在 Engine 组件维护 `isWalkModeActive` 状态
+
+**理由**:
+- Engine 组件是底层引擎的封装层
+- 需要防止重复激活/停用导致的底层调用混乱
+- 其他组件可通过 `isFirstPersonModeActive()` 查询状态
+
+#### 4. 所有注释使用中文
+**决策**: 公共 API 的 TSDoc 注释全部使用中文
+
+**理由**:
+- 项目团队主要使用中文
+- 提高 TypeScript IntelliSense 的可读性
+- 与项目其他部分保持一致
+
+#### 5. 原子提交策略
+**决策**: 每个功能层级独立提交 Git commit
+
+**提交顺序**:
+1. Engine 组件（底层封装）
+2. EngineManager（管理器代理）
+3. WalkControlManager（业务逻辑）
+4. 文档更新
+
+**理由**:
+- 便于代码审查
+- 便于问题回滚
+- 清晰的功能演进历史
+
+### 未来改进方向
+
+#### 1. 底层能力增强
+- 考虑将 `FirstPersonControls_.js` 的功能集成到 V2
+- 支持角色模型切换
+- 支持小地图功能
+
+#### 2. 更多控制参数
+- 视角转动速度 (`lookSpeed`)
+- 玩家身高 (`playerHeight`)
+- 相机翻转限制 (`maxRotateX`)
+
+#### 3. 状态持久化
+- 记住用户的漫游设置
+- 支持配置预设
+
+### 参考资料
+- 底层引擎: `bim_engine_base/src/core/v2/modules/controlModule.ts`
+- 第一人称控制器: `bim_engine_base/src/core/v2/controls/firstPersonCameraControl.js`
+- 旧版实现: `bim_engine_base/src/core/v2/controls/FirstPersonControls_.js`