同步前后端联调与文档更新

backend/docs/接口清单.md

@@ -1,6 +1,6 @@
 # API 清单
 > 文档版本：v1.0
-> 最后更新：2026-04-02
+> 最后更新：2026-04-02 09:01:17
 
 
 本文档只记录当前 backend 已实现接口，不写未来规划接口。
@@ -238,6 +238,13 @@
 
 - 将 session 从 `launched` 推进到 `running`
 
+补充约束：
+
+- 幂等
+- 重复调用时：
+  - `launched` 会推进到 `running`
+  - `running` 或已终态直接返回当前 session
+
 ### `POST /sessions/{sessionPublicID}/finish`
 
 鉴权：
@@ -249,6 +256,19 @@
 - 结束一局
 - 同时沉淀结果摘要
 
+当前结束语义：
+
+- `finished`：正常完成
+- `failed`：超时或规则失败
+- `cancelled`：主动退出或放弃恢复
+
+补充约束：
+
+- 幂等
+- 已终态重复调用直接返回当前 session / result
+- `finish(cancelled)` 是当前“放弃恢复”的官方后端语义
+- 同一局旧 `sessionToken` 在 `finish(cancelled)` 场景允许继续使用
+
 请求体重点：
 
 - `sessionToken`
@@ -427,3 +447,328 @@
 - `release.manifestUrl`
 - `release.configLabel`
 
+## 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}/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
+
+### `POST /admin/events/{eventPublicID}/rollback`
+
+鉴权：
+
+- Bearer token
+
+用途：
+
+- 将 event 当前 release 显式切回某个已发布 release
+
+请求体重点：
+
+- `releaseId`
+
+