# 模拟器调试日志方案

## 目标

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

第一阶段只做最小闭环：

- 复用 `tools/mock-gps-sim` 现有服务
- 增加 `debug-log` 消息类型
- 小程序侧增加最小 logger
- 第一批只发送 `gps-logo` 范围日志

## 设计原则

- 调试面板看“当前状态”
- 模拟器日志看“变化过程”
- 日志链只在开发/调试期间启用
- 不进入正式玩法逻辑
- 不把高频临时日志继续塞进页面 WXML

## 协议

消息类型：

```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",
    "path": "wxfile://tmp_xxx"
  }
}
```

字段说明：

- `type`
  固定为 `debug-log`
- `timestamp`
  毫秒时间戳
- `scope`
  日志分类，例如 `gps-logo`、`h5`、`compass`
- `channelId`
  日志所属模拟通道，用于多人联调时隔离不同设备的过程日志
- `level`
  `info / warn / error`
- `message`
  简短可读说明
- `payload`
  可选附加对象，用于排查细节

## 第一阶段 scope

第一批只接：

- `gps-logo`

典型日志点：

- logo 未配置
- 当前风格不是 `badge`
- 开始加载 logo
- `wx.getImageInfo` 成功
- `wx.getImageInfo` 失败
- 图片 `onload`
- 图片 `onerror`

## 小程序侧实现

新增：

- `miniprogram/engine/debug/mockSimulatorDebugLogger.ts`

职责：

- 复用 mock GPS simulator websocket 地址
- 负责连接、断开、简单队列、发送 `debug-log`
- 只在调试 UI 开启时启用

接入点：

- `MapEngine`
  - 调试 UI 开启时启用 logger
  - 调试 UI 关闭时关闭 logger
  - mock bridge 地址变化时同步 logger 地址
- `CourseLabelRenderer`
  - 发送 `gps-logo` 相关日志

## 模拟器侧实现

复用：

- `tools/mock-gps-sim/server.js`
- `tools/mock-gps-sim/public/index.html`
- `tools/mock-gps-sim/public/simulator.js`

最小能力：

- websocket 接收 `debug-log`
- UI 新增“调试日志”区域
- 仅显示 `debug-log`
- 保留最近若干条，避免无限增长

## 后续扩展

第二阶段可以再补：

- `compass`
- `h5`
- `content-card`
- `heart-rate`

第三阶段再补：

- scope 过滤
- level 过滤
- 暂停滚动
- 导出日志

## 当前结论

先把 `gps-logo` 调试链打通，再回头用模拟器日志查 logo 为什么不显示，比继续把临时字段堆在调试面板里更稳。