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

2026-04-03 13:11:41 +08:00
parent 0e28f70bad
commit 129ea935db
56 changed files with 11004 additions and 196 deletions
--- a/doc/backend/后台生产闭环架构草案.md
+++ b/doc/backend/后台生产闭环架构草案.md
--- a/doc/backend/生产发布与数据库上线方案.md
+++ b/doc/backend/生产发布与数据库上线方案.md
@@ -0,0 +1,208 @@
+# 生产发布与数据库上线方案
+> 文档版本：v1.0
+> 最后更新：2026-04-03 16:20:00
+
+## 1. 目标
+
+本文档用于约定：
+
+- 开发测试数据库与正式生产数据库的关系
+- 正式上线时数据库如何初始化与升级
+- 后端服务如何与数据库发布配合
+- 每次上线前后的最小检查项
+
+当前原则只有一条：
+
+- **测试库继续做测试，生产库独立建库，靠 migration 升级，不靠手工拷贝。**
+
+---
+
+## 2. 环境划分
+
+建议至少分 2 套数据库环境：
+
+- `dev`：开发 / 联调 / demo / workbench
+- `prod`：正式生产
+
+如果条件允许，推荐分 3 套：
+
+- `dev`
+- `staging`
+- `prod`
+
+其中：
+
+- `dev` 用于日常开发和联调
+- `staging` 用于上线前预演
+- `prod` 只承载正式业务数据
+
+---
+
+## 3. 当前数据库结构来源
+
+当前仓库已经采用 migration 驱动结构演进，目录位于：
+
+- [D:\dev\cmr-mini\backend\migrations](D:/dev/cmr-mini/backend/migrations)
+
+当前已存在的迁移文件包括：
+
+- `0001_init.sql`
+- `0002_launch.sql`
+- `0003_home.sql`
+- `0004_results.sql`
+- `0005_config_pipeline.sql`
+- `0006_resource_objects.sql`
+- `0007_variant_minimal.sql`
+- `0008_production_skeleton.sql`
+- `0009_event_ops_phase2.sql`
+
+因此正式上线时，数据库结构应以这些 migration 为准，而不是以当前测试库的现状为准。
+
+---
+
+## 4. 第一次生产上线
+
+第一次正式上线建议按以下顺序执行：
+
+1. 新建生产 PostgreSQL 数据库
+2. 配置生产环境变量
+3. 按顺序执行全部 migration
+4. 导入必要的生产基础数据
+5. 部署后端服务
+6. 执行最小 smoke test
+7. 再切前端 / 小程序到生产后端
+
+### 4.1 生产环境变量
+
+至少应与开发环境分离以下配置：
+
+- `DATABASE_URL`
+- JWT 相关密钥
+- 微信小程序相关配置
+- OSS / 资源发布相关配置
+- 其它第三方服务配置
+
+开发环境中的 `.env` 不能直接视为生产配置。
+
+参考文件：
+
+- [D:\dev\cmr-mini\backend\.env.example](D:/dev/cmr-mini/backend/.env.example)
+
+### 4.2 生产初始数据
+
+第一次上线时，建议只导入最小必要数据，例如：
+
+- 租户
+- 默认渠道
+- 最小活动与地图运行数据
+
+不建议把开发联调用的 demo 数据直接原样导入生产。
+
+---
+
+## 5. 后续版本上线
+
+每次后续正式上线建议固定为以下顺序：
+
+1. 备份生产数据库
+2. 部署前确认本次新增 migration
+3. 执行新增 migration
+4. 发布后端服务
+5. 验证关键接口
+6. 再切客户端或前端流量
+
+关键接口最少应验证：
+
+- 登录
+- 活动列表
+- 活动详情
+- `launch`
+- `session start / finish`
+- `result / history`
+
+---
+
+## 6. 上线原则
+
+### 6.1 不直接复用测试库
+
+禁止做法：
+
+- 直接把开发测试数据库改名当生产库
+- 通过手工拷表来“上线”
+- 在生产库中临时手改结构但不补 migration
+
+### 6.2 结构变更只走 migration
+
+所有数据库结构变化都应：
+
+- 新增 migration 文件
+- 进入版本管理
+- 随代码一起发布
+
+不应依赖口头约定或临时 SQL。
+
+### 6.3 生产数据与测试数据分离
+
+开发 demo 数据、联调活动、手工实验数据，应停留在：
+
+- `dev`
+- 或 `staging`
+
+不要直接进入 `prod`。
+
+### 6.4 代码版本与数据库版本对应
+
+每次上线都应能回答两件事：
+
+- 当前代码对应到哪一个 migration 版本
+- 当前生产库已经执行到哪一个 migration 版本
+
+---
+
+## 7. 推荐的发布节奏
+
+建议发布节奏为：
+
+### 阶段 1：数据库先行
+
+- 新 migration 先在 `dev` 验证
+- 再在 `staging` 演练
+- 最后进入 `prod`
+
+### 阶段 2：服务发布
+
+- 后端服务发布到对应环境
+- 验证启动、连接数据库、关键接口可用
+
+### 阶段 3：客户端切换
+
+- 小程序 / App / H5 再切到新的后端能力
+- 避免客户端先切到一个数据库未升级的后端版本
+
+---
+
+## 8. 当前项目建议的最小上线清单
+
+对当前仓库，正式上线前建议至少确认：
+
+- [D:\dev\cmr-mini\backend\migrations](D:/dev/cmr-mini/backend/migrations) 已完整纳入发布
+- [D:\dev\cmr-mini\doc\backend\后台生产闭环架构草案.md](D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md) 中当前主线对象已落库
+- `DATABASE_URL` 已切到生产库
+- JWT / 微信 / OSS 配置已替换为生产值
+- workbench / 管理接口在生产环境默认不对外暴露或受限
+- demo 事件、demo variant 不进入生产正式运营入口
+
+---
+
+## 9. 一句话结论
+
+当前项目的正式上线方式应固定为：
+
+- **新建独立生产库**
+- **通过 migration 初始化和升级**
+- **通过生产环境变量部署后端**
+- **通过最小 smoke test 验证**
+- **最后再切客户端入口**
+
+不要把开发测试数据库直接视为生产数据库。
--- 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 摘要可同时回流
+- 恢复链、结果链、首页摘要链不互相打架
--- a/doc/文档索引.md
+++ b/doc/文档索引.md
@@ -1,6 +1,6 @@
 # 文档索引
-> 文档版本：v1.0
-> 最后更新：2026-04-02 18:10:04
+> 文档版本：v1.3
+> 最后更新：2026-04-03 19:38:00

 维护约定：

@@ -46,6 +46,8 @@
 - [多线程联调协作方式](/D:/dev/cmr-mini/doc/gameplay/多线程联调协作方式.md)
 - [APP全局产品架构草案](/D:/dev/cmr-mini/doc/gameplay/APP全局产品架构草案.md)
 - [故障恢复机制](/D:/dev/cmr-mini/doc/gameplay/故障恢复机制.md)
+- [活动运营域摘要第一刀联调回归清单](/D:/dev/cmr-mini/doc/gameplay/活动运营域摘要第一刀联调回归清单.md)
+- [第五刀联调回归清单](/D:/dev/cmr-mini/doc/gameplay/第五刀联调回归清单.md)
 - [运行时编译层总表](/D:/dev/cmr-mini/doc/gameplay/运行时编译层总表.md)
 - [玩法设计文档模板](/D:/dev/cmr-mini/doc/gameplay/玩法设计文档模板.md)

@@ -75,6 +77,12 @@

 - [网关文档索引](/D:/dev/cmr-mini/doc/gateway/网关文档索引.md)

+## 后端
+
+- [业务后端数据库初版方案](/D:/dev/cmr-mini/doc/backend/业务后端数据库初版方案.md)
+- [后台生产闭环架构草案](/D:/dev/cmr-mini/doc/backend/后台生产闭环架构草案.md)
+- [生产发布与数据库上线方案](/D:/dev/cmr-mini/doc/backend/生产发布与数据库上线方案.md)
+
 ## 备注与归档

 - 长期保留的少量工作便签见 [notes](/D:/dev/cmr-mini/doc/notes)。