整理中文文档结构与索引

2026-03-30 18:49:22 +08:00
parent 3b9117427e
commit 24bc60bc7f
49 changed files with 462 additions and 136 deletions
--- a/doc/archive/notes/Gemini分析.md
+++ b/doc/archive/notes/Gemini分析.md
@@ -0,0 +1,51 @@
+# CMR-Mini 项目深度分析报告 (GeminiAnalysis.md)
+
+## 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*
+
--- a/doc/archive/notes/临时玩法讨论.md
+++ b/doc/archive/notes/临时玩法讨论.md
@@ -0,0 +1,210 @@
+# 临时玩法讨论记录
+
+本文档用于临时记录以下讨论内容：
+
+- 贪吃蛇式玩法是否适配当前架构
+- 超级玛丽拾金币式玩法是否适配当前架构
+- 这些玩法是否需要大改现有系统
+
+当前结论仅用于阶段讨论，不作为正式设计冻结文档。
+
+---
+
+## 1. 结论
+
+当前这两类玩法都适合现有架构。
+
+- `贪吃蛇式玩法`：适合
+- `区域拾金币玩法`：适合
+- 二者都不需要推翻现有主架构
+- 主要工作会集中在：
+  - 新的 `RulePlugin`
+  - 新的 `modeState`
+  - 新的 `map/hud presentation`
+  - 少量内容模型扩展
+
+也就是说，这两类玩法更像是在现有底座上继续长新玩法，而不是重做底层。
+
+---
+
+## 2. 为什么适合当前架构
+
+当前系统已经拆出了以下关键层：
+
+- 地图引擎
+- 规则引擎
+- telemetry 信息层
+- map / hud presentation
+- feedback 反馈层
+- 真实 / 模拟传感输入
+
+这意味着：
+
+- 地图只负责显示和交互能力
+- 规则层只负责玩法推进
+- telemetry 只负责通用过程信息
+- feedback 只负责声音、震动、动效等效果消费
+
+因此后续新增玩法，原则上主要是“新增规则和表现”，而不是“重写地图页”。
+
+---
+
+## 3. 贪吃蛇式玩法分析
+
+### 3.1 玩法本质
+
+这类玩法通常包含：
+
+- 玩家位置持续更新
+- 轨迹形成蛇身
+- 尾巴按规则增长或收缩
+- 撞到自己、奖励点、危险区后触发状态变化
+
+### 3.2 适配当前架构的原因
+
+当前架构已经具备：
+
+- 持续 GPS 输入
+- 持续 telemetry 更新
+- 规则事件驱动推进
+- 地图轨迹绘制能力
+- 统一反馈系统
+
+因此它天然可以承载：
+
+- 尾巴增长
+- 尾巴裁切
+- 自碰撞
+- 收集奖励
+- 危险区域
+
+### 3.3 真正需要新增的内容
+
+主要是玩法私有状态，而不是底层推翻：
+
+- `snakeBody`
+- `tailLength`
+- `tailWindow`
+- `collisionState`
+- `collectibleState`
+
+这些都应放入该玩法自己的 `modeState`。
+
+### 3.4 对当前架构的压力点
+
+这类玩法会推动当前系统继续增强：
+
+- `modeState` 承载更复杂连续状态
+- `MapPresentation` 支持蛇身/危险区/奖励点等更多图元
+- 规则层处理持续碰撞判定
+
+但这些属于增强，不属于重构。
+
+---
+
+## 4. 区域拾金币玩法分析
+
+### 4.1 玩法本质
+
+这类玩法通常包含：
+
+- 玩家在某片区域内自由移动
+- 经过或进入范围后收集金币
+- 有时间限制、连击或区域目标
+- 可附带终点或出口点
+
+### 4.2 适配当前架构的原因
+
+它本质上非常接近：
+
+- 自由收集
+- 多目标高亮
+- 局部 HUD 提示
+
+而这些当前在 `score-o` 里已经有相当基础。
+
+因此它可以看作：
+
+- `score-o` 的泛化版
+- 或“自由收集类玩法”的一个子类
+
+### 4.3 真正需要新增的内容
+
+这类玩法一般需要：
+
+- 新点位类型：`coin / pickup / bonus`
+- 新 HUD 信息：已收集数、剩余金币、区域完成度
+- 新表现：金币图标、收集动效、区域边界
+
+### 4.4 对当前架构的压力点
+
+这类玩法比蛇尾玩法对底座压力更小。
+
+它主要会推动：
+
+- 内容模型从“控制点”继续泛化
+- `MapPresentation` 支持更多点位类型
+- HUD 能容纳玩法专属信息
+
+但依然不需要大改主架构。
+
+---
+
+## 5. 需要补强的底座点
+
+如果未来真的开发这两类玩法，最值得继续补强的是：
+
+- 更明确的 `modeState` 规范
+- 更强的 `MapPresentation`
+- 更通用的内容模型
+- 更清晰的玩法事件字典
+
+建议后续逐步支持的通用对象类型：
+
+- `control`
+- `collectible`
+- `bonus`
+- `hazard`
+- `trigger`
+- `zone`
+- `exit`
+
+建议后续逐步支持的通用事件：
+
+- `item_collected`
+- `zone_entered`
+- `zone_left`
+- `self_collision`
+- `combo_started`
+- `combo_broken`
+- `area_cleared`
+
+---
+
+## 6. 当前判断标准
+
+如果未来实现这些玩法时出现以下现象，说明架构边界可能需要重审：
+
+- 必须大改 `MapEngine`
+- 必须大改 `TelemetryRuntime`
+- 必须让渲染器自己猜玩法规则
+- 必须把玩法私有状态塞进全局 telemetry
+
+如果没有出现这些情况，而主要只是新增：
+
+- `RulePlugin`
+- `modeState`
+- `presentation`
+- `feedback`
+
+那就说明当前架构是适配的。
+
+---
+
+## 7. 当前阶段总判断
+
+结论可以总结成一句话：
+
+当前这套架构不仅适合传统定向和积分赛，也适合继续承载更游戏化的运动玩法。  
+像贪吃蛇式玩法和区域拾金币玩法，都更像是“新增玩法插件”，而不是“推翻现有底座”。
+
--- a/doc/archive/notes/传感器接入待办.md
+++ b/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`，上层只消费统一状态。**
+
--- a/doc/archive/notes/多人模拟器待办.md
+++ b/doc/archive/notes/多人模拟器待办.md
@@ -0,0 +1,331 @@
+# 多人模拟器改造待开发文档
+
+本文档用于记录“公网模拟器支持多人开发/多人联调”的待开发方案。  
+当前仅作为设计与排期参考，不代表已经进入实现阶段。
+
+---
+
+## 1. 目标
+
+当前外部模拟器已经支持：
+
+- mock GPS
+- mock heart rate
+- 公网 WebSocket 接入
+
+但当前模型更接近“单会话广播”。  
+如果多人同时开发或联调，容易出现：
+
+- A 的 GPS 影响 B 的小程序
+- C 的心率影响 D 的 HUD
+- 同一公网模拟器服务缺乏隔离能力
+
+因此需要把模拟器体系升级成：
+
+- 多房间
+- 多身份
+- 按目标订阅
+
+最终目标是：
+
+- 多人共用同一个公网模拟服务
+- 各自的数据流互不干扰
+- 为未来多人玩法联调留好底座
+
+---
+
+## 2. 当前问题本质
+
+当前模拟器通信模型更像：
+
+- 一个 WebSocket 服务
+- 模拟器侧发布消息
+- 小程序侧直接接收
+
+这个模型在单人开发时足够。  
+但在多人开发时，缺少以下维度：
+
+- `room`
+- `actorId`
+- `channel`
+
+没有这些维度时，服务端无法做消息隔离与路由控制。
+
+---
+
+## 3. 建议的第一阶段方案
+
+第一阶段不追求复杂功能，只解决“多人不串流”的核心问题。
+
+### 3.1 核心模型
+
+为所有模拟消息增加 3 个维度：
+
+- `room`
+- `actorId`
+- `channel`
+
+含义如下：
+
+- `room`
+  表示一个独立测试空间
+- `actorId`
+  表示房间中的一个具体模拟源
+- `channel`
+  表示消息类型，例如 `gps`、`heart_rate`
+
+### 3.2 第一阶段目标
+
+第一阶段完成后应满足：
+
+- A 和 B 可以共用同一个公网模拟器服务
+- A 的小程序只接 A 的数据
+- B 的小程序只接 B 的数据
+- GPS 与心率都能隔离
+
+---
+
+## 4. 推荐协议
+
+### 4.1 模拟器注册
+
+```json
+{
+  "type": "register_simulator",
+  "room": "team-dev",
+  "actorId": "sim-a"
+}
+```
+
+### 4.2 小程序订阅
+
+```json
+{
+  "type": "subscribe",
+  "room": "team-dev",
+  "actorId": "sim-a",
+  "channels": ["gps", "heart_rate"]
+}
+```
+
+### 4.3 发布 GPS
+
+```json
+{
+  "type": "publish",
+  "room": "team-dev",
+  "actorId": "sim-a",
+  "channel": "gps",
+  "payload": {
+    "type": "mock_gps",
+    "timestamp": 1711267200000,
+    "lat": 31.2304,
+    "lon": 121.4737,
+    "accuracyMeters": 6,
+    "speedMps": 2.4,
+    "headingDeg": 135
+  }
+}
+```
+
+### 4.4 发布心率
+
+```json
+{
+  "type": "publish",
+  "room": "team-dev",
+  "actorId": "sim-a",
+  "channel": "heart_rate",
+  "payload": {
+    "type": "mock_heart_rate",
+    "timestamp": 1711267200000,
+    "bpm": 148
+  }
+}
+```
+
+---
+
+## 5. 服务端改造建议
+
+### 5.1 服务端职责
+
+服务端从“直接广播”升级成“按订阅路由”。
+
+它需要维护每个 WebSocket 连接的元数据：
+
+```ts
+type ClientSession = {
+  socketId: string
+  role: 'simulator' | 'app'
+  room: string | null
+  actorId: string | null
+  channels: Set<string>
+}
+```
+
+### 5.2 路由规则
+
+服务端收到 `publish` 后，只转发给满足以下条件的客户端：
+
+- `role === 'app'`
+- `room` 一致
+- `actorId` 一致
+- `channels` 包含当前 `channel`
+
+这一步完成后，多人使用同一个公网服务时就不会互串。
+
+### 5.3 第一阶段不需要的复杂能力
+
+第一阶段不建议先做：
+
+- 房间成员列表
+- 在线人数统计
+- 历史消息回放
+- 房间消息缓存
+- 权限控制
+
+这些可以等基础隔离跑通后再扩。
+
+---
+
+## 6. 小程序侧改造建议
+
+### 6.1 调试面板新增字段
+
+建议在调试面板中新增：
+
+- `Mock Room`
+- `Mock Actor`
+- `保存房间/身份`
+
+当前 GPS 和心率已经都有 mock bridge，后续建议最终共用同一个逻辑目标：
+
+- 同一个桥接地址
+- 同一个 `room`
+- 同一个 `actorId`
+
+### 6.2 连接流程
+
+小程序连上 mock bridge 后，自动发送：
+
+```json
+{
+  "type": "subscribe",
+  "room": "...",
+  "actorId": "...",
+  "channels": ["gps", "heart_rate"]
+}
+```
+
+这样：
+
+- GPS 模拟只接自己的 `gps`
+- 心率模拟只接自己的 `heart_rate`
+
+### 6.3 当前架构适配性
+
+这项改造与当前架构是兼容的。
+
+原因：
+
+- 它主要发生在传感层和调试链
+- 不需要改规则层
+- 不需要改 telemetry 语义
+- 不需要改地图引擎主逻辑
+
+---
+
+## 7. 外部模拟器改造建议
+
+### 7.1 第一阶段 UI 最小改动
+
+模拟器左侧面板新增两个输入项：
+
+- `Room`
+- `Actor ID`
+
+后续所有 GPS / 心率发送都自动带上它们。
+
+### 7.2 推荐默认使用方式
+
+多人开发时建议：
+
+- 大家共用同一个公网服务地址
+- `room` 用项目或阶段名
+- `actorId` 用开发者自己名字或实例名
+
+示例：
+
+- room: `team-dev`
+- actorId: `zhangsan`
+- actorId: `lisi`
+
+### 7.3 后续可扩展能力
+
+后续如果要继续增强，可以加：
+
+- 房间成员列表
+- 一键复制当前房间配置
+- 旁观模式
+- 同房间多个 actor 同时显示
+- 共享路径模板
+
+---
+
+## 8. 为什么这项改造值得做
+
+这不只是为了多人开发方便。
+
+它还会直接为未来这些方向打基础：
+
+- 多人玩法联调
+- 团队对抗玩法
+- 领地争夺玩法
+- 多角色追逐玩法
+
+也就是说：
+
+今天为“多人模拟器”加的 `room + actorId + channel`，未来可以直接演进成多人玩法调试底座。
+
+---
+
+## 9. 建议实施顺序
+
+### 第一阶段
+
+- 服务端支持 `register_simulator / subscribe / publish`
+- 消息带 `room + actorId + channel`
+- 小程序支持订阅指定 `room + actorId`
+- 外部模拟器增加 `room / actorId`
+
+### 第二阶段
+
+- 增加房间成员列表
+- 增加在线状态
+- 增加多 actor 可视化
+
+### 第三阶段
+
+- 接多人玩法联调
+- 接角色维度
+- 接会话回放与共享调试
+
+---
+
+## 10. 第一阶段验收标准
+
+第一阶段完成后，至少应满足：
+
+1. 两个人同时连同一个公网模拟器服务，不串 GPS  
+2. 两个人同时连同一个公网模拟器服务，不串心率  
+3. 同一个房间中，不同 `actorId` 可以隔离  
+4. 一个小程序实例可以只接收自己配置的目标流  
+
+---
+
+## 11. 当前结论
+
+这项改造建议先保留为待开发事项。  
+当前阶段不急着实现，但应作为后续多人开发与多人玩法联调的重要底座能力。
+
--- a/doc/archive/notes/我的待办.md
+++ b/doc/archive/notes/我的待办.md
@@ -0,0 +1,5 @@
+
+结果页会根据客户的要求不停的变换，用什么方案能实现这个需求，其实其他的弹出内容也都存在这个问题，样式，内容都时根据客户需求变化的，怎样一种方案设计比较好呢？
+
+
+
				`@@ -0,0 +1,5 @@`

				`结果页会根据客户的要求不停的变换，用什么方案能实现这个需求，其实其他的弹出内容也都存在这个问题，样式，内容都时根据客户需求变化的，怎样一种方案设计比较好呢？`