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