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

2026-04-03 17:01:04 +08:00
parent 114c524044
commit b09c21c814
35 changed files with 2677 additions and 175 deletions
--- a/backend/docs/开发说明.md
+++ b/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. 当前开发约定

--- a/backend/docs/接口清单.md
+++ b/backend/docs/接口清单.md
@@ -1,6 +1,6 @@
 # API 清单
-> 文档版本：v1.8
-> 最后更新：2026-04-03 12:36:15
+> 文档版本：v1.9
+> 最后更新：2026-04-03 16:16:38


 本文档只记录当前 backend 已实现接口，不写未来规划接口。
@@ -436,6 +436,61 @@

 - 自动准备 demo tenant / channel / event / release / card

+### `POST /dev/client-logs`
+
+环境：
+
+- 仅 non-production
+
+用途：
+
+- 接收 frontend 主动上报的调试日志
+- 供 backend 通过 workbench 统一查看和排查
+
+请求体重点：
+
+- `source`
+- `level`
+- `category`
+- `message`
+- `eventId`
+- `releaseId`
+- `sessionId`
+- `manifestUrl`
+- `route`
+- `occurredAt`
+- `details`
+
+补充说明：
+
+- 当前只保存在内存中
+- 默认最多保留最近 200 条
+- 仅用于联调调试
+
+### `GET /dev/client-logs`
+
+环境：
+
+- 仅 non-production
+
+用途：
+
+- 获取 frontend 最近上报的调试日志
+
+查询参数：
+
+- `limit`
+
+### `DELETE /dev/client-logs`
+
+环境：
+
+- 仅 non-production
+
+用途：
+
+- 清空当前内存中的 frontend 调试日志
+
 ### `GET /dev/workbench`

 环境：
@@ -459,6 +514,26 @@
 - scenarios
 - request history
 - curl 导出
+- frontend 调试日志查看/清空
+
+### `GET /dev/manifest-summary`
+
+环境：
+
+- 仅 non-production
+
+用途：
+
+- 由 backend 代读指定 manifest
+- 返回最小调试摘要：
+  - `schemaVersion`
+  - `playfield.kind`
+  - `game.mode`
+
+补充说明：
+
+- 只用于 workbench 联调排查
+- 不参与正式客户端运行链路

 ### `GET /dev/config/local-files`