完善样式系统与调试链路底座

doc/mock-simulator-debug-log-proposal.md

@@ -0,0 +1,125 @@
+# 模拟器调试日志方案
+
+## 目标
+
+复用现有 GPS 模拟器 websocket，在不污染地图调试面板的前提下，把高频、临时、开发期日志输出到外部模拟器。
+
+第一阶段只做最小闭环：
+
+- 复用 `tools/mock-gps-sim` 现有 websocket
+- 增加 `debug-log` 消息类型
+- 小程序侧增加最小 logger
+- 第一批只发送 `gps-logo` 范围日志
+
+## 设计原则
+
+- 调试面板看“当前状态”
+- 模拟器日志看“变化过程”
+- 日志链只在开发/调试期间启用
+- 不进入正式玩法逻辑
+- 不把高频临时日志继续塞进页面 WXML
+
+## 协议
+
+消息类型：
+
+```json
+{
+  "type": "debug-log",
+  "timestamp": 1712345678901,
+  "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`
+- `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 为什么不显示，比继续把临时字段堆在调试面板里更稳。