# 馆内导览交互优化改进计划

## 文档信息

- **项目**：深圳自然博物馆智能导览应用
- **模块**：馆内 3D 导览交互
- **创建时间**：2026-06-12
- **状态**：待评审

---

## 背景

当前馆内导览采用**显式"全馆/楼层"手动切换**模式，用户需要点击按钮在"建筑外观"和"楼层内部"之间切换。这个模式功能完整，但与基于缩放距离的自动切换模式相比，交互直觉性较弱。

**现有模式**：
- 进入馆内 3D → 加载建筑外观
- 用户手动点击"楼层"按钮 → 楼层控件出现 → 选择楼层 → 加载楼层内部
- 用户缩放只改变视角距离，不触发模型切换

**目标模式**：
- 进入馆内 3D → 加载建筑外观
- 用户放大到一定距离 → **自动切换**到楼层内部
- 用户缩小到一定距离 → **自动切换**回建筑外观
- 保留手动控制入口作为兜底

---

## 改进目标

1. **增加基于缩放距离的自动视角切换**，提升交互直觉性。
2. **保留手动切换入口**，避免误触和性能抖动。
3. **优化楼层控件可见性**，缩短操作路径。
4. **为未来多层展示预留架构空间**（不在本次实施）。

---

## 改进任务分解

### Phase 1：基础自动切换能力（核心）

**目标**：实现基于缩放距离的建筑外观 ↔ 楼层内部自动切换。

#### Task 1.1：在 ThreeMap 组件实现距离监听与自动切换逻辑

**优先级**：P0  
**预估工作量**：2-3 天  
**风险**：中等（需要调优阈值和滞回参数）

**实现要点**：

1. 监听 `OrbitControls` 的 `change` 事件，而不是每帧检查：
   ```typescript
   controls.addEventListener('change', () => {
     throttledCheckAutoSwitch()
   })
   ```

2. 实现双阈值滞回机制，避免反复切换：
   ```typescript
   const autoSwitchConfig = {
     thresholdLowFactor: 1.0,   // 放大到建筑尺寸 1.0 倍时切换到楼层
     thresholdHighFactor: 1.3,  // 缩小到建筑尺寸 1.3 倍时切换回全馆
     cooldownMs: 2000,          // 切换后冷却 2 秒
     enableAuto: true           // 可配置开关
   }
   ```

3. 增加加载锁和冷却时间：
   ```typescript
   let isAutoSwitchLocked = false
   let lastAutoSwitchTime = 0
   
   const checkAutoSwitch = () => {
     if (!autoSwitchConfig.enableAuto) return
     if (isAutoSwitchLocked) return
     
     const now = Date.now()
     if (now - lastAutoSwitchTime < autoSwitchConfig.cooldownMs) return
     
     const distance = controls.getDistance()
     // ... 判断阈值并切换
   }
   ```

4. 切换时触发事件通知上层：
   ```typescript
   emit('auto-switch', { 
     from: 'overview', 
     to: 'floor', 
     trigger: 'zoom-in',
     distance: number 
   })
   ```

**验证标准**：
- 在建筑外观缩放到近距离，自动切换到默认楼层（L1）。
- 在楼层内部缩放到远距离，自动切换回建筑外观。
- 快速缩放不会触发多次加载。
- 切换过程有 loading 状态提示。

**文件修改**：
- `src/components/map/ThreeMap.vue`：增加自动切换逻辑
- `src/domain/guideModel.ts`：增加自动切换配置类型定义

---

#### Task 1.2：调整首页和 GuideMapShell 配合自动切换

**优先级**：P0  
**预估工作量**：1 天  
**依赖**：Task 1.1

**实现要点**：

1. 监听 `ThreeMap` 的 `auto-switch` 事件，同步 `indoorView` 状态：
   ```typescript
   const handleAutoSwitch = (event: { from: string; to: string }) => {
     if (event.to === 'floor') {
       indoorView.value = 'floor'
     } else {
       indoorView.value = 'overview'
     }
   }
   ```

2. 更新状态标签文案：
   - 自动切换时显示"馆内楼层（自动）"或"馆内全馆（自动）"
   - 手动切换时显示"馆内楼层"或"馆内全馆"

3. 楼层控件可见性调整：
   - 改为 `:show-floor="is3DMode"`，在全馆模式也显示楼层控件
   - 全馆模式下点击楼层，先切换到楼层视图，再加载对应楼层

**验证标准**：
- 自动切换后，顶部状态标签正确更新。
- 全馆模式下可以直接点击楼层控件选择楼层。

**文件修改**：
- `src/pages/index/index.vue`：监听自动切换事件
- `src/components/navigation/GuideMapShell.vue`：调整楼层控件可见性

---

#### Task 1.3：保留"全馆/楼层"手动切换作为兜底

**优先级**：P1  
**预估工作量**：0.5 天  
**依赖**：Task 1.1, 1.2

**实现要点**：

1. 保留现有"全馆/楼层"切换按钮，但调整定位：
   - 不再是主交互入口，而是手动控制和兜底入口。
   - 样式可以调整为更轻量（例如图标按钮，而不是双按钮切换组）。

2. 手动切换时临时禁用自动切换（例如 10 秒）：
   ```typescript
   const handleManualSwitch = (view: 'overview' | 'floor') => {
     // 临时禁用自动切换
     threeMapRef.value?.disableAutoSwitchTemporarily?.(10000)
     
     // 执行手动切换
     if (view === 'overview') {
       void threeMapRef.value?.showOverview?.()
     } else {
       void threeMapRef.value?.switchFloor?.(activeFloorId.value)
     }
     
     indoorView.value = view
   }
   ```

3. 增加设置入口，允许用户永久禁用自动切换（可选）。

**验证标准**：
- 手动切换后，10 秒内不会因缩放触发自动切换。
- 手动切换按钮始终可用。

**文件修改**：
- `src/components/map/ThreeMap.vue`：增加临时禁用自动切换方法
- `src/components/navigation/GuideMapShell.vue`：调整切换按钮样式和行为

---

### Phase 2：交互细节优化（增强）

**目标**：优化自动切换的用户体验细节。

#### Task 2.1：增加视觉过渡和状态提示

**优先级**：P1  
**预估工作量**：1 天  
**依赖**：Task 1.1

**实现要点**：

1. 自动切换时增加淡入淡出过渡：
   ```typescript
   const transitionSwitch = async (loadFn: () => Promise<void>) => {
     // 淡出当前模型
     if (activeModel) {
       await fadeOut(activeModel, 300)
     }
     
     // 加载新模型
     await loadFn()
     
     // 淡入新模型
     if (activeModel) {
       await fadeIn(activeModel, 300)
     }
   }
   ```

2. 切换时显示提示文案：
   - "正在切换到楼层视图..."
   - "正在切换到完整建筑..."

3. 首次自动切换时显示引导提示（Toast）：
   - "已自动切换到楼层内部，您也可以手动控制视图"
   - 提示只显示一次，存储到本地缓存

**验证标准**：
- 切换过程视觉流畅，无突兀感。
- 首次自动切换有引导提示。

**文件修改**：
- `src/components/map/ThreeMap.vue`：增加过渡动画
- `src/pages/index/index.vue`：增加首次引导提示

---

#### Task 2.2：优化阈值和参数

**优先级**：P2  
**预估工作量**：1-2 天（需要实测调优）  
**依赖**：Task 1.1

**实现要点**：

1. 在真实设备（手机、平板）上测试不同阈值的效果：
   - 建筑尺寸的 0.8x / 1.0x / 1.2x
   - 冷却时间 1s / 2s / 3s

2. 针对不同建筑尺寸动态调整阈值：
   ```typescript
   const calculateThresholds = (modelSize: THREE.Vector3) => {
     const maxDim = Math.max(modelSize.x, modelSize.y, modelSize.z, 1)
     
     // 大建筑用较大倍数，小建筑用较小倍数
     const sizeFactor = maxDim > 100 ? 1.2 : 1.0
     
     return {
       low: maxDim * sizeFactor * 0.9,
       high: maxDim * sizeFactor * 1.1
     }
   }
   ```

3. 记录切换频率和用户行为，优化参数。

**验证标准**：
- 移动端测试无误触。
- 切换时机符合用户预期。
- 不会频繁切换导致加载抖动。

**文件修改**：
- `src/components/map/ThreeMap.vue`：优化阈值计算

---

### Phase 3：多层展示支持（未来）

**目标**：支持单层/多层显示模式切换，适配跨层路线展示。

**前置条件**：
- `route_graph` 和 `nav_data` 已接入
- 跨层路线规划能力已实现

#### Task 3.1：扩展 ViewMode 类型和多层加载逻辑

**优先级**：P3（依赖路线能力）  
**预估工作量**：3-4 天

**实现要点**：

1. 扩展 `ViewMode` 类型：
   ```typescript
   type ViewMode = 'overview' | 'single-floor' | 'multi-floor'
   ```

2. 实现 `loadMultiFloor` 方法：
   ```typescript
   const loadMultiFloor = async (floorIds: string[]) => {
     activeView.value = 'multi-floor'
     clearSceneData()
     
     const verticalSpacing = 10 // 楼层间距
     
     for (const [index, floorId] of floorIds.entries()) {
       const floor = floorIndex.value.find(f => f.floorId === floorId)
       if (!floor) continue
       
       const gltf = await loadModel(floorModelUrl(floor), `加载 ${floor.label}`)
       const model = gltf.scene
       model.position.y = index * verticalSpacing
       prepareModel(model)
       scene.add(model)
     }
     
     fitCameraToMultiFloor(floorIds)
   }
   ```

3. 注意性能优化：
   - 多层模型总面数可能很大，需要监控帧率
   - 考虑 LOD（细节层次）或简化模型

**验证标准**：
- 可以同时加载并显示多个楼层。
- 楼层保持合理的垂直间距。
- 帧率在可接受范围（>30fps）。

**文件修改**：
- `src/components/map/ThreeMap.vue`：增加多层加载逻辑
- `src/domain/guideModel.ts`：扩展 ViewMode 类型

---

#### Task 3.2：增加"单层/多层"切换控件

**优先级**：P3  
**预估工作量**：1 天  
**依赖**：Task 3.1

**实现要点**：

1. 在 `GuideMapShell` 增加切换控件：
   ```vue
   <view v-if="mapType === 'indoor' && indoorView === 'floor'" class="floor-display-mode">
     <view class="mode-item" :class="{ active: floorDisplayMode === 'single' }">
       <text>单层</text>
     </view>
     <view class="mode-item" :class="{ active: floorDisplayMode === 'multi' }">
       <text>多层</text>
     </view>
   </view>
   ```

2. 多层模式下显示楼层选择器，支持多选：
   - 用户可以勾选要同时显示的楼层（例如 B2、B1、1F）
   - 默认显示当前楼层的上下各一层

**验证标准**：
- 切换到多层模式，可以选择要显示的楼层。
- 多层模式下可以看到跨层路线完整路径。

**文件修改**：
- `src/components/navigation/GuideMapShell.vue`：增加多层切换控件
- `src/pages/index/index.vue`：增加多层模式状态管理

---

## 实施优先级

### 必须实施（Phase 1）

这些任务实现核心的自动切换能力，显著提升交互直觉性。

- Task 1.1：实现距离监听与自动切换逻辑
- Task 1.2：调整首页和 GuideMapShell 配合自动切换
- Task 1.3：保留手动切换作为兜底

**预估总工作量**：3.5-4.5 天

---

### 建议实施（Phase 2）

这些任务优化用户体验细节，提升产品完成度。

- Task 2.1：增加视觉过渡和状态提示
- Task 2.2：优化阈值和参数

**预估总工作量**：2-3 天

---

### 未来实施（Phase 3）

这些任务依赖跨层路线能力，优先级较低。

- Task 3.1：扩展 ViewMode 和多层加载逻辑
- Task 3.2：增加"单层/多层"切换控件

**预估总工作量**：4-5 天  
**前置条件**：`route_graph` 和 `nav_data` 接入完成

---

## 技术风险与应对

### 风险 1：自动切换触发频繁，导致加载抖动

**影响**：用户体验差，可能导致卡顿。

**应对措施**：
- 使用双阈值滞回机制（低阈值 1.0x，高阈值 1.3x）
- 增加冷却时间（2 秒内不重复触发）
- 增加加载锁（切换期间锁定，不响应新的切换请求）
- 监听 `controls.change` 事件而不是每帧检查，减少计算频率

---

### 风险 2：移动端误触缩放，导致意外切换

**影响**：用户可能在查看建筑外观时误触放大，意外切换到楼层。

**应对措施**：
- 手动切换后临时禁用自动切换（10 秒）
- 提供设置项，允许用户永久禁用自动切换
- 优化阈值，避免轻微缩放就触发
- 首次自动切换时显示引导提示，告知用户可以手动控制

---

### 风险 3：多层模式性能问题

**影响**：同时加载多个楼层可能导致内存占用过高、帧率下降。

**应对措施**：
- 限制最多同时显示 3-4 层
- 考虑使用 LOD（细节层次），远处楼层使用简化模型
- 监控帧率，低于阈值时提示用户减少显示楼层
- 多层模式下禁用部分高级渲染特性（例如阴影）

---

## 质量保证

### 单元测试

- `ThreeMap.vue` 的距离计算和阈值判断逻辑
- 自动切换状态机测试（overview → floor → overview）
- 加载锁和冷却时间逻辑测试

### 集成测试

- 完整的用户流程：进入馆内 → 缩放 → 自动切换 → 手动切换 → 楼层切换
- 自动切换与手动切换的交互测试
- 多层模式与单层模式切换测试

### 移动端测试

- 在真实移动设备（iOS/Android）测试缩放手势
- 测试误触场景
- 测试弱网环境下的加载体验

### 性能测试

- 监控切换过程的内存占用
- 监控多层模式的帧率
- 测试大建筑和小建筑的阈值适配性

---

## 验收标准

### Phase 1 验收标准

- [ ] 用户在建筑外观放大到一定距离，自动切换到默认楼层（L1）
- [ ] 用户在楼层内部缩小到一定距离，自动切换回建筑外观
- [ ] 快速缩放不会触发多次加载
- [ ] 手动切换后 10 秒内不会自动切换
- [ ] 全馆模式下可以直接点击楼层控件选择楼层
- [ ] 移动端测试无明显误触

### Phase 2 验收标准

- [ ] 切换过程有视觉过渡，无突兀感
- [ ] 首次自动切换有引导提示
- [ ] 切换时有 loading 状态提示
- [ ] 阈值在真实设备上测试符合预期

### Phase 3 验收标准

- [ ] 可以切换到多层模式，同时显示多个楼层
- [ ] 多层模式帧率 >30fps
- [ ] 多层模式下可以看到跨层路线完整路径

---

## 附录：配置项设计

### ThreeMap 组件新增 Props

```typescript
interface ThreeMapProps {
  // ... 现有 props
  
  // 自动切换配置
  autoSwitch?: boolean                    // 是否启用自动切换，默认 true
  autoSwitchThresholdLow?: number         // 下阈值倍数，默认 1.0
  autoSwitchThresholdHigh?: number        // 上阈值倍数，默认 1.3
  autoSwitchCooldown?: number             // 冷却时间（毫秒），默认 2000
  
  // 多层模式配置（Phase 3）
  enableMultiFloor?: boolean              // 是否启用多层模式，默认 false
  multiFloorVerticalSpacing?: number      // 楼层间距（米），默认 10
}
```

### 新增 Events

```typescript
// ThreeMap emit 的新事件
emit('auto-switch', { 
  from: 'overview' | 'floor',
  to: 'overview' | 'floor',
  trigger: 'zoom-in' | 'zoom-out',
  distance: number 
})

emit('auto-switch-blocked', {
  reason: 'loading-locked' | 'cooldown' | 'disabled'
})
```

---

## 参考资料

- OrbitControls 文档：https://threejs.org/docs/#examples/en/controls/OrbitControls
- Three.js 性能优化最佳实践：https://threejs.org/manual/#en/optimize-lots-of-objects
- 馆内导览产品参考：机场导览 App、商场导览 App、博物馆 3D 导览

---

## 变更记录

| 日期 | 版本 | 变更内容 | 作者 |
|------|------|---------|------|
| 2026-06-12 | v1.0 | 初始版本 | Claude |