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

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` 也已统一使用活动卡片最小摘要字段