mini-prog/doc/debug/模拟器调试日志方案.md

模拟器调试日志方案

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

目标

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

第一阶段只做最小闭环：

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

设计原则

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

协议

消息类型：

{
  "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
• 支持按 scope 过滤
• 按当前 channelId 过滤显示
• 保留最近若干条，避免无限增长

后续扩展

第二阶段可以再补：

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

第三阶段再补：

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

当前结论

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