# 漫游功能 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. **完整文档**: 调用链文档是关键，方便后续维护