# 传感器现状总结

本文档用于说明当前小程序版本已经接入并实际使用的传感器/输入源、它们在系统中的作用，以及当前阶段的稳定边界。

## 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/platform-capability-notes.md)