# 罗盘问题排查记录

## 背景

本项目在微信小程序中使用罗盘驱动：

- 指北针针头
- 指北针顶部角度数字
- `heading-up` 自动转图

在一次围绕顶部提示窗、传感器显示链和性能优化的修改后，出现了以下问题：

- iOS 端偶发正常，偶发异常
- Android 端罗盘长期无样本
- 指北针不转
- `heading-up` 自动转图一起失效

## 最终结论

这次问题的主因不是算法本身，而是：

**Android 微信环境下，罗盘监听需要被持续保活；之前将多处看似冗余的 `compassController.start()` 清理掉后，Android 的罗盘样本链被破坏了。**

也就是说：

- iOS 对罗盘监听更宽容
- Android 对罗盘监听更脆弱
- 之前稳定，不是因为链路更“干净”，而是因为老代码里存在一条实际有效的“罗盘保活链”

## 现象总结

### 失效期

- Android 调试面板里 `Compass Source` 为 `无数据`
- iOS 仍可能有 `罗盘` 样本
- 若强行用 `DeviceMotion` 兜底，会出现：
  - 指针会转
  - 但方向不准
  - 自动转图方向错误

### 恢复后

- Android `Compass Source` 恢复为 `罗盘`
- 指北针针头恢复
- 顶部角度数字恢复
- `heading-up` 恢复

## 误判过的方向

以下方向在本次排查中都被考虑过，但最终不是根因或不是主要根因：

### 1. `DeviceMotion` 兜底方案

问题：

- `DeviceMotion` 可以给出设备姿态角
- 但不能稳定代替“指向北”的绝对罗盘
- 用它兜底会导致：
  - 能转
  - 但方向明显不准

结论：

**`DeviceMotion` 不能作为正式指北针来源。**

### 2. 加速度计 / 其他传感器互斥

曾排查：

- `Accelerometer`
- `Gyroscope`
- `DeviceMotion`
- `Compass`

结论：

- 加速度计在当前微信 Android 环境下不稳定，已放弃
- 但这不是这次罗盘彻底失效的主因

### 3. 算法问题

曾尝试调整：

- 角度平滑
- 设备方向单位解释
- motion fallback 算法

结论：

这些会影响“顺不顺”、“准不准”，但**不能解释 Android 完全无罗盘样本**。

## 真正修复的方法

将之前被清理掉的多处 `this.compassController.start()` 恢复回去。

这些调用点主要分布在：

- `commitViewport(...)`
- `handleTouchStart(...)`
- `animatePreviewToRest(...)`
- `normalizeTranslate(...)`
- `zoomAroundPoint(...)`
- `handleRecenter(...)`
- `handleRotateStep(...)`
- `handleRotationReset(...)`

这些调用在代码审美上看起来像“重复启动”，但在 Android 微信环境里，它们实际上承担了：

**重新拉起 / 保活罗盘监听**

的作用。

## 当前工程判断

本项目当前应当采用以下原则：

### 1. 罗盘主来源只使用 `Compass`

不要再让：

- `DeviceMotion`
- 其它姿态角

参与正式指北针和自动转图的主方向链。

### 2. `DeviceMotion` 只保留为辅助或调试输入

可用于：

- 调试面板显示
- 设备姿态观察
- 未来原生端姿态融合参考

但不要直接驱动指北针。

### 3. Android 端罗盘需要保活

后续不要再把这些 `compassController.start()` 当成纯冗余逻辑随意清掉。

如果要优化代码，应该：

- 保留现有行为
- 将其收口为有明确语义的方法

例如：

- `ensureCompassAlive()`
- `refreshCompassBinding()`

而不是直接删掉。

## 与生命周期相关的硬约束

以下约束必须保持：

### 单实例

页面层必须保证任意时刻只有一个 `MapEngine` 活跃实例。

### 完整销毁

`MapEngine.destroy()` 中必须完整执行：

- `compassController.destroy()`
- 其它传感器 `destroy()`

防止旧监听残留。

### 调试状态不应影响罗盘主链

调试面板开关不应再控制：

- 罗盘是否启动
- 罗盘是否停止

否则容易再次引入平台差异问题。

## 推荐保留的调试字段

以下字段建议长期保留，便于后续定位：

- `Compass Source`
- `sensorHeadingText`
- 顶部角度数字
- `heading-up` 开关状态

其中 `Compass Source` 至少应显示：

- `罗盘`
- `无数据`

避免再次将问题误判为算法问题。

## 后续优化建议

如果后面要继续优化这段代码，推荐方向是：

### 可做

- 将分散的 `compassController.start()` 收口成命名明确的方法
- 为 Android 罗盘链补一层更可读的“保活机制”注释
- 保留当前稳定行为前提下做重构

### 不建议

- 再次移除这些重复 `start()` 调用
- 用 `DeviceMotion` 正式兜底指北针
- 让调试开关影响罗盘主链启动

## 一句话经验

**在微信小程序里，Android 罗盘监听的稳定性比 iOS 更脆；某些看似冗余的 `start()` 调用，实际是平台兼容补丁，不应该在没有真机回归的情况下清理。**