完善多赛道联调与全局产品架构

backend/docs/todolist.md

@@ -1,6 +1,6 @@
 # Backend TodoList
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.2
+> 最后更新：2026-04-02 11:03:02
 
 
 ## 1. 目标
@@ -37,6 +37,8 @@
 
 - `evt_demo_001` 的 release manifest 现已可正常加载
 - 小程序已能进入地图
+- `launch` 关键字段在当前阶段不再单边漂移
+- `cancelled / failed / finished` 已从 ongoing 口径里收稳
 - 模拟定位 / 调试日志问题已回到小程序与模拟器侧，不再属于 backend 当前阻塞
 
 前端当前需要配合的事项：
@@ -160,27 +162,36 @@ backend 现在需要做的是：
 
 ## 4. P1 应尽快做
 
-## 4.1 给首页 / play / result 的 ongoing 语义再做一次回归确认
+## 4.1 多赛道 Variant 第一阶段最小契约
 
-当前前端已经开始走：
+当前前端已给出：
 
-- 首页聚合
-- `event play`
-- `launch`
-- `session start / finish`
-- 本地故障恢复
+- [多赛道 Variant 五层设计草案](D:/dev/cmr-mini/doc/gameplay/多赛道Variant五层设计草案.md)
+- [多赛道 Variant 前后端最小契约](D:/dev/cmr-mini/doc/gameplay/多赛道Variant前后端最小契约.md)
 
-backend 建议再回归确认这几个接口对“进行中 session”的口径一致：
+backend 当前建议第一阶段只做最小闭环：
 
-- `/me/entry-home`
-- `/events/{eventPublicID}/play`
-- `/sessions/{sessionPublicID}/result`
+- `play.assignmentMode`
+- `play.courseVariants[]`
+- `launch.variant.*`
+- `session / result / ongoing / recent` 补 `variantId / variantName / routeCode`
 
-重点确认：
+当前目标：
 
-1. `cancelled` 后不再继续出现在 ongoing 入口
-2. `failed` 后不再继续出现在 ongoing 入口
-3. `finished` 后结果页与首页摘要字段一致
+1. 一个 session 最终只绑定一个 `variantId`
+2. `launch` 返回最终绑定结果
+3. 恢复链不重新分配 variant
+4. 结果页、ongoing、历史结果都能追溯 variant
+
+备注：
+
+- 当前只先定最小契约，不先做完整后台 variant 编排模型
+- 当前第一阶段最小后端链路已补入：
+  - `play.assignmentMode`
+  - `play.courseVariants[]`
+  - `launch.variant.*`
+  - `session / result / ongoing / recent` 的 `variantId / variantName / routeCode`
+- 下一步应由前端按该契约联调，不再继续扩后台 variant 模型
 
 ## 4.2 增加用户身体资料读取接口
 
@@ -318,18 +329,18 @@ backend 后面如果要接业务结果页，最好提前定：
 
 ## 7. 我建议的最近动作
 
-backend 现在最值得先做的，不是扩接口，而是先确认下面 3 条：
+backend 现在最值得先做的，不是继续铺更多页面接口，而是先推进下面 3 条：
 
-1. `finished / failed / cancelled` 三态语义
-2. 放弃恢复是否写 `cancelled`
-3. `start / finish` 是否按幂等处理
+1. 与前端确认多赛道第一阶段最小契约
+2. 已按最小契约扩完 `play -> launch -> session/result`
+3. 再补用户身体资料接口和 workbench 恢复场景按钮
 
-这 3 条一旦确定，前后端联调会顺很多。
+这样不会打断当前主链，同时能把下一阶段多赛道联调接上。
 
 ## 8. 一句话结论
 
 当前 backend 最重要的任务不是“再加更多接口”，而是：
 
-> 先把 session 运行态语义、放弃恢复语义和 ongoing session 口径定稳，再继续扩后台配置系统。
+> 在不破坏当前稳定主链的前提下，先把多赛道 Variant 第一阶段最小契约定稳，再继续向配置与后台模型延伸。
 
 

backend/docs/开发说明.md

@@ -1,6 +1,6 @@
 # 开发说明
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.1
+> 最后更新：2026-04-02 09:35:44
 
 
 ## 1. 环境变量
@@ -51,6 +51,11 @@ cd D:\dev\cmr-mini\backend
 
 - [http://127.0.0.1:18090/dev/workbench](http://127.0.0.1:18090/dev/workbench)
 
+当前 workbench 已覆盖两类调试链：
+
+- 用户主链：`bootstrap -> auth -> entry/home -> event play/launch -> session -> result`
+- 后台运营链：`maps/playfields/resource-packs -> admin event source -> build -> publish -> rollback`
+
 ## 3. 当前开发约定
 
 ### 3.1 开发阶段先不用 Redis

backend/docs/接口清单.md

@@ -1,6 +1,6 @@
 # API 清单
-> 文档版本：v1.0
-> 最后更新：2026-04-02 09:01:17
+> 文档版本：v1.1
+> 最后更新：2026-04-02 11:05:32
 
 
 本文档只记录当前 backend 已实现接口，不写未来规划接口。
@@ -121,6 +121,12 @@
 - `ongoingSession`
 - `recentSession`
 
+`ongoingSession / recentSession` 当前会额外带：
+
+- `variantId`
+- `variantName`
+- `routeCode`
+
 ## 4. Event
 
 ### `GET /events/{eventPublicID}`
@@ -150,6 +156,8 @@
 - `event`
 - `release`
 - `resolvedRelease`
+- `play.assignmentMode`
+- `play.courseVariants`
 - `play.canLaunch`
 - `play.primaryAction`
 - `play.launchSource`
@@ -169,13 +177,21 @@
 请求体重点：
 
 - `releaseId`
+- `variantId`
 - `clientType`
 - `deviceKey`
 
+补充说明：
+
+- 如果当前 release 声明了 `play.courseVariants[]`
+- `launch` 会返回最终绑定的 `launch.variant`
+- 当前为兼容旧调用方，`assignmentMode=manual` 且未传 `variantId` 时，backend 会先回退到首个可选 variant
+
 返回重点：
 
 - `launch.source`
 - `launch.resolvedRelease`
+- `launch.variant`
 - `launch.config`
 - `launch.business.sessionId`
 - `launch.business.sessionToken`
@@ -228,6 +244,13 @@
 - `event`
 - `resolvedRelease`
 
+`session` 当前会额外带：
+
+- `assignmentMode`
+- `variantId`
+- `variantName`
+- `routeCode`
+
 ### `POST /sessions/{sessionPublicID}/start`
 
 鉴权：
@@ -312,6 +335,9 @@
 
 - `releaseId`
 - `configLabel`
+- `variantId`
+- `variantName`
+- `routeCode`
 
 ### `GET /me/results`
 

backend/docs/核心流程.md

@@ -1,6 +1,6 @@
 # 核心流程
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.1
+> 最后更新：2026-04-02 11:03:02
 
 
 ## 1. 总流程
@@ -100,6 +100,7 @@ APP 当前主链是手机号验证码：
 
 - 当前是否可启动
 - 当前会落到哪份 `release`
+- 当前是否存在多赛道 `variant` 编排
 - 是否有 ongoing session
 - 当前推荐动作是什么
 
@@ -112,12 +113,27 @@ APP 当前主链是手机号验证码：
 - `event`
 - `release`
 - `resolvedRelease`
+- `play.assignmentMode`
+- `play.courseVariants[]`
 - `play.canLaunch`
 - `play.primaryAction`
 - `play.launchSource`
 - `play.ongoingSession`
 - `play.recentSession`
 
+当前多赛道第一阶段约束：
+
+- `play.assignmentMode` 只先支持最小口径：
+  - `manual`
+  - `random`
+  - `server-assigned`
+- `play.courseVariants[]` 只先返回准备页必需字段：
+  - `id`
+  - `name`
+  - `description`
+  - `routeCode`
+  - `selectable`
+
 ## 6. Launch 流程
 
 ### 6.1 当前原则
@@ -135,6 +151,7 @@ APP 当前主链是手机号验证码：
 当前请求体支持：
 
 - `releaseId`
+- `variantId`
 - `clientType`
 - `deviceKey`
 
@@ -142,6 +159,7 @@ APP 当前主链是手机号验证码：
 
 - `launch.source`
 - `launch.resolvedRelease`
+- `launch.variant`
 - `launch.config`
 - `launch.business.sessionId`
 - `launch.business.sessionToken`
@@ -158,6 +176,14 @@ APP 当前主链是手机号验证码：
 - `launch.resolvedRelease.releaseId`
 - `launch.resolvedRelease.manifestUrl`
 - `launch.resolvedRelease.manifestChecksumSha256`
+- `launch.variant.id`
+- `launch.variant.assignmentMode`
+
+补充说明：
+
+- 如果活动声明了多赛道 variant，`launch` 会返回本局最终绑定的 `variant`
+- 前端可以发起选择，但最终绑定以后端 `launch` 返回为准
+- 故障恢复不重新分配 variant
 
 而不是再拿 `event` 自己去猜。
 
@@ -195,6 +221,11 @@ APP 当前主链是手机号验证码：
 - `cancelled` 和 `failed` 都不再作为 ongoing session 返回
 - “放弃恢复”当前正式收口为 `finish(cancelled)`
 - 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用
+- 第一阶段若活动声明了多赛道，session 会固化：
+  - `assignmentMode`
+  - `variantId`
+  - `variantName`
+  - `routeCode`
 
 ### 7.4 幂等要求
 
@@ -232,6 +263,7 @@ APP 当前主链是手机号验证码：
 
 - 一个 event 未来可能发布新版本
 - 历史结果必须追溯到当时真实跑过的那份 release
+- 如果一场活动存在多个 variant，结果与历史摘要也必须能追溯本局 `variantId`
 
 ## 9. 当前最应该坚持的流程约束