# Mock GPS Simulator
> 文档版本：v1.0
> 最后更新：2026-04-02 08:28:05


## 启动

在仓库根目录运行：

```bash
npm run mock-gps-sim
```

启动后：

- 新版工作台: `http://127.0.0.1:17865/`
- 小程序定位模拟地址: `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>`

补充说明：

- 模拟器工作台内部现在会按当前页面地址自动推导 websocket 地址。
- 本地访问 `http://127.0.0.1:17865/` 时，会自动连接：
  - `ws://127.0.0.1:17865/mock-gps`
  - `ws://127.0.0.1:17865/mock-hr`
  - `ws://127.0.0.1:17865/debug-log`
- 外网访问例如 `https://gs.gotomars.xyz/` 时，会自动连接同源：
  - `wss://gs.gotomars.xyz/mock-gps`
  - `wss://gs.gotomars.xyz/mock-hr`
  - `wss://gs.gotomars.xyz/debug-log`
- 因此外网页面不能再把 `https://gs.gotomars.xyz/` 当作 websocket 地址手工填写；应直接使用对应的 `wss://...` 路径，或让工作台按同源自动连接。

## 多通道联调

模拟器现在支持一个最小的多通道隔离方案：

- GPS 模拟消息带 `channelId`
- 心率模拟消息带 `channelId`
- 调试日志消息带 `channelId`
- 小程序端按同一个模拟通道号过滤三条链

默认通道号：

```text
default
```

如果需要多人并行联调，可以在模拟器工作台里把“模拟通道号”改成例如：

```text
runner-a
runner-b
group-01
```

然后在小程序调试面板里把“模拟通道号”也配成同一个值。

当前“模拟通道号”位于工作台顶部，属于全局调试参数，不再归属某个单独分组。

## 当前能力

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

## 调试日志

调试日志 websocket 独立地址：

```text
ws://127.0.0.1:17865/debug-log
```

发送消息格式：

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

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

日志区域当前是：

- 地图右下角浮层
- 可展开 / 缩小
- 支持按 `scope` 过滤
- 按当前 `channelId` 隔离显示

第一阶段主要用于承接：

- `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`
- 页面里可以直接配置并启用新网关桥接
- 环境变量只作为服务启动时的默认值

### 页面里直接配置

启动模拟器后，打开：

```text
http://127.0.0.1:17865/
```

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

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

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

预设说明：

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

### PowerShell 启动示例

在仓库根目录执行：

```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`，则要这样填：

```powershell
$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`

### 桥接状态查看

启动后可查看：

```text
http://127.0.0.1:17865/bridge-status
```

桥接配置接口：

```text
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，例如：

```text
ws://192.168.1.23:17865/mock-gps
```

心率模拟地址应配置为：

```text
ws://192.168.1.23:17865/mock-hr
```

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

```text
http://192.168.1.23:17865/
```

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

```text
ws://192.168.1.23:17865/debug-log
```