完善联调标准化与诊断链路

backend/docs/开发说明.md

@@ -1,6 +1,6 @@
 # 开发说明
-> 文档版本：v1.14
-> 最后更新：2026-04-03 20:10:25
+> 文档版本：v1.20
+> 最后更新：2026-04-03 16:16:38
 
 
 ## 1. 环境变量
@@ -39,6 +39,35 @@ cd D:\dev\cmr-mini\backend
 .\scripts\start-dev.ps1
 ```
 
+## 3. Workbench 当前重点
+
+- 推荐联调入口：
+  - `Bootstrap Demo`
+  - `Use Classic Demo / Use Score-O Demo / Use Manual Variant Demo`
+  - `整条链一键验收`
+- 如果 frontend 需要把页面侧调试日志直接打到 backend，优先使用：
+  - `POST /dev/client-logs`
+  - 然后在 workbench 的 `前端调试日志` 面板里查看
+- 如果需要判断前端到底拿到了哪份配置，优先看 workbench 的：
+  - `当前 Launch 实际配置摘要`
+- 这块会直接显示：
+  - `configUrl`
+  - `releaseId`
+  - `manifestUrl`
+  - `schemaVersion`
+  - `playfield.kind`
+  - `game.mode`
+- 这组信息用于和前端地图页实际消费结果对口排查，避免只靠口头描述“像顺序赛/像积分赛”。
+- 注意：
+  - 这块摘要由 backend 代读 manifest，只用于 workbench 调试
+  - 这样做是为了避免浏览器直接读取 OSS 时受跨域影响
+  - 它不替代正式客户端加载逻辑
+  - 正式客户端仍必须直接消费 `launch.config.configUrl` 或 `launch.resolvedRelease.manifestUrl`
+- `前端调试日志` 也是调试专用能力：
+  - backend 当前只在内存里保留最近 200 条
+  - 适合前端把关键事实直接打进来，避免只靠截图和口头描述
+  - 不替代正式生产日志体系
+
 默认会设置：
 
 - `APP_ENV=development`
@@ -72,8 +101,12 @@ cd D:\dev\cmr-mini\backend
 当前推荐顺序：
 
 1. `Bootstrap Demo`
-2. `一键补齐 Runtime 并发布`
-3. `一键标准回归`
+2. 选择一种玩法入口：
+   - `Use Classic Demo`
+   - `Use Score-O Demo`
+   - `Use Manual Variant Demo`
+3. `一键补齐 Runtime 并发布`
+4. `一键标准回归`
 
 当前这条一键链会自动完成：
 
@@ -94,6 +127,20 @@ cd D:\dev\cmr-mini\backend
 - `play / launch / result / history` 回归汇总
 - demo 活动残留 ongoing session 清理：
   - 会把 demo event 下历史遗留的 `launched / running` session 自动改成 `cancelled`
+- 真实输入替换第一刀：
+  - `CourseSource.fileUrl` 当前已切到真实 KML：
+    - `https://oss-mbh5.colormaprun.com/gotomars/kml/lxcb-001/10/c01.kml`
+    - `https://oss-mbh5.colormaprun.com/gotomars/kml/lxcb-001/10/c02.kml`
+  - `TileRelease.tileBaseUrl / metaUrl` 当前已切到真实地图资源：
+    - `https://oss-mbh5.colormaprun.com/gotomars/map/lxcb-001/tiles/`
+    - `https://oss-mbh5.colormaprun.com/gotomars/map/lxcb-001/tiles/meta.json`
+  - manual 多赛道 demo 当前已使用两条真实赛道输入：
+    - `variant_a -> c01.kml`
+    - `variant_b -> c02.kml`
+  - 显式玩法测试入口：
+    - 顺序赛：`evt_demo_001 -> rel_demo_001 -> classic-sequential.json`
+    - 积分赛：`evt_demo_score_o_001 -> rel_demo_score_o_001 -> score-o.json`
+    - 多赛道：`evt_demo_variant_manual_001 -> rel_demo_variant_manual_001`
 
 当前日志能力：
 
@@ -116,6 +163,60 @@ cd D:\dev\cmr-mini\backend
   - `History`
   - `Session ID`
   - `总判定`
+- workbench 现在还支持查看 frontend 主动上报的调试日志：
+  - `拉取前端日志`
+  - `清空前端日志`
+  - 前端建议最少带：
+    - `eventId`
+    - `releaseId`
+    - `sessionId`
+    - `manifestUrl`
+    - `route`
+    - `game.mode`
+    - `playfield.kind`
+    - 当前页面阶段或动作名
+
+### 2.2 前端调试日志最小约定
+
+dev 环境下，frontend 可直接把关键调试事实发到 backend：
+
+- `POST /dev/client-logs`
+
+建议请求体最少包含：
+
+```json
+{
+  "source": "miniprogram",
+  "level": "info",
+  "category": "runtime",
+  "message": "map page loaded manifest",
+  "eventId": "evt_demo_score_o_001",
+  "releaseId": "rel_xxx",
+  "sessionId": "sess_xxx",
+  "manifestUrl": "https://oss-mbh5.colormaprun.com/...",
+  "route": "pages/map/map",
+  "occurredAt": "2026-04-03T16:16:38+08:00",
+  "details": {
+    "schemaVersion": "1",
+    "playfield.kind": "control-set",
+    "game.mode": "score-o",
+    "phase": "map-init"
+  }
+}
+```
+
+当前说明：
+
+- `source`：建议填终端来源，例如 `miniprogram`
+- `level`：建议填 `info / warn / error`
+- `category`：建议填 `launch / runtime / cache / network`
+- `message`：一句话说明当前发生了什么
+- `details`：放结构化调试细节，backend 原样收下
+
+辅助接口：
+
+- `GET /dev/client-logs?limit=50`
+- `DELETE /dev/client-logs`
 
 ## 3. 当前开发约定