1452 lines
20 KiB
Markdown
1452 lines
20 KiB
Markdown
# API 清单
|
||
> 文档版本：v1.12
|
||
> 最后更新：2026-04-03 22:34:08
|
||
|
||
|
||
本文档只记录当前 backend 已实现接口，不写未来规划接口。
|
||
|
||
## 1. Health
|
||
|
||
### `GET /healthz`
|
||
|
||
用途：
|
||
|
||
- 健康检查
|
||
|
||
## 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
|
||
|
||
## 3. Entry / Home
|
||
|
||
### `GET /entry/resolve`
|
||
|
||
用途：
|
||
|
||
- 解析当前入口归属哪个 tenant / channel
|
||
|
||
查询参数：
|
||
|
||
- `channelCode`
|
||
- `channelType`
|
||
- `platformAppId`
|
||
- `tenantCode`
|
||
|
||
### `GET /home`
|
||
|
||
用途：
|
||
|
||
- 返回入口首页卡片
|
||
- 当前卡片摘要字段已统一补齐：
|
||
- `summary`
|
||
- `status`
|
||
- `statusCode`
|
||
- `timeWindow`
|
||
- `ctaText`
|
||
- `isDefaultExperience`
|
||
- `eventType`
|
||
- `currentPresentation`
|
||
- `currentContentBundle`
|
||
|
||
### `GET /cards`
|
||
|
||
用途：
|
||
|
||
- 只返回卡片列表
|
||
- 当前与 `/home` 使用同一套卡片摘要语义
|
||
|
||
### `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`
|
||
- `currentPresentation`
|
||
- `currentContentBundle`
|
||
|
||
当前摘要字段最少包括：
|
||
|
||
- `currentPresentation.presentationId`
|
||
- `currentPresentation.templateKey`
|
||
- `currentPresentation.version`
|
||
- `currentContentBundle.contentBundleId`
|
||
- `currentContentBundle.bundleType`
|
||
- `currentContentBundle.version`
|
||
|
||
### `GET /events/{eventPublicID}/play`
|
||
|
||
鉴权：
|
||
|
||
- Bearer token
|
||
|
||
用途：
|
||
|
||
- 活动详情页 / 开始前准备页聚合
|
||
|
||
返回重点：
|
||
|
||
- `event`
|
||
- `release`
|
||
- `resolvedRelease`
|
||
- `runtime`
|
||
- `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`
|
||
|
||
### `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 / 管理员权限模型
|
||
|
||
### `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
|
||
|
||
用途：
|
||
|
||
- 查看地图资产详情
|
||
- 同时带出瓦片版本和赛道集合摘要
|
||
|
||
### `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
|
||
|
||
用途：
|
||
|
||
- 查看单个运行绑定详情
|
||
|
||
|
||
### `GET /home`
|
||
|
||
用途：
|
||
|
||
- 返回入口首页摘要
|
||
- 当前卡片摘要字段已统一补齐：
|
||
- `summary`
|
||
- `status`
|
||
- `statusCode`
|
||
- `timeWindow`
|
||
- `ctaText`
|
||
- `isDefaultExperience`
|
||
- `eventType`
|
||
- `currentPresentation`
|
||
- `currentContentBundle`
|
||
|
||
### `GET /cards`
|
||
|
||
用途：
|
||
|
||
- 按入口返回活动卡片列表
|
||
- 当前与 `/home` 使用同一套卡片摘要语义
|
||
|
||
### `GET /me/entry-home`
|
||
|
||
鉴权：
|
||
|
||
- Bearer token
|
||
|
||
用途：
|
||
|
||
- 返回“我的首页”聚合
|
||
- 当前 `cards` 也已统一使用活动卡片最小摘要字段
|