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

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
 
 当前第一版全部依赖：