完善活动运营域与联调标准化

2026-04-03 13:11:41 +08:00
parent 0e28f70bad
commit 129ea935db
56 changed files with 11004 additions and 196 deletions
--- a/doc/gameplay/多线程联调协作方式.md
+++ b/doc/gameplay/多线程联调协作方式.md
@@ -1,6 +1,6 @@
 # 多线程联调协作方式
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.1
+> 最后更新：2026-04-03 11:15:00


 ## 目标
@@ -21,7 +21,7 @@

 - 一个代码仓库
 - 多条并行线程
- 两份根目录协作文档
+- 四份根目录协作文档
 - 一名全局维护者负责总览和收口

 对应关系：
@@ -32,38 +32,57 @@

 ---

-## 2. 两份协作文档的职责
+## 2. 当前协作文档的职责

-当前跨线程沟通只走两份文件：
+当前跨线程沟通主线改为 4 份文件：
+
+- [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)
+
+旧的：

 - [f2b.md](D:/dev/cmr-mini/f2b.md)
 - [b2f.md](D:/dev/cmr-mini/b2f.md)

-### 2.1 `f2b.md`
+默认不再作为主线协作文档继续扩写，只保留历史参考价值。

-由前端线程维护，用于记录：
+### 2.1 `t2b.md`

- 前端当前联调状态
- 前端已经按什么契约实现
- 需要后端确认什么
- 当前前端阻塞点是什么
+由总控线程维护，写给后端线程，用于记录：

-它不是后端说明文档，也不是讨论区。
+- 当前阶段后端应推进什么
+- 本刀范围是什么
+- 哪些对象和接口先做

-### 2.2 `b2f.md`
+### 2.2 `b2t.md`

-由后端线程维护，用于记录：
+由后端线程维护，写给总控线程，用于记录：

- 后端已经具备什么能力
- 前端应如何接入
- 哪些地方不允许前端自行假设
- 哪些接口和字段已经定版
+- 后端当前已完成什么
+- 后端希望确认什么
+- 下一步建议是什么

-它不是前端反馈文档，也不是需求池。
+### 2.3 `t2f.md`
+
+由总控线程维护，写给前端线程，用于记录：
+
+- 当前阶段前端应推进什么
+- 当前推荐接线顺序是什么
+- 哪些字段和页面优先接入
+
+### 2.4 `f2t.md`
+
+由前端线程维护，写给总控线程，用于记录：
+
+- 前端当前已完成什么
+- 前端在哪些地方受阻
+- 需要总控或后端确认什么

 ---

-## 2.3 当前固定模板
+## 2.5 当前固定模板

 为了避免两份协作文档再次变成长讨论稿，当前约定两边都采用统一结构：

@@ -105,8 +124,10 @@

 - [readme-develop.md](D:/dev/cmr-mini/readme-develop.md)
 - [文档索引.md](D:/dev/cmr-mini/doc/文档索引.md)
- [f2b.md](D:/dev/cmr-mini/f2b.md)
- [b2f.md](D:/dev/cmr-mini/b2f.md)
+- [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)

 以及当前代码事实：

@@ -118,8 +139,8 @@

 总控线程不应该：

- 抢写前端线程的 `f2b.md`
- 抢写后端线程的 `b2f.md`
+- 抢写前端线程的 [f2t.md](D:/dev/cmr-mini/f2t.md)
+- 抢写后端线程的 [b2t.md](D:/dev/cmr-mini/b2t.md)
 - 把临时讨论直接当作正式契约
 - 在两边尚未确认时擅自“替双方拍板”

@@ -133,7 +154,7 @@

 总控线程需要持续做两件事：

- 读取并理解 [f2b.md](D:/dev/cmr-mini/f2b.md) 和 [b2f.md](D:/dev/cmr-mini/b2f.md) 的最新事实
+- 读取并理解 [b2t.md](D:/dev/cmr-mini/b2t.md) 和 [f2t.md](D:/dev/cmr-mini/f2t.md) 的最新事实
 - 把已经收敛的跨线程结论回写到 `doc/` 正式文档

 也就是说，总控线程不是“第三份协作文档”，而是：
@@ -152,8 +173,9 @@

 ```text
 前端/后端各自推进
-> 遇到跨边界事项时写入 f2b / b2f
-> 总控线程读取两份协作文档
+-> 总控通过 t2b / t2f 下发阶段性要求
+-> 前后端通过 b2t / f2t 回写事实与阻塞
+-> 总控线程读取四份协作文档
 -> 判断是否需要：
   - 调整主线优先级
   - 更新正式方案文档
@@ -163,7 +185,7 @@

 也就是说：

- `f2b / b2f` 是协作事实层
+- `t2b / b2t / t2f / f2t` 是协作事实层
 - `doc/` 是正式知识层
 - 代码是最终实现层

@@ -177,8 +199,10 @@

 位于仓库根目录：

- [f2b.md](D:/dev/cmr-mini/f2b.md)
- [b2f.md](D:/dev/cmr-mini/b2f.md)
+- [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)

 特点：

@@ -265,7 +289,7 @@
 - 模拟器接入
 - 交互和体验

-并把需要后端确认的事项写入 [f2b.md](D:/dev/cmr-mini/f2b.md)。
+并把当前事实、阻塞和待确认事项回写到 [f2t.md](D:/dev/cmr-mini/f2t.md)。

 ### 7.2 后端线程

@@ -276,7 +300,7 @@
 - release / manifest / config 发布链
 - workbench / dev tools

-并把前端需要知道的契约写入 [b2f.md](D:/dev/cmr-mini/b2f.md)。
+并把当前事实、完成项和待确认事项回写到 [b2t.md](D:/dev/cmr-mini/b2t.md)。

 ### 7.3 总控线程

@@ -294,7 +318,7 @@

 当前项目的协作方式正式定为：

-> 前后端线程分别维护自己的协作文档， 总控线程负责读取两份协作文档并维护全局主线、正式文档和阶段结论。
+> 总控线程通过 [t2b.md](D:/dev/cmr-mini/t2b.md) / [t2f.md](D:/dev/cmr-mini/t2f.md) 下发阶段要求，前后端线程通过 [b2t.md](D:/dev/cmr-mini/b2t.md) / [f2t.md](D:/dev/cmr-mini/f2t.md) 回写事实，总控线程再维护全局主线、正式文档和阶段结论。

 这样做的目标不是增加文书工作，而是：

@@ -308,9 +332,13 @@

 截至当前阶段，这套方式已经进入实际执行状态：

- 前端线程维护 [f2b.md](D:/dev/cmr-mini/f2b.md)
- 后端线程维护 [b2f.md](D:/dev/cmr-mini/b2f.md)
- 两份文档都已经按统一结构整理
+- 总控线程维护：
+  - [t2b.md](D:/dev/cmr-mini/t2b.md)
+  - [t2f.md](D:/dev/cmr-mini/t2f.md)
+- 执行线程回写：
+  - [b2t.md](D:/dev/cmr-mini/b2t.md)
+  - [f2t.md](D:/dev/cmr-mini/f2t.md)
+- 旧的 [f2b.md](D:/dev/cmr-mini/f2b.md) / [b2f.md](D:/dev/cmr-mini/b2f.md) 仅保留历史参考
 - 总控线程负责维护 [文档索引.md](D:/dev/cmr-mini/doc/文档索引.md) 和 `doc/` 下的正式文档

 后续如果线程数量增加，或者联调链变复杂，优先仍然是：
--- a/doc/gameplay/活动运营域摘要第一刀联调回归清单.md
+++ b/doc/gameplay/活动运营域摘要第一刀联调回归清单.md
@@ -0,0 +1,98 @@
+# 活动运营域摘要第一刀联调回归清单
+> 文档版本：v1.0
+> 最后更新：2026-04-03 19:38:00
+
+## 目标
+
+本清单只用于回归“活动运营域摘要第一刀”是否稳定，不扩新页面链，不验证复杂运营样式。
+
+当前回归范围：
+
+- 活动详情页
+- 活动准备页
+- `launch.presentation / launch.contentBundle` 会话快照
+- 与 runtime 主链的相互不干扰
+
+## 回归项
+
+### 1. 活动详情页摘要
+
+- 页面：`/pages/event/event`
+- 检查项：
+  - 是否展示 `展示版本`
+  - 是否展示 `内容包版本`
+  - 当字段缺失时是否回退为 `当前未声明...`
+- 通过标准：
+  - 页面可正常加载
+  - 摘要存在
+  - 不影响原有 `release / 主动作 / 赛道模式`
+
+### 2. 准备页摘要
+
+- 页面：`/pages/event-prepare/event-prepare`
+- 检查项：
+  - 是否展示 `活动运营摘要`
+  - 是否仍保留：
+    - 多赛道选择
+    - runtime 预览摘要
+    - 设备准备区
+- 通过标准：
+  - 新摘要可见
+  - 页面结构未被打乱
+  - 进入地图主链不受影响
+
+### 3. launch 快照接线
+
+- 页面链：`event -> event-prepare -> map`
+- 检查项：
+  - `launch.presentation`
+  - `launch.contentBundle`
+  - 是否已进入 `GameLaunchEnvelope`
+- 通过标准：
+  - launch 后不报错
+  - 不影响地图加载
+  - 会话快照链不断
+
+### 4. 与 runtime 主链隔离
+
+- 页面链：`event-prepare -> map -> result`
+- 检查项：
+  - 新增活动运营摘要后，以下能力是否仍正常：
+    - `launch.runtime`
+    - 赛道摘要
+    - 恢复链
+    - 结果页跳转
+- 通过标准：
+  - 没有因活动运营摘要接线导致 runtime 摘要缺失或错位
+
+### 5. 缺字段降级
+
+- 检查项：
+  - 若 backend 某活动未返回：
+    - `currentPresentation`
+    - `currentContentBundle`
+    - `launch.presentation`
+    - `launch.contentBundle`
+  - 前端是否仍能正常展示和进入地图
+- 通过标准：
+  - 页面不崩
+  - 只显示 `当前未声明...`
+  - 主链继续可用
+
+## 建议记录字段
+
+如联调发现问题，建议一次性记录：
+
+- `eventPublicID`
+- 活动页展示的 `展示版本 / 内容包版本`
+- 准备页展示的 `展示版本 / 内容包版本`
+- `launch` 是否成功
+- 地图是否正常进入
+- 是否影响 `runtime` 摘要或多赛道链
+- 实际报错文案 / 控制台错误
+
+## 一句话结论
+
+本轮只验证一句话：
+
+**活动运营域摘要第一刀是否已经接稳，且没有影响 runtime 稳定主链。**
--- a/doc/gameplay/第五刀联调回归清单.md
+++ b/doc/gameplay/第五刀联调回归清单.md
@@ -0,0 +1,204 @@
+# 第五刀联调回归清单
+> 文档版本：v1.0
+> 最后更新：2026-04-03 14:50:00
+
+## 目标
+
+本清单用于回归验证第五刀“前端接线阶段”的实际效果，重点确认：
+
+- `launch.runtime` 是否已稳定进入前端运行链
+- 多赛道与 runtime 摘要是否能同时正确回流
+- 恢复链、结果链、首页摘要链是否保持一致
+
+本清单优先验证“可见”和“一致”，不要求当前阶段完成复杂运营样式。
+
+## 当前范围
+
+本轮重点回归以下页面：
+
+- 活动页
+- 准备页
+- 地图页
+- 单局结果页
+- 历史结果列表页
+- 首页 `ongoing / recent`
+
+## 建议测试数据
+
+优先使用后端当前已提供的多赛道手动 demo：
+
+- `eventPublicID = evt_demo_variant_manual_001`
+- `variant_a`
+  - `name = A 线`
+  - `routeCode = route-variant-a`
+- `variant_b`
+  - `name = B 线`
+  - `routeCode = route-variant-b`
+
+普通单赛道活动可继续使用：
+
+- `eventPublicID = evt_demo_001`
+
+## 回归项
+
+### 1. 准备页预览态摘要
+
+验证目标：
+
+- 准备页能显示“运行对象摘要”
+- 当前阶段允许是预览态，不要求已经拿到完整 `launch.runtime`
+
+检查点：
+
+- `地点` 当前允许显示 `待 launch.runtime 确认`
+- `地图` 当前允许显示 `待 launch.runtime 确认`
+- `赛道`
+  - `manual` 模式下，应跟随当前选择变化
+- `RouteCode`
+  - `manual` 模式下，应跟随当前选择变化
+
+### 2. Launch Runtime 映射
+
+验证目标：
+
+- 进入地图后，前端已正式消费后端 `launch.runtime`
+
+检查点：
+
+- 地图页“当前游戏”摘要中可看到：
+  - `运行绑定`
+  - `地点`
+  - `地图`
+  - `赛道集`
+  - `赛道版本`
+  - `RouteCode`
+  - `瓦片版本`
+
+### 3. 多赛道手动选择
+
+验证目标：
+
+- `manual` 模式下，准备页选择的赛道和最终 `launch.variant / launch.runtime` 一致
+
+建议步骤：
+
+1. 打开 `evt_demo_variant_manual_001`
+2. 在准备页选择 `A 线`
+3. 进入地图，记录地图页 runtime 摘要
+4. 结束一局，记录结果页摘要
+5. 再重复一次，切换到 `B 线`
+
+检查点：
+
+- 地图页 `赛道版本`
+- 单局结果页 `赛道版本`
+- 历史结果列表页该条记录的 `赛道`
+- 首页 `recent`
+
+都应能区分 `A 线 / B 线`
+
+### 4. 单局结果页 Runtime
+
+验证目标：
+
+- 结果页优先消费 `result.session.runtime`
+- 如果后端某次未带该字段，前端能回退到 launch 快照，不出现空白
+
+检查点：
+
+- 结果页中可见：
+  - `运行绑定`
+  - `地点`
+  - `地图`
+  - `赛道集`
+  - `赛道版本`
+  - `RouteCode`
+  - `瓦片版本`
+
+### 5. 历史结果列表页 Runtime
+
+验证目标：
+
+- 历史结果列表页保持摘要态，不改主结构，但能看到 runtime 对象
+
+检查点：
+
+- 每条结果卡片可显示：
+  - `地点`
+  - `地图`
+  - `赛道`
+
+### 6. 首页 Ongoing / Recent Runtime
+
+验证目标：
+
+- 首页 `ongoing / recent` 已开始展示 runtime 摘要
+
+检查点：
+
+- `进行中运行对象`
+- `最近一局运行对象`
+
+内容至少包含：
+
+- `地点`
+- `地图`
+- `赛道`
+
+### 7. 恢复链 Runtime 一致性
+
+验证目标：
+
+- 非正常退出后恢复，赛道和 runtime 不发生漂移
+
+建议步骤：
+
+1. 使用多赛道活动选择 `B 线`
+2. 进入地图并开始一局
+3. 非正常退出
+4. 重新进入程序并选择“继续恢复”
+
+检查点：
+
+- 恢复后的地图页 runtime 摘要仍然是原来的 `place / map / variant`
+- 赛道版本不变
+
+### 8. 放弃恢复语义
+
+验证目标：
+
+- 放弃恢复不会上错局
+- 放弃后不会残留旧 runtime
+
+建议步骤：
+
+1. 打开一局并异常退出
+2. 再进程序，选择“放弃”
+3. 回首页
+
+检查点：
+
+- 不再提示旧局恢复
+- 首页 `ongoing` 应消失
+- 再开新局时 runtime 摘要以新局为准
+
+## 问题记录建议
+
+如果发现问题，尽量一次性记录：
+
+- `eventPublicID`
+- 选择的 `variantId / routeCode`
+- `launch.variant`
+- `launch.runtime`
+- 地图页 runtime 摘要
+- 结果页 runtime 摘要
+- 首页 / 历史页摘要
+- 是否属于恢复场景
+
+## 当前阶段结论标准
+
+本轮完成标准不是“页面全部重做”，而是：
+
+- `launch.runtime` 已进入用户侧主页面链
+- 多赛道与 runtime 摘要可同时回流
+- 恢复链、结果链、首页摘要链不互相打架