cmr-mini/backend/docs/接口清单.md

# API 清单
> 文档版本：v1.23
> 最后更新：2026-04-07 16:08:37


本文档只记录当前 backend 已实现接口，不写未来规划接口。

当前已实现接口总数：

- `115`

## 1. Health

### `GET /healthz`

用途：

- 健康检查

## 0. Workbench

### `GET /dev/workbench`

用途：

- 调试工作台
- 一键回归、日志查看、摘要排查

### `GET /admin/ops-workbench`

用途：

- 运维后台第一期页面
- 资源录入、OSS 纳管、地图瓦片导入、KML 批量导入

## 2. Auth

### `POST /auth/sms/send`

用途：

- 发登录验证码
- 发绑定手机号验证码

核心参数：

- `countryCode`
- `mobile`
- `clientType`
- `deviceKey`
- `scene`

### `POST /auth/login/sms`

用途：

- APP 手机号验证码登录

返回重点：

- `user`
- `tokens.accessToken`
- `tokens.refreshToken`

### `POST /auth/login/wechat-mini`

用途：

- 微信小程序登录

开发态：

- 支持 `dev-` 前缀 code

### `POST /auth/bind/mobile`

鉴权：

- Bearer token

用途：

- 已登录用户绑定手机号
- 必要时执行账号合并

### `POST /auth/refresh`

用途：

- 刷新 access token

### `POST /auth/logout`

用途：

- 撤销 refresh token

## 2.1 Ops Auth

说明：

- 运维账号与前端玩家账号完全分离
- 生产环境走手机号验证码运维账号
- 开发环境为了录资源和调发布方便，`/admin/ops-workbench` 与 `/ops/admin/*` 默认免登录可用

### `POST /ops/auth/sms/send`

用途：

- 发送运维账号登录 / 注册验证码

### `POST /ops/auth/register`

用途：

- 注册独立运维账号
- 首个账号默认授予 `owner`

### `POST /ops/auth/login/sms`

用途：

- 运维账号手机号验证码登录

### `POST /ops/auth/refresh`

用途：

- 刷新运维 access token

### `POST /ops/auth/logout`

用途：

- 撤销运维 refresh token

### `GET /ops/me`

鉴权：

- Ops bearer token

用途：

- 获取当前运维账号信息和主角色

## 2.2 Ops Admin（地图资源管理第一刀）

### `GET /ops/admin/summary`

用途：

- 运维后台总览聚合接口
- 返回资源、活动、运行绑定、发布版本统计

### `GET /ops/admin/assets`

用途：

- 读取受管资源列表
- 给运维后台资源总览与录入校验使用

### `POST /ops/admin/assets/register-link`

用途：

- 登记已有正式外链资源
- 统一纳管到 backend 资源对象

### `POST /ops/admin/assets/upload`

用途：

- 上传文件给 backend，再统一存入 OSS
- 运维不需要自己处理底层存储细节

### `GET /ops/admin/assets/{assetPublicID}`

用途：

- 查看单个受管资源详情
- 返回资源类型、版本、正式 URL 和元数据

### `GET /ops/admin/places`

用途：

- 读取地点列表
- 给运维后台地图资源管理区做浏览入口

### `POST /ops/admin/places`

用途：

- 新建地点

### `GET /ops/admin/places/{placePublicID}`

用途：

- 读取地点详情
- 返回当前地点下的地图资源列表

### `POST /ops/admin/places/{placePublicID}/map-assets`

用途：

- 在指定地点下新建地图资源

### `GET /ops/admin/map-assets/{mapAssetPublicID}`

用途：

- 读取地图资源详情
- 返回当前瓦片版本、关联赛道集和关联活动摘要

### `GET /ops/admin/map-assets`

用途：

- 读取地图列表
- 返回地点、当前瓦片版本和关联活动摘要

### `PUT /ops/admin/map-assets/{mapAssetPublicID}`

用途：

- 更新地图基础信息
- 支持名称、封面、摘要、状态维护

### `POST /ops/admin/map-assets/{mapAssetPublicID}/tile-releases`

用途：

- 给地图资源追加新的瓦片版本

### `POST /ops/admin/ops/tile-releases/import`

用途：

- 一次录入 `place + map asset + tile release`
- 运维录入地图瓦片版本的最小入口

### `GET /ops/admin/course-sources`

用途：

- 运维后台读取 KML / GeoJSON 输入源列表

### `GET /ops/admin/course-sources/{sourcePublicID}`

用途：

- 运维后台读取单个赛道输入源详情

### `GET /ops/admin/course-sets/{courseSetPublicID}`

用途：

- 运维后台读取赛道集合详情
- 用于默认路线和路线预览

### `POST /ops/admin/ops/course-sets/import-kml-batch`

用途：

- 批量录入一组 KML
- 自动生成 `course set + variants`

### `GET /ops/admin/events`

用途：

- 运维后台活动列表
- 给地图关联活动区做浏览入口

### `POST /ops/admin/events`

用途：

- 运维后台新建活动
- 先录活动基础信息，再进入默认绑定和发布链

### `GET /ops/admin/events/{eventPublicID}`

用途：

- 运维后台活动详情
- 返回默认绑定和当前 source 摘要

### `PUT /ops/admin/events/{eventPublicID}`

用途：

- 运维后台更新活动基础信息
- 支持名称、摘要、slug、状态维护

### `POST /ops/admin/events/{eventPublicID}/presentations/import`

用途：

- 导入活动展示定义
- 用于当前活动默认绑定与发布

### `POST /ops/admin/events/{eventPublicID}/content-bundles/import`

用途：

- 导入活动内容包
- 用于当前活动默认绑定与发布

### `POST /ops/admin/events/{eventPublicID}/defaults`

用途：

- 保存活动默认绑定
- 固化 `runtime / presentation / content bundle` 三元组

### `GET /ops/admin/events/{eventPublicID}/pipeline`

用途：

- 读取活动发布链概览
- 返回 source / build / release 摘要

### `POST /ops/admin/sources/{sourceID}/build`

用途：

- 基于 source 构建 build

### `GET /ops/admin/builds/{buildID}`

用途：

- 读取单个 build 明细

### `POST /ops/admin/builds/{buildID}/publish`

用途：

- 发布 build 为正式 release

### `GET /ops/admin/releases/{releasePublicID}`

用途：

- 读取单个 release 详情

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

用途：

- 将活动当前 release 回滚到指定版本

## 3. Entry / Home

### `GET /entry/resolve`

用途：

- 解析当前入口归属哪个 tenant / channel

查询参数：

- `channelCode`
- `channelType`
- `platformAppId`

## 3.1 Public Experience

### `GET /public/experience-maps`

用途：

- 游客模式地图列表
- 返回可公开体验的地图与默认活动摘要

### `GET /public/experience-maps/{mapAssetPublicID}`

用途：

- 游客模式地图详情
- 返回某张地图下挂载的默认体验活动

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

用途：

- 游客模式活动详情
- 只允许默认体验活动

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

用途：

- 游客模式准备页聚合接口
- 返回 `canLaunch`、`assignmentMode`、`courseVariants`、`preview`

### `POST /public/events/{eventPublicID}/launch`

用途：

- 游客模式启动一局
- 返回与正式 launch 近似结构，并带 `business.isGuest = true`

核心参数：

- `releaseId`
- `variantId`
- `clientType`
- `deviceKey`
- `tenantCode`

### `GET /home`

用途：

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

### `GET /cards`

用途：

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

当前额外补充：

- `showInEventList`

### `GET /experience-maps`

用途：

- 地图资源列表
- 返回每张地图下默认体验活动数量和默认活动 ID 列表

返回重点：

- `placeId`
- `placeName`
- `mapId`
- `mapName`
- `coverUrl`
- `summary`
- `defaultExperienceCount`
- `defaultExperienceEventIds`

### `GET /experience-maps/{mapAssetPublicID}`

用途：

- 地图详情
- 返回地图基础信息和默认体验活动摘要

返回重点：

- `tileBaseUrl`
- `tileMetaUrl`
- `defaultExperiences[]`

`defaultExperiences[]` 当前包含：

- `eventId`
- `title`
- `subtitle`
- `eventType`
- `status`
- `statusCode`
- `ctaText`
- `isDefaultExperience`
- `showInEventList`
- `currentPresentation`
- `currentContentBundle`

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

鉴权：

- Bearer token

用途：

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

返回重点：

- `user`
- `tenant`
- `channel`
- `cards`
- `ongoingSession`
- `recentSession`

`ongoingSession / recentSession` 当前会额外带：

- `variantId`
- `variantName`
- `routeCode`

## 4. Event

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

用途：

- Event 详情

返回重点：

- `event`
- `release`
- `resolvedRelease`
- `runtime`
- `preview`
- `currentPresentation`
- `currentContentBundle`

当前摘要字段最少包括：

- `currentPresentation.presentationId`
- `currentPresentation.templateKey`
- `currentPresentation.version`
- `currentContentBundle.contentBundleId`
- `currentContentBundle.bundleType`
- `currentContentBundle.version`

当前 `preview` 为准备页地图预览 V1 只读增强字段，最小包括：

- `preview.mode`
- `preview.baseTiles.tileBaseUrl`
- `preview.baseTiles.zoom`
- `preview.baseTiles.tileSize`
- `preview.viewport.width / height`
- `preview.viewport.minLon / minLat / maxLon / maxLat`
- `preview.variants[].controls`
- `preview.variants[].legs`
- `preview.selectedVariantId`

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

鉴权：

- Bearer token

用途：

- 活动详情页 / 开始前准备页聚合

返回重点：

- `event`
- `release`
- `resolvedRelease`
- `runtime`
- `preview`
- `currentPresentation`
- `currentContentBundle`
- `play.assignmentMode`
- `play.courseVariants`
- `play.canLaunch`
- `play.primaryAction`
- `play.launchSource`
- `play.ongoingSession`
- `play.recentSession`

当前 `play.canLaunch=true` 的最小前置条件为：

- event `status = active`
- 当前已发布 release 存在
- 当前已发布 release 有 `manifest`
- 当前已发布 release 已绑定 `runtime`
- 当前已发布 release 已绑定 `presentation`
- 当前已发布 release 已绑定 `content bundle`

当前摘要字段最少包括：

- `currentPresentation.presentationId`
- `currentPresentation.templateKey`
- `currentPresentation.version`
- `currentContentBundle.contentBundleId`
- `currentContentBundle.bundleType`
- `currentContentBundle.version`

当前 `preview` 继续表示准备页地图预览 V1 只读增强字段，结构与 `GET /events/{eventPublicID}` 相同。

### `POST /events/{eventPublicID}/launch`

鉴权：

- Bearer token

用途：

- 基于当前 event 的可启动 release 创建一局 session

请求体重点：

- `releaseId`
- `variantId`
- `clientType`
- `deviceKey`

补充说明：

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

返回重点：

- `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`

鉴权：

- Bearer token

用途：

- 查看某个 event 的 source config 列表

### `GET /config-sources/{sourceID}`

鉴权：

- Bearer token

用途：

- 查看单条 source config 明细

### `GET /config-builds/{buildID}`

鉴权：

- Bearer token

用途：

- 查看单次 build 明细

## 5. Session

### `GET /sessions/{sessionPublicID}`

鉴权：

- Bearer token

用途：

- 查询一局详情

返回重点：

- `session`
- `event`
- `resolvedRelease`

`session` 当前会额外带：

- `assignmentMode`
- `variantId`
- `variantName`
- `routeCode`

### `POST /sessions/{sessionPublicID}/start`

鉴权：

- `sessionToken`

用途：

- 将 session 从 `launched` 推进到 `running`

补充约束：

- 幂等
- 重复调用时：
  - `launched` 会推进到 `running`
  - `running` 或已终态直接返回当前 session

### `POST /sessions/{sessionPublicID}/finish`

鉴权：

- `sessionToken`

用途：

- 结束一局
- 同时沉淀结果摘要

当前结束语义：

- `finished`：正常完成
- `failed`：超时或规则失败
- `cancelled`：主动退出或放弃恢复

补充约束：

- 幂等
- 已终态重复调用直接返回当前 session / result
- `finish(cancelled)` 是当前“放弃恢复”的官方后端语义
- 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用

请求体重点：

- `sessionToken`
- `status`
- `summary.finalDurationSec`
- `summary.finalScore`
- `summary.completedControls`
- `summary.totalControls`
- `summary.distanceMeters`
- `summary.averageSpeedKmh`
- `summary.maxHeartRateBpm`

### `GET /me/sessions`

鉴权：

- Bearer token

用途：

- 查询用户最近 session

## 6. Result

### `GET /sessions/{sessionPublicID}/result`

鉴权：

- Bearer token

用途：

- 查询单局结果页数据

返回重点：

- `session`
- `result`

`session` 中会带：

- `releaseId`
- `configLabel`
- `variantId`
- `variantName`
- `routeCode`

### `GET /me/results`

鉴权：

- Bearer token

用途：

- 查询用户最近结果列表

## 7. Profile

### `GET /me`

鉴权：

- Bearer token

用途：

- 当前用户基础信息

### `GET /me/profile`

鉴权：

- Bearer token

用途：

- “我的页”聚合接口

返回重点：

- `user`
- `bindings`
- `recentSessions`

## 8. Dev

### `POST /dev/bootstrap-demo`

环境：

- 仅 non-production

用途：

- 自动准备 demo tenant / channel / event / release / card

### `POST /dev/client-logs`

环境：

- 仅 non-production

用途：

- 接收 frontend 主动上报的调试日志
- 供 backend 通过 workbench 统一查看和排查

请求体重点：

- `source`
- `level`
- `category`
- `message`
- `eventId`
- `releaseId`
- `sessionId`
- `manifestUrl`
- `route`
- `occurredAt`
- `details`

补充说明：

- 当前只保存在内存中
- 默认最多保留最近 200 条
- 仅用于联调调试

### `GET /dev/client-logs`

环境：

- 仅 non-production

用途：

- 获取 frontend 最近上报的调试日志

查询参数：

- `limit`

### `DELETE /dev/client-logs`

环境：

- 仅 non-production

用途：

- 清空当前内存中的 frontend 调试日志

### `GET /dev/workbench`

环境：

- 仅 non-production

用途：

- 后端自带 API 测试面板

当前支持：

- bootstrap
- auth
- entry/home
- event/play/launch
- session start/finish/detail
- result 查询
- profile 查询
- quick flows
- scenarios
- request history
- curl 导出
- frontend 调试日志查看/清空

### `GET /dev/manifest-summary`

环境：

- 仅 non-production

用途：

- 由 backend 代读指定 manifest
- 返回最小调试摘要：
  - `schemaVersion`
  - `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 联调排查
- 不参与正式客户端运行链路

### `GET /dev/config/local-files`

环境：

- 仅 non-production

用途：

- 列出本地配置目录中的 JSON 文件

### `POST /dev/events/{eventPublicID}/config-sources/import-local`

环境：

- 仅 non-production

用途：

- 从本地配置目录导入 source config

请求体重点：

- `fileName`
- `notes`

### `POST /dev/config-builds/preview`

环境：

- 仅 non-production

用途：

- 基于 source config 生成 preview build

请求体重点：

- `sourceId`

### `POST /dev/config-builds/publish`

环境：

- 仅 non-production

用途：

- 将成功的 preview build 发布成正式 release
- 自动切换 `event.current_release_id`

请求体重点：

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

返回重点：

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

## 9. Admin 资源对象

说明：

- 当前是后台第一版的最小对象接口
- 先只做 Bearer 鉴权
- 暂未接正式 RBAC / 管理员权限模型
- 运维后台当前已开始切到独立前缀：
  - `/ops/admin/*`
  - 这批接口在运维后台中与 `/admin/*` 使用同一套 handler，语义一致

### `GET /admin/maps`

鉴权：

- Bearer token

用途：

- 获取地图对象列表

### `POST /admin/maps`

鉴权：

- Bearer token

用途：

- 新建地图对象

请求体重点：

- `code`
- `name`
- `status`
- `description`

### `GET /admin/maps/{mapPublicID}`

鉴权：

- Bearer token

用途：

- 获取地图对象详情和版本列表

### `POST /admin/maps/{mapPublicID}/versions`

鉴权：

- Bearer token

用途：

- 新建地图版本

请求体重点：

- `versionCode`
- `mapmetaUrl`
- `tilesRootUrl`
- `status`
- `publishedAssetRoot`
- `bounds`
- `metadata`
- `setAsCurrent`

### `GET /admin/playfields`

鉴权：

- Bearer token

用途：

- 获取赛场 / KML 对象列表

### `POST /admin/playfields`

鉴权：

- Bearer token

用途：

- 新建赛场对象

请求体重点：

- `code`
- `name`
- `kind`
- `status`
- `description`

### `GET /admin/playfields/{playfieldPublicID}`

鉴权：

- Bearer token

用途：

- 获取赛场对象详情和版本列表

### `POST /admin/playfields/{playfieldPublicID}/versions`

鉴权：

- Bearer token

用途：

- 新建赛场版本

请求体重点：

- `versionCode`
- `sourceType`
- `sourceUrl`
- `controlCount`
- `status`
- `publishedAssetRoot`
- `bounds`
- `metadata`
- `setAsCurrent`

### `GET /admin/resource-packs`

鉴权：

- Bearer token

用途：

- 获取资源包对象列表

### `POST /admin/resource-packs`

鉴权：

- Bearer token

用途：

- 新建资源包对象

请求体重点：

- `code`
- `name`
- `status`
- `description`

### `GET /admin/resource-packs/{resourcePackPublicID}`

鉴权：

- Bearer token

用途：

- 获取资源包对象详情和版本列表

### `POST /admin/resource-packs/{resourcePackPublicID}/versions`

鉴权：

- Bearer token

用途：

- 新建资源包版本

请求体重点：

- `versionCode`
- `contentEntryUrl`
- `audioRootUrl`
- `themeProfileCode`
- `status`
- `publishedAssetRoot`
- `metadata`
- `setAsCurrent`

### `GET /admin/events`

鉴权：

- Bearer token

用途：

- 获取后台 Event 列表

### `POST /admin/events`

鉴权：

- Bearer token

用途：

- 新建后台 Event

请求体重点：

- `tenantCode`
- `slug`
- `displayName`
- `summary`
- `status`

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

鉴权：

- Bearer token

用途：

- 获取后台 Event 详情
- 返回最新 source config 摘要

### `PUT /admin/events/{eventPublicID}`

鉴权：

- Bearer token

用途：

- 更新 Event 基础信息

请求体重点：

- `tenantCode`
- `slug`
- `displayName`
- `summary`
- `status`

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

鉴权：

- Bearer token

用途：

- 用地图版本、赛场版本、资源包版本组装一版 source config
- 直接落到现有 `event_config_sources`

请求体重点：

- `map.mapId`
- `map.versionId`
- `playfield.playfieldId`
- `playfield.versionId`
- `resourcePack.resourcePackId`
- `resourcePack.versionId`
- `gameModeCode`
- `routeCode`
- `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`

鉴权：

- Bearer token

用途：

- 从后台视角聚合查看某个 event 的：
  - sources
  - builds
  - releases
  - current release

### `POST /admin/sources/{sourceID}/build`

鉴权：

- Bearer token

用途：

- 基于某个 source 生成 preview build

### `GET /admin/builds/{buildID}`

鉴权：

- Bearer token

用途：

- 查看某次 build 详情

### `POST /admin/builds/{buildID}/publish`

鉴权：

- Bearer token

用途：

- 将某次成功 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`

鉴权：

- Bearer token

用途：

- 将 event 当前 release 显式切回某个已发布 release

请求体重点：

- `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

用途：

- 查看地图资产详情
- 同时带出瓦片版本和赛道集合摘要

### `GET /admin/map-assets`

鉴权：

- Bearer token

用途：

- 查看地图资产列表
- 返回地点、当前瓦片版本和关联活动摘要

### `PUT /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

用途：

- 查看单个运行绑定详情

### `POST /admin/ops/tile-releases/import`

鉴权：

- Bearer token

用途：

- 运维入口第一期：按 `place + map asset + tile release` 一次录入瓦片版本
- 可在录入时直接指定 `setAsCurrent`

请求体重点：

- `placeCode`
- `placeName`
- `mapAssetCode`
- `mapAssetName`
- `mapType`
- `versionCode`
- `tileBaseUrl`
- `metaUrl`
- `publishedAssetRoot`
- `setAsCurrent`

### `POST /admin/ops/course-sets/import-kml-batch`

鉴权：

- Bearer token

用途：

- 运维入口第一期：按一组 KML 路线批量录入赛道集合与 variants
- 适合把同一场地的一批路线一次性整理成 `course set`

请求体重点：

- `placeCode`
- `placeName`
- `mapAssetCode`
- `mapAssetName`
- `mapType`
- `courseSetCode`
- `courseSetName`
- `mode`
- `defaultRouteCode`
- `routes[]`

### `GET /admin/assets`

鉴权：

- Bearer token

用途：

- 查看当前 backend 已纳管的正式资源对象列表

### `POST /admin/assets/register-link`

鉴权：

- Bearer token

用途：

- 登记一个已有正式外链为受管资源

请求体重点：

- `assetType`
- `assetCode`
- `version`
- `publicUrl`
- `status`
- `metadata`

### `POST /admin/assets/upload`

鉴权：

- Bearer token

用途：

- 通过 backend 上传一个正式资源文件到 OSS，并自动纳管

表单重点：

- `assetType`
- `assetCode`
- `version`
- `title`
- `objectDir` 可选
- `status`
- `metadataJson` 可选
- `file`

### `GET /admin/assets/{assetPublicID}`

鉴权：

- Bearer token

用途：

- 查看单个已纳管资源对象详情


### `GET /home`

用途：

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

### `GET /cards`

用途：

- 按入口返回活动卡片列表
- 当前与 `/home` 使用同一套卡片摘要语义

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

鉴权：

- Bearer token

用途：

- 返回“我的首页”聚合
- 当前 `cards` 也已统一使用活动卡片最小摘要字段