cmr-mini/tools/mock-gps-sim/README.md

Mock GPS Simulator

启动

在仓库根目录运行：

npm run mock-gps-sim

启动后：

• 新版工作台: http://127.0.0.1:17865/
• 旧版面板: http://127.0.0.1:17865/v1/
• 小程序定位模拟地址: ws://127.0.0.1:17865/mock-gps
• 小程序心率模拟地址: ws://127.0.0.1:17865/mock-hr
• 小程序调试日志地址: ws://127.0.0.1:17865/debug-log
• 资源代理: http://127.0.0.1:17865/proxy?url=<remote-url>

当前能力

• 直接载入 game.json
• 自动解析 map / mapmeta / course
• 自动切换自定义瓦片
• 自动渲染 KML 控制点
• 一键跳到开始点 / 结束点 / 任意检查点
• 地图点击跳点
• 实时连续发送 mock_gps
• 路径编辑
• 上传轨迹文件回放（GPX / KML / GeoJSON）
• 路径回放
• 速度、频率、精度调节
• 可选桥接到新实时网关
• 接收小程序侧 debug-log 调试日志

调试日志

调试日志 websocket 独立地址：

ws://127.0.0.1:17865/debug-log

发送消息格式：

{
  "type": "debug-log",
  "timestamp": 1712345678901,
  "scope": "gps-logo",
  "level": "info",
  "message": "wx.getImageInfo success",
  "payload": {
    "src": "https://example.com/logo.png"
  }
}

当前 UI 会通过独立日志通道把这类消息显示到“调试日志”区域。

第一阶段主要用于承接：

• gps-logo

后面可以继续扩到：

• compass
• h5
• content-card
• heart-rate

桥接到新网关

旧模拟器现在支持保留原有本地广播链路的同时，把数据旁路转发到新的 Go 实时网关。

默认行为：

• 小程序定位模拟继续连接 ws://127.0.0.1:17865/mock-gps
• 小程序心率模拟继续连接 ws://127.0.0.1:17865/mock-hr
• 调试日志单独连接 ws://127.0.0.1:17865/debug-log
• 页面里可以直接配置并启用新网关桥接
• 环境变量只作为服务启动时的默认值

页面里直接配置

启动模拟器后，打开：

http://127.0.0.1:17865/

如果需要旧版稳定界面，打开：

http://127.0.0.1:17865/v1/

在“新网关桥接”区域可以直接配置：

• 是否启用桥接
• 网关地址
• Producer Token
• Channel ID
• 目标 Device ID
• Group ID
• Source ID
• Source Mode
• 本地桥接预设

点“应用桥接配置”后立即生效，不需要重启模拟器。

预设说明：

• 预设保存在浏览器本地存储
• 适合多人联调时快速切换 deviceId / groupId / sourceId
• “套用预设”只会填入表单，不会自动提交到服务端
• 需要再点一次“应用桥接配置”才会真正切换运行时桥接目标

PowerShell 启动示例

在仓库根目录执行：

$env:MOCK_SIM_GATEWAY_ENABLED='1'
$env:MOCK_SIM_GATEWAY_URL='ws://127.0.0.1:18080/ws'
$env:MOCK_SIM_GATEWAY_TOKEN='dev-producer-token'
$env:MOCK_SIM_GATEWAY_CHANNEL_ID=''
$env:MOCK_SIM_GATEWAY_DEVICE_ID='child-001'
$env:MOCK_SIM_GATEWAY_SOURCE_ID='mock-gps-sim-a'
npm run mock-gps-sim

如果你使用新网关管理台创建的 channel，则要这样填：

$env:MOCK_SIM_GATEWAY_ENABLED='1'
$env:MOCK_SIM_GATEWAY_URL='ws://127.0.0.1:18080/ws'
$env:MOCK_SIM_GATEWAY_TOKEN='<producerToken>'
$env:MOCK_SIM_GATEWAY_CHANNEL_ID='<channelId>'
$env:MOCK_SIM_GATEWAY_DEVICE_ID='child-001'
npm run mock-gps-sim

说明：

• 不填 MOCK_SIM_GATEWAY_CHANNEL_ID 时，旧模拟器走老的 authenticate 模式
• 填了 MOCK_SIM_GATEWAY_CHANNEL_ID 时，旧模拟器自动走 join_channel 模式
• 管理台里复制出来的 producerToken 只能和对应的 channelId 配套使用

可用环境变量

• MOCK_SIM_GATEWAY_ENABLED
  • 1 表示启用桥接
• MOCK_SIM_GATEWAY_URL
  • 新网关地址，默认 ws://127.0.0.1:18080/ws
• MOCK_SIM_GATEWAY_TOKEN
  • Producer token，默认 dev-producer-token
• MOCK_SIM_GATEWAY_CHANNEL_ID
  • 可选 channel id；填写后会改走 join_channel
• MOCK_SIM_GATEWAY_DEVICE_ID
  • 转发目标 deviceId，默认 child-001
• MOCK_SIM_GATEWAY_GROUP_ID
  • 可选 groupId
• MOCK_SIM_GATEWAY_SOURCE_ID
  • source id，默认 mock-gps-sim
• MOCK_SIM_GATEWAY_SOURCE_MODE
  • source mode，默认 mock
• MOCK_SIM_GATEWAY_RECONNECT_MS
  • 断线重连间隔，默认 3000

桥接状态查看

启动后可查看：

http://127.0.0.1:17865/bridge-status

桥接配置接口：

http://127.0.0.1:17865/bridge-config

返回内容包含：

• 是否启用桥接
• 是否已连上新网关
• 是否已认证
• 最近发送 topic
• 已发送条数
• 丢弃条数
• 最近错误

加载自己的地图

推荐方式：

1. 启动模拟器后，打开 http://127.0.0.1:17865/
2. 在“资源加载”里填自己的 game.json 地址
3. 点“载入配置”

模拟器会自动：

• 读取 map 和 mapmeta
• 切换到你的瓦片底图
• 读取 course
• 渲染开始点、检查点、结束点

如果你不想走整套配置，也可以：

• 直接填“瓦片模板”，例如 https://host/tiles/{z}/{x}/{y}.webp
• 直接填 KML URL

路径回放也支持直接导入轨迹文件：

• GPX
• KML
• GeoJSON / JSON

说明：

• 配置和 KML 是通过本地代理拉取的，所以浏览器跨域问题会少很多
• 如果你的资源需要鉴权，第一版代理还没有加认证头透传

真机调试注意

如果小程序跑在手机上，不要用 127.0.0.1。
把小程序里的 mock bridge 地址改成你电脑在局域网里的 IP，例如：

ws://192.168.1.23:17865/mock-gps

心率模拟地址应配置为：

ws://192.168.1.23:17865/mock-hr

同理，浏览器里的模拟器页面也建议用电脑局域网地址打开，例如：

http://192.168.1.23:17865/

如果你要在小程序里看调试日志，Logger 地址应配置为：

ws://192.168.1.23:17865/debug-log