推进活动系统最小成品闭环与游客体验

backend/docs/接口清单.md

@@ -1,10 +1,14 @@
 # API 清单
-> 文档版本：v1.12
-> 最后更新：2026-04-03 22:34:08
+> 文档版本：v1.23
+> 最后更新：2026-04-07 16:08:37
 
 
 本文档只记录当前 backend 已实现接口，不写未来规划接口。
 
+当前已实现接口总数：
+
+- `115`
+
 ## 1. Health
 
 ### `GET /healthz`
@@ -13,6 +17,22 @@
 
 - 健康检查
 
+## 0. Workbench
+
+### `GET /dev/workbench`
+
+用途：
+
+- 调试工作台
+- 一键回归、日志查看、摘要排查
+
+### `GET /admin/ops-workbench`
+
+用途：
+
+- 运维后台第一期页面
+- 资源录入、OSS 纳管、地图瓦片导入、KML 批量导入
+
 ## 2. Auth
 
 ### `POST /auth/sms/send`
@@ -75,6 +95,264 @@
 
 - 撤销 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`
@@ -88,6 +366,50 @@
 - `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`
@@ -113,6 +435,55 @@
 - 只返回卡片列表
 - 当前与 `/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`
 
 鉴权：
@@ -153,6 +524,7 @@
 - `release`
 - `resolvedRelease`
 - `runtime`
+- `preview`
 - `currentPresentation`
 - `currentContentBundle`
 
@@ -165,6 +537,18 @@
 - `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`
 
 鉴权：
@@ -181,6 +565,7 @@
 - `release`
 - `resolvedRelease`
 - `runtime`
+- `preview`
 - `currentPresentation`
 - `currentContentBundle`
 - `play.assignmentMode`
@@ -209,6 +594,8 @@
 - `currentContentBundle.bundleType`
 - `currentContentBundle.version`
 
+当前 `preview` 继续表示准备页地图预览 V1 只读增强字段，结构与 `GET /events/{eventPublicID}` 相同。
+
 ### `POST /events/{eventPublicID}/launch`
 
 鉴权：
@@ -665,6 +1052,9 @@
 - 当前是后台第一版的最小对象接口
 - 先只做 Bearer 鉴权
 - 暂未接正式 RBAC / 管理员权限模型
+- 运维后台当前已开始切到独立前缀：
+  - `/ops/admin/*`
+  - 这批接口在运维后台中与 `/admin/*` 使用同一套 handler，语义一致
 
 ### `GET /admin/maps`
 
@@ -1259,6 +1649,28 @@
 - 查看地图资产详情
 - 同时带出瓦片版本和赛道集合摘要
 
+### `GET /admin/map-assets`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 查看地图资产列表
+- 返回地点、当前瓦片版本和关联活动摘要
+
+### `PUT /admin/map-assets/{mapAssetPublicID}`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 更新地图资产基础信息
+- 支持名称、封面、摘要、状态维护
+
 ### `POST /admin/map-assets/{mapAssetPublicID}/tile-releases`
 
 鉴权：
@@ -1415,6 +1827,114 @@
 
 - 查看单个运行绑定详情
 
+### `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`