推进活动列表第一刀与联调回归

2026-04-03 19:33:16 +08:00
parent b09c21c814
commit 527b4c78a9
34 changed files with 3094 additions and 224 deletions
--- a/backend/docs/开发说明.md
+++ b/backend/docs/开发说明.md
@@ -1,6 +1,6 @@
 # 开发说明
-> 文档版本：v1.20
-> 最后更新：2026-04-03 16:16:38
+> 文档版本：v1.25
+> 最后更新：2026-04-03 18:56:46


 ## 1. 环境变量
@@ -45,6 +45,13 @@ cd D:\dev\cmr-mini\backend
  - `Bootstrap Demo`
  - `Use Classic Demo / Use Score-O Demo / Use Manual Variant Demo`
  - `整条链一键验收`
+- 当前玩法切换除了切 `event / release / source / build`，还会自动切换：
+  - `presentation schema`
+  - `content manifest`
+  - `asset manifest`
+- 这些 demo 资源现在由 backend 提供，避免继续在 workbench 里保留 `example.com` 占位地址：
+  - `GET /dev/demo-assets/presentations/{demoKey}`
+  - `GET /dev/demo-assets/content-manifests/{demoKey}`
 - 如果 frontend 需要把页面侧调试日志直接打到 backend，优先使用：
  - `POST /dev/client-logs`
  - 然后在 workbench 的 `前端调试日志` 面板里查看
@@ -67,6 +74,54 @@ cd D:\dev\cmr-mini\backend
  - backend 当前只在内存里保留最近 200 条
  - 适合前端把关键事实直接打进来，避免只靠截图和口头描述
  - 不替代正式生产日志体系
+- `Bootstrap Demo` 准备出的联调文案也已换成中文样例：
+  - `领秀城公园顺序赛`
+  - `领秀城公园积分赛`
+  - `领秀城公园多赛道挑战`
+
+## 4. 活动卡片列表最小摘要
+
+当前 backend 已为以下入口统一补齐活动卡片最小摘要字段：
+
+- `/cards`
+- `/home`
+- `/me/entry-home`
+
+当前字段集：
+
+- `title`
+- `subtitle`
+- `summary`
+- `status`
+- `statusCode`
+- `timeWindow`
+- `ctaText`
+- `coverUrl`
+- `isDefaultExperience`
+- `eventType`
+- `currentPresentation`
+- `currentContentBundle`
+
+当前派生规则：
+
+- `summary`
+  - 无值时回退为：`当前暂无活动摘要`
+- `status`
+  - `running` -> `进行中`
+  - `upcoming` -> `即将开始`
+  - `ended` -> `已结束`
+  - 其余 -> `状态待确认`
+- `timeWindow`
+  - 由 `cards.starts_at / ends_at` 派生
+  - 缺失时回退为：`时间待公布`
+- `ctaText`
+  - 默认体验活动：`进入体验`
+  - 进行中：`进入活动`
+  - 已结束：`查看回顾`
+  - 其余：`查看详情`
+- `currentPresentation / currentContentBundle`
+  - 当前继续表示已发布 release 实际绑定摘要
+  - 不是 event 草稿默认值

 默认会设置：

@@ -100,13 +155,26 @@ cd D:\dev\cmr-mini\backend

 当前推荐顺序：

-1. `Bootstrap Demo`
+1. `Bootstrap Demo（只准备数据）`
 2. 选择一种玩法入口：
   - `Use Classic Demo`
   - `Use Score-O Demo`
   - `Use Manual Variant Demo`
-3. `一键补齐 Runtime 并发布`
-4. `一键标准回归`
+3. 如果只是想看发布过程，点 `Bootstrap + 发布当前玩法`
+4. 如果想只测发布链，点 `一键补齐 Runtime 并发布`
+5. 如果想直接验整条链，点 `一键标准回归`
+
+当前这几个按钮的职责已经拆开：
+
+- `Bootstrap Demo（只准备数据）`
+  - 只负责准备 demo event / source / build / release / runtime 等测试数据
+  - 不会基于当前玩法再额外重新发布一版
+- `Bootstrap + 发布当前玩法`
+  - 会先执行一遍 `Bootstrap Demo`
+  - 然后对当前选中的玩法执行“发布活动配置（自动补 Runtime）”
+- `一键补齐 Runtime 并发布`
+  - 不再隐式 bootstrap
+  - 只基于当前已选玩法和当前表单上下文执行发布链

 当前这条一键链会自动完成：

@@ -220,6 +288,48 @@ dev 环境下，frontend 可直接把关键调试事实发到 backend：

 ## 3. 当前开发约定

+### 3.0 玩家进入规则
+
+当前要明确一条玩家链路规则：
+
+- 玩家进入游戏，必须基于“已发布 release”
+- 不能基于：
+  - event 草稿默认绑定
+  - 未发布 presentation
+  - 未发布 content bundle
+  - 未发布 runtime
+
+当前接口中的：
+
+- `currentPresentation`
+- `currentContentBundle`
+
+在玩家链路里表示的是：
+
+- 当前已发布 release 上实际绑定的展示版本摘要
+- 当前已发布 release 上实际绑定的内容包摘要
+
+不是：
+
+- event 草稿默认值摘要
+
+所以如果当前 release 还没绑定这些对象，玩家页看到空值是正常行为。前端页面应优先：
+
+- 用 `play.canLaunch` 判定是否允许进入
+- 把空值解释成“当前未发布或当前发布未绑定”
+
+当前 `canLaunch` 已按正式进入规则收紧：
+
+- 只有当当前 event 满足以下条件时，`play.canLaunch = true`
+  - event `status = active`
+  - 已存在当前发布 release
+  - 当前发布 release 有 `manifest`
+  - 当前发布 release 已绑定 `runtime`
+  - 当前发布 release 已绑定 `presentation`
+  - 当前发布 release 已绑定 `content bundle`
+
+当前 `POST /events/{eventPublicID}/launch` 也已与 `canLaunch` 保持同一套前置条件。
+
 ### 3.1 开发阶段先不用 Redis

 当前第一版全部依赖：
--- a/backend/docs/接口清单.md
+++ b/backend/docs/接口清单.md
@@ -1,6 +1,6 @@
 # API 清单
-> 文档版本：v1.9
-> 最后更新：2026-04-03 16:16:38
+> 文档版本：v1.12
+> 最后更新：2026-04-03 22:34:08


 本文档只记录当前 backend 已实现接口，不写未来规划接口。
@@ -95,12 +95,23 @@
 用途：

 - 返回入口首页卡片
+- 当前卡片摘要字段已统一补齐：
+  - `summary`
+  - `status`
+  - `statusCode`
+  - `timeWindow`
+  - `ctaText`
+  - `isDefaultExperience`
+  - `eventType`
+  - `currentPresentation`
+  - `currentContentBundle`

 ### `GET /cards`

 用途：

 - 只返回卡片列表
+- 当前与 `/home` 使用同一套卡片摘要语义

 ### `GET /me/entry-home`

@@ -111,6 +122,7 @@
 用途：

 - 首页聚合接口
+- 当前 `cards` 也已统一使用活动卡片最小摘要字段

 返回重点：

@@ -179,6 +191,15 @@
 - `play.ongoingSession`
 - `play.recentSession`

+当前 `play.canLaunch=true` 的最小前置条件为：
+
+- event `status = active`
+- 当前已发布 release 存在
+- 当前已发布 release 有 `manifest`
+- 当前已发布 release 已绑定 `runtime`
+- 当前已发布 release 已绑定 `presentation`
+- 当前已发布 release 已绑定 `content bundle`
+
 当前摘要字段最少包括：

 - `currentPresentation.presentationId`
@@ -210,6 +231,12 @@
 - 如果当前 release 声明了 `play.courseVariants[]`
 - `launch` 会返回最终绑定的 `launch.variant`
 - 当前为兼容旧调用方，`assignmentMode=manual` 且未传 `variantId` 时，backend 会先回退到首个可选 variant
+- 当前 `launch` 与 `play.canLaunch` 使用同一套前置条件
+- 若当前发布 release 缺少：
+  - `runtime`
+  - `presentation`
+  - `content bundle`
+  之一，`launch` 会直接返回 `409`

 返回重点：

@@ -530,6 +557,38 @@
  - `playfield.kind`
  - `game.mode`

+### `GET /dev/demo-assets/presentations/{demoKey}`
+
+环境：
+
+- 仅 non-production
+
+用途：
+
+- 返回联调用的示例展示定义 schema
+- 给 workbench 的玩法切换自动填充真实 `presentation schema` 资源地址
+
+路径参数：
+
+- `demoKey`
+  - 当前支持：`classic`、`score-o`、`manual-variant`
+
+### `GET /dev/demo-assets/content-manifests/{demoKey}`
+
+环境：
+
+- 仅 non-production
+
+用途：
+
+- 返回联调用的示例内容 manifest
+- 给 workbench 的玩法切换自动填充真实 `content manifest` 资源地址
+
+路径参数：
+
+- `demoKey`
+  - 当前支持：`classic`、`score-o`、`manual-variant`
+
 补充说明：

 - 只用于 workbench 联调排查
@@ -1357,3 +1416,36 @@
 - 查看单个运行绑定详情


+### `GET /home`
+
+用途：
+
+- 返回入口首页摘要
+- 当前卡片摘要字段已统一补齐：
+  - `summary`
+  - `status`
+  - `statusCode`
+  - `timeWindow`
+  - `ctaText`
+  - `isDefaultExperience`
+  - `eventType`
+  - `currentPresentation`
+  - `currentContentBundle`
+
+### `GET /cards`
+
+用途：
+
+- 按入口返回活动卡片列表
+- 当前与 `/home` 使用同一套卡片摘要语义
+
+### `GET /me/entry-home`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 返回“我的首页”聚合
+- 当前 `cards` 也已统一使用活动卡片最小摘要字段
--- a/backend/docs/数据模型.md
+++ b/backend/docs/数据模型.md
@@ -1,8 +1,8 @@
 # 数据模型
-> 文档版本：v1.3
-> 最后更新：2026-04-03 12:36:15
+> 文档版本：v1.4
+> 最后更新：2026-04-03 22:34:08

-当前 migration 共 10 版。
+当前 migration 共 11 版。

 ## 1. 迁移清单

@@ -16,6 +16,7 @@
 - [0008_production_skeleton.sql](D:/dev/cmr-mini/backend/migrations/0008_production_skeleton.sql)
 - [0009_event_ops_phase2.sql](D:/dev/cmr-mini/backend/migrations/0009_event_ops_phase2.sql)
 - [0010_event_default_bindings.sql](D:/dev/cmr-mini/backend/migrations/0010_event_default_bindings.sql)
+- [0011_card_summary.sql](D:/dev/cmr-mini/backend/migrations/0011_card_summary.sql)

 ## 2. 表分组

@@ -78,6 +79,16 @@
 - 支撑首页卡片
 - 运营入口聚合
 - tenant/channel 维度展示控制
+- 默认体验活动标记
+
+当前补充字段：
+
+- `cards.is_default_experience`
+
+当前说明：
+
+- 活动卡片列表第一刀先通过卡片显式字段承接“默认体验活动 / 普通活动”区分
+- `timeWindow / ctaText / status` 当前先由 backend 摘要层派生，不再额外新增对象层级

 ### 2.5 运行态

--- a/backend/docs/核心流程.md
+++ b/backend/docs/核心流程.md
@@ -1,6 +1,6 @@
 # 核心流程
-> 文档版本：v1.2
-> 最后更新：2026-04-03 11:22:50
+> 文档版本：v1.3
+> 最后更新：2026-04-03 18:16:19


 ## 1. 总流程
@@ -104,6 +104,17 @@ APP 当前主链是手机号验证码：
 - 是否有 ongoing session
 - 当前推荐动作是什么

+补充规则：
+
+- `play.canLaunch` 不是“有 event 就能进”
+- 它当前表示“当前发布 release 已完整可启动”
+- 最小要求为：
+  - 已发布 release 存在
+  - manifest 存在
+  - runtime 已绑定
+  - presentation 已绑定
+  - content bundle 已绑定
+
 当前聚合接口：

 - `GET /events/{eventPublicID}/play`