# CMR-Mini 项目深度分析报告 (GeminiAnalysis.md)
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


## 1. 项目定位与核心愿景
**CMR-Mini** 是一个运行在微信小程序环境中的高性能**定向越野 (Orienteering)** 实时竞赛/练习引擎。其核心竞争力在于通过自研的 **WebGL 地图渲染管线** 提供流畅的地图交互，并结合高精度多传感器融合技术（GPS、罗盘、心率、加速度计等）实现精准的运动反馈。

## 2. 核心系统架构分析

### 2.1 地图渲染引擎 (Map Engine)
*   **渲染技术**：采用 `Single WebGL Pipeline`。相比微信原生地图组件，具有更高的定制化能力，特别是在“Heading-Up”（朝向朝上）模式下的性能表现。
*   **瓦片管理**：通过 `TileStore` 实现三级缓存（内存 -> 磁盘 -> 网络），并支持 `tilePersistentCache`。
*   **投影逻辑**：采用 `WGS84 -> WorldTile -> Camera -> Screen` 的标准 GIS 变换链，能够精准处理地理坐标到屏幕像素的映射。

### 2.2 传感器融合系统 (Sensor System)
*   **CompassHeadingController**：核心逻辑在于罗盘数据 (`wx.onCompassChange`) 与设备姿态 (`wx.onDeviceMotionChange`) 的协同。
*   **LocationController**：支持真实 GPS 数据与 Mock 模拟器（通过 WebSocket 连接 `mock-gps-sim` 工具）的无缝切换。
*   **TelemetryRuntime**：实现了运动参数的实时计算，包括速度、距离目标点距离、心率分区等指标。

### 2.3 游戏逻辑与规则 (Game Logic)
*   **GameRuntime**：驱动对局状态机，支持“顺序赛 (Classic Sequential)”与“积分赛 (Score-O)”。
*   **PunchPolicy**：实现了自动进入检查点范围触发、手动打点、跳过点位等业务逻辑。

## 3. 指北针 (Compass) 平滑度瓶颈分析
根据目前的实现，指北针的卡顿感主要源于以下三个层面：

1.  **采样频率与插值逻辑**：
    *   目前使用 `interpolateHeadingDeg` 进行线性差值，且 `ABSOLUTE_HEADING_CORRECTION` 为固定系数 (0.44)。这种静态系数在“静态微调”时显得不够敏锐，在“快速旋转”时又显得滞后。
2.  **Android/iOS 差异化丢帧**：
    *   Android 传感器回调频率不稳定。
    *   逻辑中对 `direction` 进行了严格的数值有效性判断，若系统由于硬件抖动返回短时异常值，会导致视觉上的“跳帧”。
3.  **UI 同步周期限制**：
    *   `MapEngine` 的 `UI_SYNC_INTERVAL_MS` 设置为 80ms，这意味着视觉反馈的最高帧率仅为 12.5Hz，远低于屏幕刷新率，导致指针转动不够丝滑。

## 4. 优化技术路线建议

### 4.1 引入指数加权移动平均 (EWMA) 的动态系数
建议根据旋转角速度动态调整平滑系数。当检测到瞬时角位移较大时，降低平滑度以追求响应速度；当位移较小时，增加平滑度以过滤手抖带来的噪声。

### 4.2 视觉平滑：使用 CSS Transform 或 WebGL 帧间补偿
目前数据是由控制器下发到 UI 的。建议：
*   **方案 A (推荐)**：在 UI 层（`.wxml`/`.wxss`）利用 `transition: transform 0.1s linear;` 实现视觉层面的自动补帧。
*   **方案 B**：在 WebGL 渲染循环内进行帧间插值，将数据的 12.5Hz 提升到 渲染循环的 60Hz。

### 4.3 预测与死区 (Dead-zone) 过滤
在 `CompassHeadingController` 中加入微小位移的死区过滤逻辑，避免由于硬件高频微小抖动导致的视图高频重绘，降低系统功耗的同时提升视觉稳定性。

## 5. 结论
CMR-Mini 已经建立了一个非常坚实的专业定向越野引擎基础。后续的优化重点应从“功能的实现”转向“交互的极致平滑”，特别是针对指北针这类核心导向组件，需要更精细化的信号处理策略。

---
*Generated by Gemini CLI Analysis Tool*