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

2026-04-03 13:11:41 +08:00
parent 0e28f70bad
commit 129ea935db
56 changed files with 11004 additions and 196 deletions
--- a/backend/docs/接口清单.md
+++ b/backend/docs/接口清单.md
@@ -1,6 +1,6 @@
 # API 清单
-> 文档版本：v1.1
-> 最后更新：2026-04-02 11:05:32
+> 文档版本：v1.8
+> 最后更新：2026-04-03 12:36:15


 本文档只记录当前 backend 已实现接口，不写未来规划接口。
@@ -140,6 +140,18 @@
 - `event`
 - `release`
 - `resolvedRelease`
+- `runtime`
+- `currentPresentation`
+- `currentContentBundle`
+
+当前摘要字段最少包括：
+
+- `currentPresentation.presentationId`
+- `currentPresentation.templateKey`
+- `currentPresentation.version`
+- `currentContentBundle.contentBundleId`
+- `currentContentBundle.bundleType`
+- `currentContentBundle.version`

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

@@ -156,6 +168,9 @@
 - `event`
 - `release`
 - `resolvedRelease`
+- `runtime`
+- `currentPresentation`
+- `currentContentBundle`
 - `play.assignmentMode`
 - `play.courseVariants`
 - `play.canLaunch`
@@ -164,6 +179,15 @@
 - `play.ongoingSession`
 - `play.recentSession`

+当前摘要字段最少包括：
+
+- `currentPresentation.presentationId`
+- `currentPresentation.templateKey`
+- `currentPresentation.version`
+- `currentContentBundle.contentBundleId`
+- `currentContentBundle.bundleType`
+- `currentContentBundle.version`
+
 ### `POST /events/{eventPublicID}/launch`

 鉴权：
@@ -192,10 +216,33 @@
 - `launch.source`
 - `launch.resolvedRelease`
 - `launch.variant`
+- `launch.runtime`
+- `launch.presentation`
+- `launch.contentBundle`
 - `launch.config`
 - `launch.business.sessionId`
 - `launch.business.sessionToken`

+当前活动运营摘要最少包括：
+
+- `launch.presentation.presentationId`
+- `launch.presentation.templateKey`
+- `launch.presentation.version`
+- `launch.contentBundle.contentBundleId`
+- `launch.contentBundle.bundleType`
+- `launch.contentBundle.version`
+
+`launch.runtime` 当前为兼容新增字段，最少会带：
+
+- `runtimeBindingId`
+- `placeId`
+- `mapId`
+- `tileReleaseId`
+- `courseSetId`
+- `courseVariantId`
+
+如当前 release 尚未挂接 runtime binding，则该字段为空。
+
 ### `GET /events/{eventPublicID}/config-sources`

 鉴权：
@@ -466,12 +513,16 @@
 请求体重点：

 - `buildId`
+- `runtimeBindingId` 可选
+- `presentationId` 可选
+- `contentBundleId` 可选

 返回重点：

 - `release.releaseId`
 - `release.manifestUrl`
 - `release.configLabel`
+- `runtime.runtimeBindingId` 可选

 ## 9. Admin 资源对象

@@ -738,6 +789,145 @@
 - `overrides`
 - `notes`

+### `GET /admin/events/{eventPublicID}/presentations`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看某个 event 下的展示定义列表
+
+### `POST /admin/events/{eventPublicID}/presentations`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 为 event 创建一条最小 presentation 定义
+
+请求体重点：
+
+- `code`
+- `name`
+- `presentationType`
+- `schema`
+
+### `POST /admin/events/{eventPublicID}/presentations/import`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 通过统一导入入口创建展示定义
+- 第一阶段只记录：
+  - `templateKey`
+  - `sourceType`
+  - `schemaUrl`
+  - `version`
+  - `title`
+
+核心参数：
+
+- `title`
+- `templateKey`
+- `sourceType`
+- `schemaUrl`
+- `version`
+
+### `GET /admin/presentations/{presentationPublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看单条 presentation 明细
+
+### `GET /admin/events/{eventPublicID}/content-bundles`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看某个 event 下的内容包列表
+
+### `POST /admin/events/{eventPublicID}/content-bundles`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 为 event 创建一条最小 content bundle
+
+请求体重点：
+
+- `code`
+- `name`
+- `entryUrl`
+- `assetRootUrl`
+- `metadata`
+
+### `POST /admin/events/{eventPublicID}/content-bundles/import`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 通过统一导入入口为 event 创建内容包
+- 先记录 `bundleType / sourceType / manifestUrl / version / assetManifest`
+
+请求体重点：
+
+- `title`
+- `bundleType`
+- `sourceType`
+- `manifestUrl`
+- `version`
+- `assetManifest`
+
+### `GET /admin/content-bundles/{contentBundlePublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看单条 content bundle 明细
+
+### `POST /admin/events/{eventPublicID}/defaults`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 固化 event 当前默认 active 绑定
+- 后续 publish 在未显式传参时，优先继承：
+  - `presentationId`
+  - `contentBundleId`
+  - `runtimeBindingId`
+
+核心参数：
+
+- `presentationId`
+- `contentBundleId`
+- `runtimeBindingId`
+
 ### `GET /admin/events/{eventPublicID}/pipeline`

 鉴权：
@@ -782,6 +972,57 @@

 - 将某次成功 build 发布成正式 release
 - 自动切换 event 当前 release
+- 可选在发布时直接挂接：
+  - `runtimeBindingId`
+  - `presentationId`
+  - `contentBundleId`
+- 如果未显式传入 `runtimeBindingId / presentationId / contentBundleId`，会优先按 event 当前默认 active 绑定自动补齐
+
+请求体重点：
+
+- `runtimeBindingId` 可选
+- `presentationId` 可选
+- `contentBundleId` 可选
+
+### `GET /admin/releases/{releasePublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看单个 release 明细
+- 带出当前已挂接的最小 runtime / presentation / content bundle 摘要
+
+当前 release 摘要最少包括：
+
+- `presentation.presentationId`
+- `presentation.templateKey`
+- `presentation.version`
+- `contentBundle.contentBundleId`
+- `contentBundle.bundleType`
+- `contentBundle.version`
+- `runtime.runtimeBindingId`
+- `runtime.placeId`
+- `runtime.mapId`
+- `runtime.tileReleaseId`
+- `runtime.courseVariantId`
+
+### `POST /admin/releases/{releasePublicID}/runtime-binding`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 将某个 `runtimeBindingId` 挂接到指定 release
+- 为后续 `launch.runtime` 提供运行对象来源
+
+请求体重点：
+
+- `runtimeBindingId`

 ### `POST /admin/events/{eventPublicID}/rollback`

@@ -797,4 +1038,247 @@

 - `releaseId`

+## 10. Admin 生产骨架
+
+说明：
+
+- 当前是总控确认后的第一阶段生产骨架接口
+- 重点先覆盖：
+  - `Place`
+  - `MapAsset`
+  - `TileRelease`
+  - `CourseSource`
+  - `CourseSet`
+  - `CourseVariant`
+  - `MapRuntimeBinding`
+- 这批接口不会替换现有 `events / event_releases / launch` 主链，而是增量补运行域对象
+
+### `GET /admin/places`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 获取地点对象列表
+
+### `POST /admin/places`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 新建地点对象
+
+请求体重点：
+
+- `code`
+- `name`
+- `region`
+- `coverUrl`
+- `description`
+- `centerPoint`
+- `status`
+
+### `GET /admin/places/{placePublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看地点详情
+- 同时带出该地点下的地图资产列表
+
+### `POST /admin/places/{placePublicID}/map-assets`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 在某个地点下创建地图资产
+
+请求体重点：
+
+- `code`
+- `name`
+- `mapType`
+- `legacyMapId`
+- `coverUrl`
+- `description`
+- `status`
+
+### `GET /admin/map-assets/{mapAssetPublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看地图资产详情
+- 同时带出瓦片版本和赛道集合摘要
+
+### `POST /admin/map-assets/{mapAssetPublicID}/tile-releases`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 为某个地图资产创建瓦片版本
+
+请求体重点：
+
+- `legacyVersionId`
+- `versionCode`
+- `tileBaseUrl`
+- `metaUrl`
+- `publishedAssetRoot`
+- `metadata`
+- `status`
+- `setAsCurrent`
+
+### `GET /admin/course-sources`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 获取赛道原始输入源列表
+
+### `POST /admin/course-sources`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 新建赛道原始输入源
+- 用于承接 KML / GeoJSON 等输入
+
+请求体重点：
+
+- `legacyPlayfieldId`
+- `legacyVersionId`
+- `sourceType`
+- `fileUrl`
+- `checksum`
+- `parserVersion`
+- `importStatus`
+- `metadata`
+
+### `GET /admin/course-sources/{sourcePublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看单个赛道输入源详情
+
+### `POST /admin/map-assets/{mapAssetPublicID}/course-sets`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 在某个地图资产下创建赛道集合
+
+请求体重点：
+
+- `code`
+- `mode`
+- `name`
+- `description`
+- `status`
+
+### `GET /admin/course-sets/{courseSetPublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看赛道集合详情
+- 同时带出它的 variant 列表
+
+### `POST /admin/course-sets/{courseSetPublicID}/variants`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 为某个赛道集合创建具体可运行赛道方案
+
+请求体重点：
+
+- `sourceId`
+- `name`
+- `routeCode`
+- `mode`
+- `controlCount`
+- `difficulty`
+- `configPatch`
+- `metadata`
+- `status`
+- `isDefault`
+
+### `GET /admin/runtime-bindings`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 获取活动运行绑定列表
+
+### `POST /admin/runtime-bindings`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 把活动和地点、地图资产、瓦片版本、赛道方案正式绑定起来
+
+请求体重点：
+
+- `eventId`
+- `placeId`
+- `mapAssetId`
+- `tileReleaseId`
+- `courseSetId`
+- `courseVariantId`
+- `status`
+- `notes`
+
+### `GET /admin/runtime-bindings/{runtimeBindingPublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看单个运行绑定详情
+