整理中文文档结构与索引

doc/debug/传感器现状总结.md

@@ -0,0 +1,235 @@
+# 传感器现状总结
+
+本文档用于说明当前小程序版本已经接入并实际使用的传感器/输入源、它们在系统中的作用，以及当前阶段的稳定边界。
+
+## 1. 当前正式在用的传感器/输入源
+
+### 1.1 GPS 定位
+
+当前作用：
+
+- 当前定位点显示
+- GPS 轨迹线绘制
+- 到目标点距离计算
+- 打点半径判定
+- 地图锁定跟随
+- 自动转图中的前进方向判断
+- 速度、里程、卡路里等 telemetry 统计
+
+当前涉及层：
+
+- `LocationController`
+- `TelemetryRuntime`
+- `MapEngine`
+- `RuleEngine`
+
+说明：
+
+- 这是当前地图和玩法系统最核心的输入源。
+
+### 1.2 Compass 罗盘
+
+当前作用：
+
+- 指北针
+- 静止或低速时的地图朝向
+- 真北 / 磁北参考切换相关显示
+
+当前涉及层：
+
+- `CompassHeadingController`
+- `MapEngine`
+
+说明：
+
+- 当前自动转图的稳定主来源之一。
+
+### 1.3 Gyroscope 陀螺仪
+
+当前作用：
+
+- 提供设备旋转速率调试数据
+- 为设备朝向可信度提供辅助参考
+- 为后续更稳的自动转图平滑能力预留输入
+
+当前涉及层：
+
+- `GyroscopeController`
+- `TelemetryRuntime`
+
+说明：
+
+- 当前已接入并显示，但还没有直接主导地图旋转。
+
+### 1.4 DeviceMotion 设备方向
+
+当前作用：
+
+- 提供设备朝向角参考
+- 参与 `deviceHeadingDeg`
+- 参与 `headingConfidence`
+- 用于调试观察姿态相关信息
+
+当前涉及层：
+
+- `DeviceMotionController`
+- `TelemetryRuntime`
+
+说明：
+
+- 当前不直接接管自动转图，主要作为辅助与调试输入。
+
+### 1.5 BLE 心率带
+
+虽然不是手机内置传感器，但当前已经是正式输入源。
+
+当前作用：
+
+- 实时心率采集
+- HUD 颜色分区
+- 卡路里估算
+- 橙 / 红警戒边框
+- 后续心率相关玩法
+
+当前涉及层：
+
+- `HeartRateController`
+- `HeartRateInputController`
+- `TelemetryRuntime`
+- HUD / Feedback
+
+## 2. 当前正式在用的模拟输入源
+
+### 2.1 模拟 GPS
+
+当前作用：
+
+- 室内测试路线与打点
+- 模拟移动
+- 测试规则、HUD、自动转图
+
+说明：
+
+- 与真实 GPS 并列，是正式的开发调试输入源。
+
+### 2.2 模拟心率
+
+当前作用：
+
+- 测试心率颜色区间
+- 测试卡路里累计
+- 测试边框警示
+- 测试第二块 HUD
+
+说明：
+
+- 与真实心率带并列，是正式的开发调试输入源。
+
+## 3. 当前没有纳入正式能力的传感器
+
+### 3.1 Accelerometer 加速度计
+
+当前状态：
+
+- 在当前微信小程序运行时 / 设备环境下不稳定
+- 启动时出现 `startAccelerometer:fail, has enable, should stop pre operation`
+- 已从当前第一阶段正式方案中移出
+
+结论：
+
+- 当前小程序版本不依赖加速度计
+- 后续更完整的姿态 / 运动融合，建议放到原生 Flutter 端实现
+
+## 4. 当前地图上真正直接起作用的核心输入
+
+如果只看当前会直接影响地图行为和玩法行为的核心输入，主要是：
+
+- `GPS`
+- `Compass`
+- `Heart Rate (BLE)`
+
+其中：
+
+- `GPS` 负责位置、轨迹、速度、距离、打点、跟随、前进方向
+- `Compass` 负责当前稳定的地图朝向与指北针
+- `Heart Rate` 负责 HUD 颜色、卡路里和警戒反馈
+
+而：
+
+- `Gyroscope`
+- `DeviceMotion`
+
+当前更多是为后续更稳的朝向融合能力做准备。
+
+## 5. 当前阶段的稳定边界
+
+小程序第一阶段推荐稳定边界如下：
+
+- 保留：
+  - `Location`
+  - `Compass`
+  - `Gyroscope`
+  - `DeviceMotion`
+  - `BLE Heart Rate`
+  - `Mock GPS`
+  - `Mock Heart Rate`
+- 放弃：
+  - `Accelerometer`
+
+结论：
+
+- 小程序端以稳定为优先
+- 更完整的原始传感器融合，放在原生 Flutter 端推进
+
+## 6. 一句话总结
+
+当前小程序版本已经正式使用的核心传感器 / 输入源是：
+
+- `GPS`
+- `Compass`
+- `Gyroscope`
+- `DeviceMotion`
+- `Heart Rate (BLE)`
+- `Mock GPS`
+- `Mock Heart Rate`
+
+其中真正直接驱动地图行为的核心仍然是：
+
+- `GPS`
+- `Compass`
+
+其余能力更多承担辅助、调试、反馈和后续扩展输入的角色。
+
+---
+
+## 7. 当前主体能力边界补充
+
+最近排查已经确认：
+
+- 当前最初使用的是**个人主体**小程序
+
+这会影响部分设备能力的可用性与稳定性，尤其是：
+
+- `Compass`
+- `Accelerometer`
+- 与 `web-view` 相关的扩展体验链
+
+因此当前这份传感器结论要加一个前提：
+
+**它不仅受到代码实现影响，也受到小程序主体能力边界影响。**
+
+这意味着：
+
+- 某些 Android 上的样本异常，不一定是算法错误
+- 某些 H5 / 传感器问题，不一定能在个人主体下彻底解决
+
+当前建议：
+
+- 原生主流程继续开发
+- 传感器高级能力与 H5 接入先保留设计与代码入口
+- 等企业主体切换完成后，再做专项回归
+
+详细说明见：
+
+- [platform-capability-notes.md](D:/dev/cmr-mini/doc/debug/平台能力说明.md)
+