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

联调架构阶段总结

文档版本：v1.0 最后更新：2026-04-03 16:59:19

1. 当前结论

当前联调架构已经从“能联”升级为“可诊断、可回归、可收口”。

这次阶段性进步的核心不是多了几个接口，而是三条链一起立住了：

1. 标准测试链
2. 结构化诊断链
3. 多线程协作链

也就是说，当前联调已经不再主要依赖：

• 截图
• 口头描述
• 各自猜测

而是可以依赖统一入口、统一日志和统一回写口径来定位问题。

---

2. 标准测试链

backend 当前已经把联调入口收敛成标准路径：

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
• 后端 -> 总控：
  • b2t.md
• 总控 -> 前端：
  • t2f.md
• 前端 -> 总控：
  • f2t.md

这条协作链的作用是：

• 前后端不再互相口头转述
• 总控能统一收口
• 阶段性结论能及时沉淀回：
  • 文档索引
  • readme-develop.md

---

6. 当前阶段结论

可以把当前状态明确成：

6.1 已完成

• 基础骨架
• 活动运营域摘要第一刀
• 联调标准化第一版

6.2 正在推进

• 真实输入替换
• 更接近生产的联调环境

6.3 暂不启动

• 活动卡片（列表）产品化
• 新玩家侧页面扩张
• 更复杂后台运营功能

---

7. 下一步建议

当前下一步不再是继续搭骨架，而是继续把真实输入往活动层推进。

优先顺序建议：

1. content manifest
2. presentation schema
3. 活动文案样例

同时继续保持：

• 前端只做联调回归和小修
• 后端继续保证一键回归链稳定
• 排障优先看：
  • 回归结果汇总
  • 当前 Launch 实际配置摘要
  • 前端调试日志

---

8. 一句话总结

当前联调架构已经从“人肉协作”升级成：

标准测试链 + 结构化诊断链 + 多线程协作链

这代表系统已经从“能跑”进入“可持续联调、可持续收口、可逐步逼近生产”的阶段。