mini-prog/doc/todo-sensor-integration-plan.md

传感器接入待开发方案

本文档用于整理当前项目后续可利用的传感器能力，分为：

• 微信小程序能力边界
• 原生 Flutter App 能力边界
• 两端统一的抽象建议
• 推荐落地顺序

目标不是一次性接入所有传感器，而是优先接入对当前地图玩法、自动转图、运动状态识别、HUD/反馈最有价值的能力。

---

1. 总体原则

传感器接入必须遵守以下原则：

• 原始传感器数据只放在 engine/sensor
• 融合后的高级状态放在 telemetry
• 地图引擎只消费“对地图有意义的结果”
• 规则引擎只在玩法确实需要时消费高级状态
• 不要把原始三轴值直接喂给地图或玩法逻辑

推荐统一产出的高级状态包括：

• movementState
• headingSource
• devicePose
• headingConfidence
• cadenceSpm
• motionIntensity

---

2. 微信小程序可用传感器

2.1 当前确认可用

基于微信小程序官方 API 与项目内 typings，当前可直接使用的能力包括：

• Location
  • wx.startLocationUpdate
  • wx.startLocationUpdateBackground
  • wx.onLocationChange
• Accelerometer
  • wx.startAccelerometer
  • wx.onAccelerometerChange
• Compass
  • wx.startCompass
  • wx.onCompassChange
• DeviceMotion
  • wx.startDeviceMotionListening
  • wx.onDeviceMotionChange
• Gyroscope
  • wx.startGyroscope
  • wx.onGyroscopeChange
• WeRunData
  • wx.getWeRunData

2.2 当前确认不可直接获得的原始能力

微信小程序没有直接开放以下原始传感器接口：

• Gravity
• Linear Acceleration
• Rotation Vector
• Geomagnetic Field 原始三轴
• Proximity
• 原始 Step Counter

说明：

• wx.getWeRunData 不是实时步数传感器流
• 它更适合中长期统计，不适合实时地图玩法

---

3. 微信小程序推荐应用方案

3.1 第一优先级

A. Gyroscope

用途：

• 提升自动转图平滑度
• 降低跑步中手机晃动导致的朝向抖动
• 增强指北针和地图旋转过渡体验

推荐产出：

• turnRate
• headingSmoothFactor
• headingStability

B. DeviceMotion

用途：

• 识别手机姿态
• 判断设备是竖持、倾斜还是接近平放
• 配合 gyro 增强朝向可信度

推荐产出：

• devicePose
• orientationConfidence
• tiltState

C. Compass

用途：

• 静止或低速时，作为持机朝向基准
• 指北针展示

推荐角色：

• 继续保留
• 作为“静止朝向输入”
• 不再单独承担跑动中的全部朝向逻辑

3.2 第二优先级

D. Accelerometer

用途：

• 辅助识别是否真的在移动
• 识别急停、抖动、运动强度变化

推荐产出：

• motionIntensity
• movementConfidence

说明：

• 不建议直接用原始加速度驱动地图行为
• 应和 GPS、gyro 一起融合使用

E. Location

用途：

• 当前定位
• 轨迹
• 目标距离
• movement heading
• 速度估计

推荐角色：

• 继续作为地图和玩法核心输入
• 后续更多与 gyro / accelerometer 配合使用

3.3 当前不建议优先投入

F. WeRunData

用途：

• 日级步数统计
• 长周期运动数据

当前不建议投入原因：

• 不是实时传感器
• 不适合当前地图实时玩法主链

---

4. 微信小程序推荐先产出的高级状态

A. movementState

建议值：

• idle
• walk
• run

来源：

• GPS 速度
• accelerometer
• device motion

B. headingSource

建议值：

• sensor
• blended
• movement

来源：

• compass
• gyroscope
• GPS track

C. devicePose

建议值：

• upright
• tilted
• flat

来源：

• device motion
• gyroscope

D. headingConfidence

建议值：

• low
• medium
• high

来源：

• compass
• gyroscope
• GPS 精度
• movement heading 是否可靠

---

5. 原生 Flutter App 可用传感器

原生 Flutter App 的能力边界明显更强，后续如果迁移或并行开发，可直接利用系统原始传感器。

5.1 可考虑直接接入

• Location / GNSS
• Compass / Magnetometer
• Gyroscope
• Accelerometer
• Linear Acceleration
• Gravity
• Rotation Vector
• Step Counter / Pedometer
• Barometer（如设备支持）
• Proximity（视玩法需求）

说明：

• Flutter 本身一般通过插件获取这些能力
• 具体以 Android / iOS 可用性差异为准

5.2 Flutter 相对小程序的主要优势

• 能直接拿到更完整的原始传感器矩阵
• 更适合做高质量姿态融合
• 更适合做步数、步频、跑动状态识别
• 可更深度控制后台行为和采样频率

---

6. Flutter 推荐应用方案

6.1 第一优先级

A. Rotation Vector

用途：

• 作为地图自动转图的高质量姿态输入
• 优于单纯磁力计 + 罗盘

推荐产出：

• deviceHeadingDeg
• devicePose
• headingConfidence

B. Gyroscope

用途：

• 旋转平滑
• 快速转身检测
• 姿态短时补偿

C. Linear Acceleration

用途：

• 识别运动状态
• 急停、冲刺、抖动判定

推荐产出：

• motionIntensity
• movementState

D. Step Counter

用途：

• 实时步数
• 步频
• 跑步状态识别
• 训练/卡路里模型增强

推荐产出：

• stepCount
• cadenceSpm
• movementState

6.2 第二优先级

E. Gravity

用途：

• 持机姿态识别
• 平放/竖持策略切换

F. Magnetometer

用途：

• 作为姿态融合底层输入

建议：

• 不建议单独直接映射到业务逻辑
• 主要与 rotation vector / gyro 融合

G. Barometer

用途：

• 海拔变化
• 爬升检测

适合：

• 户外定向训练
• 赛后统计

---

7. Flutter 推荐先产出的高级状态

A. movementState

建议值：

• idle
• walk
• run
• sprint

来源：

• GPS
• step counter
• linear acceleration

B. cadenceSpm

用途：

• 训练分析
• 卡路里估算增强
• 玩法资源逻辑

C. devicePose

建议值：

• upright
• tilted
• flat

D. headingSource

建议值：

• sensor
• blended
• movement

E. headingConfidence

建议值：

• low
• medium
• high

F. elevationTrend

建议值：

• flat
• ascending
• descending

来源：

• barometer
• GPS altitude

---

8. 两端统一抽象建议

尽管两端可用传感器不同，但建议统一抽象，不让上层感知平台差异。

8.1 原始层

放在：

• engine/sensor

职责：

• 读取平台原始传感器
• 做最基础的节流、归一化、权限处理

8.2 融合层

放在：

• telemetry

职责：

• 生成统一高级状态
• 对外屏蔽平台差异

建议统一输出：

• movementState
• devicePose
• headingSource
• headingConfidence
• cadenceSpm
• motionIntensity

8.3 消费层

地图引擎消费

• headingSource
• devicePose
• headingConfidence

规则层消费

• movementState
• cadenceSpm
• motionIntensity

HUD / Feedback 消费

• movementState
• cadenceSpm
• 心率 / 卡路里 / 训练强度

---

9. 推荐接入顺序

微信小程序第一阶段

先接：

• Gyroscope
• DeviceMotion

目标：

• 提升自动转图质量
• 产出更稳定的姿态与朝向可信度

微信小程序第二阶段

再接：

• Accelerometer

目标：

• 提升 movement state 识别

Flutter 第一阶段

先接：

• Rotation Vector
• Gyroscope
• Linear Acceleration

目标：

• 直接建立高质量朝向与运动状态底座

Flutter 第二阶段

再接：

• Step Counter
• Gravity

目标：

• 增强运动统计与姿态判断

---

10. 当前最值得优先投入的方向

如果只从当前项目收益看，最值得优先做的是：

微信小程序

• Gyroscope
• DeviceMotion

Flutter

• Rotation Vector
• Gyroscope
• Linear Acceleration

原因：

• 这些能力最直接影响地图体验
• 最贴近当前自动转图、前进方向、姿态识别需求
• 复用价值高

---

11. 一句话结论

微信小程序

可用传感器有限，但足够继续做：

• 更稳的自动转图
• 更好的朝向平滑
• 更好的运动状态识别

最值得优先接入的是：

• Gyroscope
• DeviceMotion
• Accelerometer

原生 Flutter App

可利用的原始传感器更完整，建议未来重点发挥：

• Rotation Vector
• Gyroscope
• Linear Acceleration
• Step Counter

两端都应遵守同一个原则：

原始传感器进 engine/sensor，高级状态进 telemetry，上层只消费统一状态。