cmr-mini/doc/debug/模拟器多通道联调最小方案.md

模拟器多通道联调最小方案

文档版本：v1.0 最后更新：2026-04-02

目标

在不引入房间系统、不增加复杂编排的前提下，让同一台本地模拟器服务能够同时承接多路联调数据，并保证不同联调对象之间的数据不串线。

方案

统一增加一个字段：

• channelId

三条链都带这个字段：

• mock-gps
• mock-hr
• debug-log

设计原则

• 不做 room / participant 管理
• 不做多人控制台编排
• 只解决“数据隔离”
• GPS、心率、日志三条链统一使用同一个模拟通道号

默认值

默认通道号：

"default"

空值、缺失值都归一化成：

"default"

消息格式

GPS

{
  "type": "mock_gps",
  "timestamp": 1712345678901,
  "channelId": "runner-a",
  "lat": 31.2304,
  "lon": 121.4737,
  "accuracyMeters": 6,
  "speedMps": 2.4,
  "headingDeg": 92
}

心率

{
  "type": "mock_heart_rate",
  "timestamp": 1712345678901,
  "channelId": "runner-a",
  "bpm": 148
}

调试日志

{
  "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 处理。

适用场景

• 两台手机同时接同一台本地模拟器服务
• 一个调试人员同时开多台模拟器页面
• 同时联调多个儿童设备

当前边界

这套最小方案只解决：

• 多路数据隔离

不解决：

• 房间管理
• 成员列表
• 批量启动/停止
• 同步起跑
• 多控制台协作

如果后面真的需要这些，再升级到房间模型。