整理中文文档结构与索引

doc/debug/罗盘排障记录.md

@@ -0,0 +1,213 @@
+# 罗盘问题排查记录
+
+## 背景
+
+本项目在微信小程序中使用罗盘驱动：
+
+- 指北针针头
+- 指北针顶部角度数字
+- `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()` 调用，实际是平台兼容补丁，不应该在没有真机回归的情况下清理。**
+