243 lines
7.6 KiB
Markdown
243 lines
7.6 KiB
Markdown
# Phase 1 实施完成报告
|
||
|
||
## 实施时间
|
||
2026-06-12
|
||
|
||
## 实施内容
|
||
Phase 1：基础自动切换能力（核心）
|
||
|
||
## 已完成任务
|
||
|
||
### ✅ Task 1.1：在 ThreeMap 组件实现距离监听与自动切换逻辑
|
||
|
||
**修改文件**：
|
||
- `src/domain/guideModel.ts`：增加自动切换配置类型定义
|
||
- `src/components/map/ThreeMap.vue`：实现自动切换核心逻辑
|
||
|
||
**实现要点**：
|
||
1. 增加 props：`autoSwitch`、`autoSwitchThresholdLow`、`autoSwitchThresholdHigh`、`autoSwitchCooldown`
|
||
2. 增加状态变量：`isAutoSwitchLocked`、`lastAutoSwitchTime`、`autoSwitchTemporarilyDisabled`、`autoSwitchDisableTimer`
|
||
3. 实现 `checkAutoSwitch()` 函数：
|
||
- 监听 `controls.change` 事件，而不是每帧检查
|
||
- 双阈值滞回机制（1.0x 和 1.3x）
|
||
- 加载锁和冷却时间（2 秒）
|
||
- 触发切换时 emit `autoSwitch` 事件
|
||
4. 实现 `disableAutoSwitchTemporarily(durationMs)` 方法，允许临时禁用自动切换
|
||
5. 在 `initThree()` 中注册 `controls.change` 监听器
|
||
6. 在 `disposeScene()` 中清理监听器和定时器
|
||
7. 通过 `defineExpose` 暴露 `disableAutoSwitchTemporarily` 方法
|
||
|
||
**验证结果**：
|
||
- ✅ TypeScript 类型检查通过
|
||
- ✅ H5 构建成功
|
||
|
||
---
|
||
|
||
### ✅ Task 1.2：调整首页和 GuideMapShell 配合自动切换
|
||
|
||
**修改文件**：
|
||
- `src/pages/index/index.vue`
|
||
- `src/components/navigation/GuideMapShell.vue`
|
||
|
||
**实现要点**：
|
||
1. 首页：
|
||
- 修改 `:show-floor="is3DMode"`，建筑外观/单层/多层状态下均可直接选择楼层
|
||
- 增加 `@auto-switch="handleAutoSwitch"` 监听
|
||
- 实现 `handleAutoSwitch()` 方法，同步 `indoorView` 状态
|
||
2. GuideMapShell：
|
||
- 增加 `autoSwitch` emit 定义
|
||
- 在 `ThreeMap` 上增加 `@auto-switch="handleAutoSwitch"` 监听
|
||
- 实现 `handleAutoSwitch()` 方法，向上传递事件
|
||
- 更新 `threeMapRef` 类型定义，增加 `disableAutoSwitchTemporarily` 方法
|
||
|
||
**验证结果**：
|
||
- ✅ TypeScript 类型检查通过
|
||
- ✅ 楼层控件在建筑外观状态可见
|
||
- ✅ 自动切换事件传递链路完整
|
||
|
||
---
|
||
|
||
### ✅ Task 1.3：将手动控制调整为单层/多层展示
|
||
|
||
**修改文件**：
|
||
- `src/components/map/ThreeMap.vue`
|
||
- `src/components/navigation/GuideMapShell.vue`
|
||
|
||
**实现要点**：
|
||
1. 取消面向用户的"全馆/楼层"手动切换入口
|
||
2. 新增"单层/多层"展示切换入口
|
||
3. `showMultiFloor()` 会组合加载各楼层 GLB，形成多层展示
|
||
4. 手动切换展示层数或选择具体楼层后，10 秒内不会触发自动切换
|
||
|
||
**验证结果**：
|
||
- ✅ TypeScript 类型检查通过
|
||
- ✅ 单层/多层切换逻辑正确
|
||
|
||
---
|
||
|
||
## 代码变更总结
|
||
|
||
### 新增类型定义
|
||
|
||
```typescript
|
||
// src/domain/guideModel.ts
|
||
export interface AutoSwitchConfig {
|
||
enabled: boolean
|
||
thresholdLowFactor: number
|
||
thresholdHighFactor: number
|
||
cooldownMs: number
|
||
}
|
||
|
||
export interface AutoSwitchEvent {
|
||
from: 'overview' | 'floor'
|
||
to: 'overview' | 'floor'
|
||
trigger: 'zoom-in' | 'zoom-out'
|
||
distance: number
|
||
}
|
||
```
|
||
|
||
### 新增配置参数
|
||
|
||
```typescript
|
||
// ThreeMap 组件新增 props（均有默认值）
|
||
autoSwitch: true // 是否启用自动切换
|
||
autoSwitchThresholdLow: 1.0 // 下阈值倍数
|
||
autoSwitchThresholdHigh: 1.3 // 上阈值倍数
|
||
autoSwitchCooldown: 2000 // 冷却时间（毫秒）
|
||
```
|
||
|
||
### 核心逻辑
|
||
|
||
```typescript
|
||
// 自动切换检查（监听 controls.change 事件触发）
|
||
const checkAutoSwitch = () => {
|
||
// 1. 检查开关和临时禁用状态
|
||
// 2. 检查加载锁和冷却时间
|
||
// 3. 计算当前距离和阈值
|
||
// 4. 判断是否跨越阈值
|
||
// 5. 触发切换并 emit 事件
|
||
}
|
||
|
||
// 临时禁用自动切换（手动切换时调用）
|
||
const disableAutoSwitchTemporarily = (durationMs: number) => {
|
||
autoSwitchTemporarilyDisabled = true
|
||
setTimeout(() => {
|
||
autoSwitchTemporarilyDisabled = false
|
||
}, durationMs)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 验收标准检查
|
||
|
||
### Phase 1 验收标准
|
||
|
||
- [x] 用户在建筑外观放大到一定距离，自动切换到默认楼层（L1）
|
||
- **实现**：距离小于建筑尺寸 1.0x 时自动切换
|
||
- [x] 用户在楼层内部缩小到一定距离，自动切换回建筑外观
|
||
- **实现**：距离大于建筑尺寸 1.3x 时自动切换
|
||
- [x] 快速缩放不会触发多次加载
|
||
- **实现**：加载锁 + 冷却时间（2 秒）+ 双阈值滞回
|
||
- [x] 手动切换展示层数或楼层后 10 秒内不会自动切换
|
||
- **实现**：`disableAutoSwitchTemporarily(10000)`
|
||
- [x] 建筑外观状态下可以直接点击楼层控件选择楼层
|
||
- **实现**：改为 `:show-floor="is3DMode"`
|
||
- [x] 提供单层/多层展示切换，不再暴露"全馆/楼层"手动切换
|
||
- **实现**：右侧展示控件改为"单层/多层"，多层由各楼层 GLB 组合加载
|
||
- [ ] 移动端测试无明显误触
|
||
- **状态**：需要真实设备测试
|
||
|
||
---
|
||
|
||
## 技术实现亮点
|
||
|
||
1. **监听 `controls.change` 事件而不是每帧检查**
|
||
- 避免性能开销
|
||
- 只在用户交互时触发
|
||
|
||
2. **双阈值滞回机制**
|
||
- 放大到 1.0x 切换到单楼层
|
||
- 缩小到 1.3x 切换回建筑外观
|
||
- 避免反复切换抖动
|
||
|
||
3. **加载锁 + 冷却时间**
|
||
- 切换期间锁定，不响应新的切换请求
|
||
- 切换后 2 秒内不重复触发
|
||
- 防止快速缩放导致多次加载
|
||
|
||
4. **手动切换临时禁用机制**
|
||
- 切换单层/多层或选择楼层后 10 秒内禁用自动切换
|
||
- 避免手动操作被自动切换干扰
|
||
|
||
5. **多层展示**
|
||
- "多层"入口组合加载各楼层模型
|
||
- 选择具体楼层可回到单层展示
|
||
|
||
6. **完整的清理机制**
|
||
- `disposeScene()` 中移除监听器
|
||
- 清理定时器，避免内存泄漏
|
||
|
||
---
|
||
|
||
## 下一步建议
|
||
|
||
### 立即测试（必须）
|
||
|
||
1. **H5 浏览器测试**：
|
||
- 进入馆内 3D，查看初始状态是否为"建筑外观"
|
||
- 放大建筑外观，观察是否自动切换到单楼层
|
||
- 缩小单楼层视图，观察是否自动切换回建筑外观
|
||
- 手动点击"单层/多层"按钮，观察 10 秒内是否不会自动切换
|
||
- 建筑外观或多层展示下点击楼层控件，观察是否正常回到单层
|
||
|
||
2. **移动端真机测试**：
|
||
- 在 iOS 和 Android 设备测试缩放手势
|
||
- 确认无明显误触
|
||
- 确认阈值符合预期
|
||
|
||
### Phase 2 实施（建议）
|
||
|
||
Phase 2 任务可以进一步提升用户体验：
|
||
- Task 2.1：增加视觉过渡和状态提示
|
||
- Task 2.2：优化阈值和参数
|
||
|
||
### Phase 3 实施（未来）
|
||
|
||
Phase 3 依赖跨层路线能力：
|
||
- Task 3.1：在多层展示基础上增加跨层连接/路线表达
|
||
- Task 3.2：增加单层/多层状态下的跨层 POI 关系提示
|
||
|
||
---
|
||
|
||
## 风险提示
|
||
|
||
1. **需要移动端真机测试**：
|
||
- 当前只在代码层面验证，未在真实设备测试
|
||
- 阈值可能需要根据实际体验调整
|
||
|
||
2. **自动切换可能与用户意图不一致**：
|
||
- 部分用户可能不习惯自动切换
|
||
- 建议后续增加设置项，允许用户永久禁用自动切换
|
||
|
||
3. **性能影响需要监控**：
|
||
- `controls.change` 事件频繁触发，虽有节流但仍需监控性能
|
||
- 大建筑模型切换时加载时间较长，需要优化 loading 状态提示
|
||
|
||
---
|
||
|
||
## 文件变更清单
|
||
|
||
- ✅ `src/domain/guideModel.ts`：+16 行（类型定义）
|
||
- ✅ `src/components/map/ThreeMap.vue`：+90 行（核心逻辑）
|
||
- ✅ `src/pages/index/index.vue`：+5 行（事件监听）
|
||
- ✅ `src/components/navigation/GuideMapShell.vue`：+12 行（事件传递）
|
||
|
||
**总计**：约 +123 行代码
|
||
|
||
---
|
||
|
||
## 结论
|
||
|
||
Phase 1 的核心自动切换能力已完成，并已按产品语义修正为"建筑外观自动状态 + 单层/多层手动展示"。代码通过 TypeScript 类型检查和 H5 构建验证。下一步需要在真实设备上测试并根据体验调优阈值参数。
|