# 传感器接入待开发方案

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

- 微信小程序能力边界
- 原生 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`，上层只消费统一状态。**