整理中文文档结构与索引

doc/archive/notes/传感器接入待办.md

@@ -0,0 +1,571 @@
+# 传感器接入待开发方案
+
+本文档用于整理当前项目后续可利用的传感器能力，分为：
+
+- 微信小程序能力边界
+- 原生 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`，上层只消费统一状态。**
+