# 架构决策记录

## 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`