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

doc/gameplay/联调架构阶段总结.md

@@ -0,0 +1,182 @@
+# 联调架构阶段总结
+> 文档版本：v1.0
+> 最后更新：2026-04-03 16:59:19
+
+## 1. 当前结论
+
+当前联调架构已经从“能联”升级为“可诊断、可回归、可收口”。
+
+这次阶段性进步的核心不是多了几个接口，而是三条链一起立住了：
+
+1. 标准测试链
+2. 结构化诊断链
+3. 多线程协作链
+
+也就是说，当前联调已经不再主要依赖：
+
+- 截图
+- 口头描述
+- 各自猜测
+
+而是可以依赖统一入口、统一日志和统一回写口径来定位问题。
+
+---
+
+## 2. 标准测试链
+
+backend 当前已经把联调入口收敛成标准路径：
+
+```text
+Bootstrap Demo
+-> 一键补齐 Runtime 并发布
+-> 一键标准回归
+-> play / launch / result / history 验证
+```
+
+当前这条链的价值是：
+
+- 从空白环境直接起链
+- 不再手工预铺多份 demo 对象
+- 同一条测试链可以反复执行
+- 回归结果有统一出口
+
+当前 workbench 已具备：
+
+- `Bootstrap Demo`
+- `一键补齐 Runtime 并发布`
+- `一键标准回归`
+- `回归结果汇总`
+
+---
+
+## 3. 稳定测试数据链
+
+当前联调环境已经不再只靠临时假数据，而是开始切入更接近生产的真实输入。
+
+当前已接入：
+
+- 真实 KML / 赛道文件
+- 真实地图资源 URL
+- manual 多赛道双 KML 输入
+- 三类显式 demo 入口：
+  - `evt_demo_001`
+  - `evt_demo_score_o_001`
+  - `evt_demo_variant_manual_001`
+
+当前阶段这条链的意义是：
+
+- 前后端终于在测同一套对象
+- demo 数据不再漂
+- 联调结果更接近生产环境
+
+---
+
+## 4. 结构化诊断链
+
+这次联调真正发生质变的关键，是结构化诊断口径已经建立。
+
+backend 当前已提供：
+
+- 分步执行日志
+- 真实错误
+- stack
+- 最后一次 curl
+- 预期判定
+- `当前 Launch 实际配置摘要`
+
+frontend 当前已配合提供：
+
+- `POST /dev/client-logs`
+- 首页、活动页、准备页、地图关键链路的主动上报
+- 更明确的本地诊断字段：
+  - `details.seq`
+  - `launchVariantId`
+  - `runtimeCourseVariantId`
+
+当前这条结构化诊断链意味着：
+
+- 不再只知道“失败了”
+- 可以知道：
+  - 卡在哪一步
+  - 当前 launch 实际拿到了什么
+  - 前端消费到了什么
+  - 是后端发布问题、前端消费问题，还是规则理解问题
+
+这也是为什么最近某些问题反复修改多轮仍未命中，而补上结构化日志后能一次定位成功。
+
+---
+
+## 5. 多线程协作链
+
+当前多线程联调已经形成稳定协作方式：
+
+- 总控 -> 后端：
+  - [t2b.md](D:/dev/cmr-mini/t2b.md)
+- 后端 -> 总控：
+  - [b2t.md](D:/dev/cmr-mini/b2t.md)
+- 总控 -> 前端：
+  - [t2f.md](D:/dev/cmr-mini/t2f.md)
+- 前端 -> 总控：
+  - [f2t.md](D:/dev/cmr-mini/f2t.md)
+
+这条协作链的作用是：
+
+- 前后端不再互相口头转述
+- 总控能统一收口
+- 阶段性结论能及时沉淀回：
+  - [文档索引](D:/dev/cmr-mini/doc/文档索引.md)
+  - [readme-develop.md](D:/dev/cmr-mini/readme-develop.md)
+
+---
+
+## 6. 当前阶段结论
+
+可以把当前状态明确成：
+
+### 6.1 已完成
+
+- 基础骨架
+- 活动运营域摘要第一刀
+- 联调标准化第一版
+
+### 6.2 正在推进
+
+- 真实输入替换
+- 更接近生产的联调环境
+
+### 6.3 暂不启动
+
+- 活动卡片（列表）产品化
+- 新玩家侧页面扩张
+- 更复杂后台运营功能
+
+---
+
+## 7. 下一步建议
+
+当前下一步不再是继续搭骨架，而是继续把真实输入往活动层推进。
+
+优先顺序建议：
+
+1. `content manifest`
+2. `presentation schema`
+3. 活动文案样例
+
+同时继续保持：
+
+- 前端只做联调回归和小修
+- 后端继续保证一键回归链稳定
+- 排障优先看：
+  - `回归结果汇总`
+  - `当前 Launch 实际配置摘要`
+  - `前端调试日志`
+
+---
+
+## 8. 一句话总结
+
+当前联调架构已经从“人肉协作”升级成：
+
+**标准测试链 + 结构化诊断链 + 多线程协作链**
+
+这代表系统已经从“能跑”进入“可持续联调、可持续收口、可逐步逼近生产”的阶段。