# 联调架构阶段总结
> 文档版本：v1.1
> 最后更新：2026-04-07 22:38:00

## 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 已进入当前最小成品闭环范围

- 活动卡片列表最小产品化第一刀
- 地图体验第一刀
- 游客模式第一刀
- 准备页地图预览 V1

### 6.4 当前后端收口原则

- backend 第一阶段活动模型先按：
  - 单地图
  - 单路线组
  - 单玩法
  收口推进
- 复杂多地图 / 多路线组 / 多玩法活动，后续通过：
  - 活动实例化
  - 组合入口层
  - 组合卡片层
  解决

---

## 7. 下一步建议

当前下一步不再是继续搭骨架，而是把已经接通的玩家链真正收顺，并继续保持联调环境接近生产。

优先顺序建议：

1. 活动列表第一刀联调回归与小修
2. 活动详情页 / 准备页去工程味
3. 地图体验链 / 游客体验链整链回归
4. 继续使用：
   - `Bootstrap Demo`
   - `一键补齐 Runtime 并发布`
   - `一键标准回归`
   做统一验证

同时继续保持：

- 前端不扩第二刀产品化
- 后端继续保证一键回归链稳定
- 后端按单地图 / 单路线组 / 单玩法先收模型
- 排障优先看：
  - `回归结果汇总`
  - `当前 Launch 实际配置摘要`
  - `前端调试日志`

---

## 8. 一句话总结

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

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

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