chore: 提交调试文档与模拟器改动

2026-04-01 13:12:39 +08:00
parent 3ef841ecc7
commit 175a16001e
14 changed files with 1695 additions and 315 deletions
--- a/doc/debug/模拟器多通道联调最小方案.md
+++ b/doc/debug/模拟器多通道联调最小方案.md
@@ -0,0 +1,141 @@
+# 模拟器多通道联调最小方案
+
+## 目标
+
+在不引入房间系统、不增加复杂编排的前提下，让同一台本地模拟器服务能够同时承接多路联调数据，并保证不同联调对象之间的数据不串线。
+
+## 方案
+
+统一增加一个字段：
+
+- `channelId`
+
+三条链都带这个字段：
+
+- `mock-gps`
+- `mock-hr`
+- `debug-log`
+
+## 设计原则
+
+- 不做 room / participant 管理
+- 不做多人控制台编排
+- 只解决“数据隔离”
+- GPS、心率、日志三条链统一使用同一个模拟通道号
+
+## 默认值
+
+默认通道号：
+
+```json
+"default"
+```
+
+空值、缺失值都归一化成：
+
+```json
+"default"
+```
+
+## 消息格式
+
+### GPS
+
+```json
+{
+  "type": "mock_gps",
+  "timestamp": 1712345678901,
+  "channelId": "runner-a",
+  "lat": 31.2304,
+  "lon": 121.4737,
+  "accuracyMeters": 6,
+  "speedMps": 2.4,
+  "headingDeg": 92
+}
+```
+
+### 心率
+
+```json
+{
+  "type": "mock_heart_rate",
+  "timestamp": 1712345678901,
+  "channelId": "runner-a",
+  "bpm": 148
+}
+```
+
+### 调试日志
+
+```json
+{
+  "type": "debug-log",
+  "timestamp": 1712345678901,
+  "channelId": "runner-a",
+  "scope": "gps-logo",
+  "level": "info",
+  "message": "logo ready",
+  "payload": {
+    "src": "https://example.com/logo.png"
+  }
+}
+```
+
+## 模拟器侧
+
+新版工作台提供一个统一输入：
+
+- `模拟通道号`
+
+它会同时作用于：
+
+- GPS 发送
+- 心率发送
+- 日志过滤
+
+也就是说，一个模拟器页面实例默认对应一个通道。
+
+## 小程序侧
+
+调试面板提供一个统一输入：
+
+- `模拟通道号`
+
+保存后会同步给：
+
+- 定位模拟接收过滤
+- 心率模拟接收过滤
+- logger 发送通道
+
+“一键连接开发调试源”会带上当前通道号一起生效。
+
+## 接收规则
+
+接收端统一按归一化后的 `channelId` 精确匹配：
+
+- 收到的消息 `channelId` 与当前模拟通道号一致才消费
+- 不一致直接忽略
+
+缺失 `channelId` 的旧消息，按 `default` 处理。
+
+## 适用场景
+
+- 两台手机同时接同一台本地模拟器服务
+- 一个调试人员同时开多台模拟器页面
+- 同时联调多个儿童设备
+
+## 当前边界
+
+这套最小方案只解决：
+
+- 多路数据隔离
+
+不解决：
+
+- 房间管理
+- 成员列表
+- 批量启动/停止
+- 同步起跑
+- 多控制台协作
+
+如果后面真的需要这些，再升级到房间模型。
--- a/doc/debug/模拟器控制面板重构方案.md
+++ b/doc/debug/模拟器控制面板重构方案.md
@@ -2,22 +2,22 @@

 ## 目标

-在不破坏现有老版面板的前提下，新增一套新版控制面板，用于承接更复杂的开发调试工作流。
+在不增加第二套历史 UI 负担的前提下，整理出一套新版控制面板，用于承接更复杂的开发调试工作流。

 重构目标：

- 保留老版入口，确保已有使用习惯不受影响
 - 新增工作台式面板，提升连接、控制、观察、排障效率
 - 继续复用现有模拟器脚本和 websocket 协议，避免维护两套逻辑
+- 最终只保留新版入口，避免长期双份维护

 ## 设计原则

-1. 新旧并行
+1. 单入口维护
   - 新版入口使用 `/`
-   - 旧版入口保留在 `/v1/`
+   - 模拟器只保留一个工作台入口
 2. 逻辑复用
-   - 两个页面共用 `simulator.js`
-   - 只通过不同 HTML 布局和 CSS 风格区分
+   - 继续复用 `simulator.js`
+   - 只维护一套 HTML 布局和 CSS 风格
 3. 面向调试流程
   - 连接优先
   - 控制第二
@@ -44,7 +44,6 @@
 - 心率模拟连接状态
 - 调试日志连接状态
 - 一键连接开发调试源
- 新旧面板切换入口

 ### 2. 左侧控制区

@@ -83,26 +82,16 @@
 - 面积更大
 - 便于边看地图边看日志

-## 与旧版的关系
-
-旧版和新版应同时可用：
-
- 新版作为默认工作台
- 旧版继续作为稳定基线
- 问题排查时可快速回退旧版
-
 ## 实施顺序

 1. 根路径切换到新版工作台
 2. 新增新版样式 `workbench.css`
 3. 复用现有 `simulator.js`
-4. 旧版页面迁移到 `/v1/`
-5. 在旧版和新版之间互相添加跳转入口
-6. 更新 README 和调试文档索引
+4. 清理历史入口和旧文案
+5. 更新 README 和调试文档索引

 ## 验收标准

- 老版页面继续正常工作
 - 新版页面可完整使用现有 GPS、心率、日志、路径、网关能力
- 两个页面共用同一套 websocket 协议和数据逻辑
- 用户可以在两个版本之间切换
+- 模拟器只保留一个工作台入口
+- websocket 协议和调试逻辑继续复用
--- a/doc/debug/模拟器调试日志方案.md
+++ b/doc/debug/模拟器调试日志方案.md
@@ -2,11 +2,11 @@

 ## 目标

-复用现有 GPS 模拟器 websocket，在不污染地图调试面板的前提下，把高频、临时、开发期日志输出到外部模拟器。
+复用现有模拟器服务，在不污染地图调试面板的前提下，把高频、临时、开发期日志输出到外部模拟器。

 第一阶段只做最小闭环：

- 复用 `tools/mock-gps-sim` 现有 websocket
+- 复用 `tools/mock-gps-sim` 现有服务
 - 增加 `debug-log` 消息类型
 - 小程序侧增加最小 logger
 - 第一批只发送 `gps-logo` 范围日志
@@ -27,6 +27,7 @@
 {
  "type": "debug-log",
  "timestamp": 1712345678901,
+  "channelId": "runner-a",
  "scope": "gps-logo",
  "level": "info",
  "message": "wx.getImageInfo success",
@@ -45,6 +46,8 @@
  毫秒时间戳
 - `scope`
  日志分类，例如 `gps-logo`、`h5`、`compass`
+- `channelId`
+  日志所属模拟通道，用于多人联调时隔离不同设备的过程日志
 - `level`
  `info / warn / error`
 - `message`
@@ -123,4 +126,3 @@
 ## 当前结论

 先把 `gps-logo` 调试链打通，再回头用模拟器日志查 logo 为什么不显示，比继续把临时字段堆在调试面板里更稳。
-
--- a/doc/debug/调试文档索引.md
+++ b/doc/debug/调试文档索引.md
@@ -10,11 +10,13 @@
 ## 当前主文档

 - [模拟器控制面板重构方案](/D:/dev/cmr-mini/doc/debug/模拟器控制面板重构方案.md)
-  用于说明新版模拟器工作台布局、新旧并行策略和重构目标。
+  用于说明新版模拟器工作台布局和重构目标。
 - [平台能力说明](/D:/dev/cmr-mini/doc/debug/平台能力说明.md)
  用于记录主体能力、`web-view`、传感器等平台边界。
 - [模拟器调试日志方案](/D:/dev/cmr-mini/doc/debug/模拟器调试日志方案.md)
  用于说明 mock simulator 的日志旁路与 `debug-log` 协议。
+- [模拟器多通道联调最小方案](/D:/dev/cmr-mini/doc/debug/模拟器多通道联调最小方案.md)
+  用于说明 GPS / 心率 / 日志三条链统一按 `channelId` 隔离的最小实现。
 - [传感器当前状态总结](/D:/dev/cmr-mini/doc/debug/传感器现状总结.md)
  用于看当前已确认的传感器状态与调试结论。
 - [罗盘问题记录](/D:/dev/cmr-mini/doc/debug/罗盘排障记录.md)
@@ -26,11 +28,13 @@
 2. [mock-simulator-control-panel-proposal.md](/D:/dev/cmr-mini/doc/debug/模拟器控制面板重构方案.md)
 3. [sensor-current-summary.md](/D:/dev/cmr-mini/doc/debug/传感器现状总结.md)
 4. [mock-simulator-debug-log-proposal.md](/D:/dev/cmr-mini/doc/debug/模拟器调试日志方案.md)
-5. [compass-debugging-notes.md](/D:/dev/cmr-mini/doc/debug/罗盘排障记录.md)
+5. [multi-channel-simulator-minimal-plan.md](/D:/dev/cmr-mini/doc/debug/模拟器多通道联调最小方案.md)
+6. [compass-debugging-notes.md](/D:/dev/cmr-mini/doc/debug/罗盘排障记录.md)

 ## 使用建议

 - 看“当前限制”和“为什么会这样”，优先看平台能力说明。
 - 看“现在系统是什么状态”，优先看传感器现状总结。
 - 看“以后日志怎么打”，优先看模拟器日志方案。
+- 看“多人联调怎么隔离”，优先看模拟器多通道联调最小方案。
 - 看“为什么罗盘以前坏过”，再去看罗盘问题记录。