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

2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
--- a/backend/docs/README.md
+++ b/backend/docs/README.md
@@ -1,6 +1,6 @@
 # Backend Docs
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.1
+> 最后更新：2026-04-07 18:47:09


 这套文档服务两个目的：
@@ -20,6 +20,7 @@
 8. [前后端联调清单](D:/dev/cmr-mini/backend/docs/前后端联调清单.md)
 9. [TodoList](D:/dev/cmr-mini/backend/docs/todolist.md)
 10. [开发说明](D:/dev/cmr-mini/backend/docs/开发说明.md)
+11. [B2B 交接文档](D:/dev/cmr-mini/b2b.md)

 ## 当前系统范围

--- a/backend/docs/后台管理最小方案.md
+++ b/backend/docs/后台管理最小方案.md
@@ -1,6 +1,6 @@
 # 后台管理最小方案
-> 文档版本：v1.1
-> 最后更新：2026-04-03 11:02:42
+> 文档版本：v1.8
+> 最后更新：2026-04-07 17:23:15

 ## 1. 目标

@@ -176,16 +176,16 @@

 ## 4. 后台第一版页面建议

-按最小闭环，建议先做 6 个页面：
+按当前运维工作流，建议先按“地图主流程”组织，而不是把底层对象散着摆：

 1. 地图列表页
-2. 赛场 / KML 列表页
-3. 资源包列表页
-4. Event 列表与编辑页
-5. Build / Release 列表页
-6. 发布详情页
+2. 地图详情页
+3. KML / 赛道管理页
+4. 活动管理页
+5. 发布中心
+6. 资源总览页

-这 6 页够把“资源录入 -> Event 组装 -> 发布 -> launch”跑通。
+这 6 页的目标是把“资源录入 -> 地图管理 -> 赛道管理 -> 活动绑定 -> 发布”跑通。

 补充：

@@ -216,8 +216,112 @@
 - `event` 只做引用和少量覆盖
 - `release` 固化具体版本引用

+### 5.1 当前活动模型收口原则
+
+为了让前台卡片、详情页、发布语义和运维操作都保持简单，当前活动模型先明确收成最小可玩单元：
+
+- `单地图`
+- `单路线组`
+- `单玩法`
+
+也就是第一阶段一个活动只表达一件事：
+
+> 在这张地图上，使用这组路线，按这一个玩法运行。
+
+当前不建议第一阶段直接支持：
+
+- 一个活动绑定多张地图
+- 一个活动绑定多组路线
+- 一个活动同时支持多玩法
+
+复杂需求先通过“活动实例化”解决，而不是在一个活动里做多对多编排。例如：
+
+- 地图 A + 路线组 1 + 顺序赛 = 活动 A1
+- 地图 A + 路线组 2 + 顺序赛 = 活动 A2
+- 地图 A + 路线组 2 + 积分赛 = 活动 A3
+
+这样做的目的：
+
+- 前台卡片逻辑简单
+- 发布语义明确
+- 结果追溯简单
+- 运维后台第一期不需要一开始就做复杂配置器
+
+后续如果确实需要复杂组合，优先考虑：
+
+- 基于模板批量实例化多个活动
+
+而不是直接把单个活动扩成多地图、多路线组、多玩法容器。
+
+### 5.2 组合入口层原则
+
+多地图、多路线组、多玩法这类需求后面仍然会存在，但当前建议放在“组合入口层”解决，不直接进入单个活动的运行模型。
+
+也就是分成两层：
+
+1. 运行实例层
+- 一个活动实例始终保持：
+  - `单地图`
+  - `单路线组`
+  - `单玩法`
+
+2. 组合入口层
+- 通过组合卡片或组合入口，把多个活动实例编排成一个前台入口
+- 例如：
+  - 多地图合集
+  - 多玩法合集
+  - 不同难度合集
+  - 同主题活动合集
+
+这样做的目的：
+
+- 前台入口可以灵活组合
+- backend 的发布、回溯、结果沉淀仍然保持简单
+- 运维后台第一期不需要一开始就做复杂多对多编排器
+- 后面若要扩能力，也是在“组合层”扩，而不是把底层活动模型搞乱
+
 ## 6. 一条完整后台工作流

+## 7. 运维入口第一期
+
+当前已经开始落地一条“先运维录入、再活动绑定发布”的最小入口，不再只靠手工脚本或改代码上传资源。
+
+第一期先开放两条：
+
+1. `POST /admin/ops/tile-releases/import`
+   - 作用：一次录入 `place + map asset + tile release`
+   - 适合把地图瓦片版本登记进 backend
+
+2. `POST /admin/ops/course-sets/import-kml-batch`
+   - 作用：一次录入一组 KML，生成 `course set + variants`
+   - 适合多赛道活动的批量路线导入
+
+第一期边界：
+
+- 只做录入
+- 只做对象登记和最小 current 绑定
+- 已开始落地独立运维后台 `/admin/ops-workbench`
+- 不替代后续完整运维后台
+
+当前第一版页面结构已经按主流程拆成：
+
+1. `资源总览`
+2. `地图管理`
+3. `资源录入`
+4. `KML / 赛道管理`
+5. `活动管理`
+6. `发布中心`
+
+当前设计原则：
+
+- 运维首先看到“地图列表”
+- KML / 赛道围绕地图管理，不作为孤立对象平铺
+- 活动管理围绕地图关联活动、默认体验活动和发布状态展开
+- 活动编排当前先按“单地图 + 单路线组 + 单玩法”收口
+- 多地图 / 多玩法需求当前先通过“组合卡片 / 组合入口”承接
+- 地图、KML、活动尽量统一成“列表 / 新增 / 修改 / 详情 / 预览 / 发布关联”的相似使用习惯
+- 底层对象如 `Place / MapAsset / TileRelease / CourseSource / CourseSet` 继续保留，但收进主流程内部，不作为首页认知入口
+
 ```mermaid
 flowchart LR
  A["录入地图版本"] --> D["Event 选择地图版本"]
@@ -327,7 +431,21 @@ flowchart LR
 2. `Event` 组装接口 `/admin/events`、`/admin/events/{id}/source` 已完成
 3. `pipeline/build/publish` 后台聚合接口已完成
 4. `rollback` 已完成
-5. 下一步是把这批接口接进 workbench 或正式后台页面
+5. 运维入口第一期已完成：
+   - `POST /admin/ops/tile-releases/import`
+   - `POST /admin/ops/course-sets/import-kml-batch`
+6. 运维入口第二期已开始：
+   - `POST /admin/assets/upload`
+   - `POST /admin/assets/register-link`
+   - `GET /admin/assets`
+   - `GET /admin/assets/{assetPublicID}`
+7. 运维后台第一版结构已开始落地到 `/admin/ops-workbench`：
+   - `资源总览`
+   - `资源录入`
+   - `赛道集管理`
+   - `活动绑定`
+   - `发布中心`
+8. 下一步是继续把更多资源对象与发布细节收进这套运维台，而不是再塞回调试工作台

 ## 10. 一句话结论

--- a/backend/docs/开发说明.md
+++ b/backend/docs/开发说明.md
@@ -1,6 +1,6 @@
 # 开发说明
-> 文档版本：v1.25
-> 最后更新：2026-04-03 18:56:46
+> 文档版本：v1.45
+> 最后更新：2026-04-07 18:15:01


 ## 1. 环境变量
@@ -18,6 +18,50 @@
 - `WECHAT_MINI_APP_ID`
 - `WECHAT_MINI_APP_SECRET`
 - `WECHAT_MINI_DEV_PREFIX`
+
+## 2. 运维后台当前结构
+
+- 运维后台入口：`/admin/ops-workbench`
+- 当前采用：
+  - 左侧：流程导航
+  - 中间：单主视图
+  - 右侧：状态 / 日志 / 最近对象
+- 当前主流程导航：
+  - `资源总览`
+  - `地图 / 地点管理`
+  - `路线资源管理`
+  - `活动管理`
+  - `活动编排`
+  - `发布中心`
+  - `资源录入` 作为辅助入口保留
+- `资源总览` 优先展示：
+  - 地点、地图、瓦片版本、受管资源
+  - 路线组、路线变体、运行绑定、配置源
+  - 活动数、默认体验活动、已发布活动、发布版本、展示定义、内容包、运维账号
+- `地图 / 地点管理` 当前收成：
+  - 先看地图列表
+  - 右上角入口：`添加地图 / 添加地点`
+  - 点击地图进入详情弹出层
+  - 新增 / 编辑地图走独立弹出层
+  - 新增地点走独立弹出层
+  - 地点编辑区使用省/市两级选择，并回填到 `region`
+  - 地图详情只保留：
+    - 当前瓦片版本
+    - 默认体验活动概况
+    - 关联活动数量与摘要
+  - 关联活动详情统一去 `活动管理`
+- 省市数据当前来自在线公开数据源：
+  - `uiwjs/province-city-china`
+  - backend 通过 `/ops/admin/region-options` 统一提供给运维台，页面本身不直连第三方源
+  - 当前选中活动的 `release / runtime / presentation / content bundle`
+- 地图页当前只显示关联活动数量与摘要，不再平铺活动详情；活动详情和默认绑定统一放到 `活动管理 / 活动编排`。
+- `地图 / 地点管理` 当前已支持：
+  - 地点列表
+  - 地图列表
+  - 地图关键字筛选
+  - 点列表项直接读取详情
+  - 选地点后自动带出该地点下地图
+  - 选地图后自动带出当前瓦片版本、默认活动概况和地图预览摘要
 - `LOCAL_EVENT_DIR`
 - `ASSET_BASE_URL`
 - `ASSET_PUBLIC_BASE_URL`
@@ -39,17 +83,86 @@ cd D:\dev\cmr-mini\backend
 .\scripts\start-dev.ps1
 ```

+开发环境补充：
+
+- 运维后台入口：`/admin/ops-workbench`
+- 运维接口前缀：`/ops/admin/*`
+- 当 `APP_ENV != production` 时：
+  - 缺少 token 会直接进入 dev ops 上下文
+  - 残留旧 token、玩家 token、失效 token 也会自动回退到 dev ops 上下文
+  - 目的是避免开发联调时每次都要重新登录
+
 ## 3. Workbench 当前重点

 - 推荐联调入口：
-  - `Bootstrap Demo`
+  - `Bootstrap Demo（只准备数据）`
+  - `Bootstrap + 发布当前玩法`
  - `Use Classic Demo / Use Score-O Demo / Use Manual Variant Demo`
  - `整条链一键验收`
+- `Bootstrap Demo（只准备数据）` 当前会直接准备三条标准 demo 的基础已发布态：
+  - `evt_demo_001`
+  - `evt_demo_score_o_001`
+  - `evt_demo_variant_manual_001`
+- 这三条 demo 在 bootstrap 后都会直接带上：
+  - 当前 release
+  - runtime
+  - presentation
+  - content bundle
+- 也就是说，frontend 当前从首页选择三种玩法时，不需要再额外先点一次发布按钮，已经能直接按“当前已发布 release”语义联调入口、详情和 `canLaunch`
 - 当前玩法切换除了切 `event / release / source / build`，还会自动切换：
  - `presentation schema`
+
+## 4. 运维后台当前主流程
+
+运维后台入口：
+
+- [http://127.0.0.1:18090/admin/ops-workbench](http://127.0.0.1:18090/admin/ops-workbench)
+
+当前不再把运维动作混在调试后台里，统一分成 3 条管理线：
+
+1. 地图管理
+- 先看地图列表
+- 再做新建 / 编辑
+- 然后看当前瓦片版本、默认活动和关联活动
+
+2. KML / 赛道管理
+- 围绕当前地图导入一组 KML
+- 查看当前地图下赛道集
+- 查看默认路线和路线摘要
+
+3. 活动管理
+- 先看活动列表
+- 再做新建 / 修改 / 读取详情
+- 然后管理默认 `runtime / presentation / content bundle`
+- 最后进入发布中心
+
+当前 UI 组织方式也已收口：
+
+- 左侧：流程导航
+- 中间：单主视图
+- 右侧：状态 / 日志 / 最近对象
+
+也就是说：
+
+- 不再把所有运维功能平铺在一个长页面里
+- 运维者一次只处理一个主任务块
+- 主区已改成宽屏自适应，尽量利用大屏空间
+
+当前新增的地图管理接口：
+
+- `GET /admin/map-assets`
+- `PUT /admin/map-assets/{mapAssetPublicID}`
+- `GET /ops/admin/map-assets`
+- `PUT /ops/admin/map-assets/{mapAssetPublicID}`
+- `GET /ops/admin/course-sources`
+- `GET /ops/admin/course-sources/{sourcePublicID}`
+- `GET /ops/admin/course-sets/{courseSetPublicID}`
+- `POST /ops/admin/events`
+- `PUT /ops/admin/events/{eventPublicID}`
  - `content manifest`
  - `asset manifest`
 - 这些 demo 资源现在由 backend 提供，避免继续在 workbench 里保留 `example.com` 占位地址：
+  - `GET /dev/demo-assets/manifests/{demoKey}`
  - `GET /dev/demo-assets/presentations/{demoKey}`
  - `GET /dev/demo-assets/content-manifests/{demoKey}`
 - 如果 frontend 需要把页面侧调试日志直接打到 backend，优先使用：
@@ -66,6 +179,14 @@ cd D:\dev\cmr-mini\backend
  - `game.mode`
 - 这组信息用于和前端地图页实际消费结果对口排查，避免只靠口头描述“像顺序赛/像积分赛”。
 - 注意：
+  - 游客模式当前不走 `/dev/workbench` 一键链验证
+  - frontend 若要联调游客模式，请直接使用：
+    - `GET /public/experience-maps`
+    - `GET /public/experience-maps/{mapAssetPublicID}`
+    - `GET /public/events/{eventPublicID}`
+    - `GET /public/events/{eventPublicID}/play`
+    - `POST /public/events/{eventPublicID}/launch`
+  - 游客模式当前只允许默认体验活动进入，且仍然必须基于已发布 release。
  - 这块摘要由 backend 代读 manifest，只用于 workbench 调试
  - 这样做是为了避免浏览器直接读取 OSS 时受跨域影响
  - 它不替代正式客户端加载逻辑
@@ -78,6 +199,116 @@ cd D:\dev\cmr-mini\backend
  - `领秀城公园顺序赛`
  - `领秀城公园积分赛`
  - `领秀城公园多赛道挑战`
+- 当前“准备页地图预览 V1”已先接进只读查询接口：
+  - `GET /events/{eventPublicID}`
+  - `GET /events/{eventPublicID}/play`
+- 当前 preview 字段最小结构为：
+  - `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`
+- 当前实现边界：
+  - 只服务准备页只读预览
+  - 不进入正式 launch 主链
+  - demo 活动当前已自带预览元数据
+  - 非带预览元数据的活动允许返回空
+- workbench 当前已增加固定卡片：
+  - `准备页地图预览状态`
+  - 当前会直接显示：
+    - `Preview Mode`
+    - `Tile Base URL`
+    - `Zoom`
+    - `Viewport`
+    - `Selected Variant`
+    - `Preview Variant Count`
+    - `First Variant Controls`
+    - `First Variant Legs`
+  - 点击：
+    - `Event Detail`
+    - `Event Play`
+    后都会刷新这张卡
+- 当前运维入口第一期已迁移到独立运维工作台：
+  - `Import Tile Release`
+  - `Import KML Batch`
+- 两条入口分别对应：
+  - `POST /admin/ops/tile-releases/import`
+  - `POST /admin/ops/course-sets/import-kml-batch`
+- 推荐使用顺序：
+  1. 先录入瓦片版本
+  2. 再批量录入 KML 路线
+  3. 最后再继续组装 `runtime / event / release`
+- 这两条入口当前只服务运维录入第一期，不替代正式后台 UI。
+- 当前运维入口第二期已先落 backend 资源纳管接口：
+  - `GET /admin/assets`
+  - `POST /admin/assets/register-link`
+  - `POST /admin/assets/upload`
+  - `GET /admin/assets/{assetPublicID}`
+- 当前用途：
+  - 运维不再必须自己管 OSS 目录细节
+  - 允许直接上传文件，由 backend 负责：
+    - 上传到 OSS
+    - 生成正式 URL
+    - 登记资源对象
+  - 也允许直接登记已有正式外链
+- 当前已新增独立运维工作台：
+  - [http://127.0.0.1:18090/admin/ops-workbench](http://127.0.0.1:18090/admin/ops-workbench)
+- 当前入口分工：
+  - `/dev/workbench`
+    - 调试工作台
+    - 一键回归、配置摘要、前端日志、联调排查
+    - 当前只保留运维入口说明与跳转，不再承载正式资源录入动作
+  - `/admin/ops-workbench`
+    - 运维工作台
+    - 资源上传、外链登记、地图瓦片导入、KML 批量导入
+    - 活动绑定
+    - 发布中心
+- 当前运维后台鉴权也已经开始独立：
+  - 运维账号接口：
+    - `POST /ops/auth/sms/send`
+    - `POST /ops/auth/register`
+    - `POST /ops/auth/login/sms`
+    - `POST /ops/auth/refresh`
+    - `POST /ops/auth/logout`
+    - `GET /ops/me`
+  - 运维后台管理接口：
+    - `/ops/admin/*`
+  - 设计目标：
+    - 运维账号与前端玩家账号完全分离
+    - 生产环境走手机号验证码注册/登录
+    - 后续可扩角色分级、多租户
+- 当前开发环境为了录资源和调发布方便，运维后台默认免登录：
+  - `/admin/ops-workbench` 可直接进入
+  - `/ops/admin/*` 在 non-production 下可直接调用
+  - 只有主动验证运维账号链路时，才需要真的走手机号验证码登录
+- 当前运维工作台已收成 5 块：
+  - `资源总览`
+  - `地图资源管理`
+  - `资源录入`
+  - `赛道集管理`
+  - `活动绑定`
+  - `发布中心`
+- 当前“地图资源管理”第一刀的最小目标是：
+  1. 读取地点列表
+  2. 新建地点
+  3. 读取地点详情
+  4. 新建地图资源
+  5. 读取地图详情
+  6. 在同一页面查看：
+     - 当前瓦片版本
+     - 当前瓦片地址
+     - 默认活动摘要
+- 当前运维台对应入口：
+  - `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}`
+  - `POST /ops/admin/map-assets/{mapAssetPublicID}/tile-releases`

 ## 4. 活动卡片列表最小摘要

@@ -649,6 +880,48 @@ Redis 后面只在需要性能优化、限流或短期票据缓存时再接。
  - `business`
  - `variant`

+## 6.1 地图列表与默认活动
+
+当前 backend 已补最小地图体验入口：
+
+- `GET /experience-maps`
+- `GET /experience-maps/{mapAssetPublicID}`
+
+语义约定：
+
+- 地图列表按 `Place / MapAsset` 聚合
+- 默认活动关系来自：
+  - `events.is_default_experience`
+  - `events.show_in_event_list`
+  - 当前已发布 `release` 绑定到的 `runtime.mapAsset`
+- `Bootstrap Demo` 后：
+  - `evt_demo_001` 为默认体验活动
+  - `evt_demo_score_o_001`
+  - `evt_demo_variant_manual_001`
+    为普通活动，但仍会出现在地图关联活动里
+
+当前前端可直接消费的字段：
+
+- 地图列表：
+  - `placeId`
+  - `placeName`
+  - `mapId`
+  - `mapName`
+  - `coverUrl`
+  - `summary`
+  - `defaultExperienceCount`
+  - `defaultExperienceEventIds`
+- 地图详情：
+  - `placeId`
+  - `placeName`
+  - `mapId`
+  - `mapName`
+  - `coverUrl`
+  - `summary`
+  - `tileBaseUrl`
+  - `tileMetaUrl`
+  - `defaultExperiences[]`
+
 ## 7. 当前后续开发建议

 文档整理完之后，后面建议按这个顺序继续：
--- a/backend/docs/接口清单.md
+++ b/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`

--- a/backend/docs/数据模型.md
+++ b/backend/docs/数据模型.md
@@ -1,8 +1,8 @@
 # 数据模型
-> 文档版本：v1.4
-> 最后更新：2026-04-03 22:34:08
+> 文档版本：v1.6
+> 最后更新：2026-04-07 16:29:08

-当前 migration 共 11 版。
+当前 migration 共 15 版。

 ## 1. 迁移清单

@@ -17,6 +17,20 @@
 - [0009_event_ops_phase2.sql](D:/dev/cmr-mini/backend/migrations/0009_event_ops_phase2.sql)
 - [0010_event_default_bindings.sql](D:/dev/cmr-mini/backend/migrations/0010_event_default_bindings.sql)
 - [0011_card_summary.sql](D:/dev/cmr-mini/backend/migrations/0011_card_summary.sql)
+- [0012_managed_assets.sql](D:/dev/cmr-mini/backend/migrations/0012_managed_assets.sql)
+- [0013_ops_console.sql](D:/dev/cmr-mini/backend/migrations/0013_ops_console.sql)
+- [0014_map_experience.sql](D:/dev/cmr-mini/backend/migrations/0014_map_experience.sql)
+- [0015_guest_identity.sql](D:/dev/cmr-mini/backend/migrations/0015_guest_identity.sql)
+
+## 2. 当前地图体验入口相关字段
+
+- `events.is_default_experience`
+- `events.show_in_event_list`
+
+当前用途：
+
+- 支撑地图列表下的默认体验活动
+- 统一活动卡片、地图详情和默认体验入口语义

 ## 2. 表分组

@@ -50,6 +64,7 @@
 - `mobile`
 - `wechat_mini_openid`
 - `wechat_unionid`
+- `guest`

 ### 2.3 业务对象与配置发布

--- a/backend/docs/资源对象与目录方案.md
+++ b/backend/docs/资源对象与目录方案.md
@@ -1,6 +1,6 @@
 # 资源对象与目录方案
-> 文档版本：v1.0
-> 最后更新：2026-04-02 08:28:05
+> 文档版本：v1.3
+> 最后更新：2026-04-07 13:13:19


 本文档用于把“地图复用、KML 复用、内容资源复用、配置发布”统一收成一套后端可执行方案。
@@ -13,6 +13,20 @@
 - 让 `release` 能稳定追溯当时到底用了哪一份地图、哪一份 KML、哪一套资源包
 - 让同一套资源对象既能服务小程序，也能服务未来 APP

+当前补充约束：
+
+- 正式资源目录只认 `OSS / CDN`
+- 本地 `tmp/` 仅作为临时收件箱，不参与正式发布源
+- backend 当前已开始提供运维入口第一期：
+  - `POST /admin/ops/tile-releases/import`
+  - `POST /admin/ops/course-sets/import-kml-batch`
+- backend 当前也已开始提供运维入口第二期：
+  - `POST /admin/assets/upload`
+  - `POST /admin/assets/register-link`
+  - `GET /admin/assets`
+  - `GET /admin/assets/{assetPublicID}`
+- 当前目标是把“上传文件”和“登记外链”统一收口到同一套资源模型，不要求运维自己关心底层存储实现。
+
 ---

 ## 1. 设计结论
@@ -379,6 +393,10 @@ build / publish 时，Go 中间层应做装配：

 ```text
 gotomars/maps/{mapCode}/{version}/...
+gotomars/kml/{placeCode}/{version}/route01.kml
+gotomars/kml/{placeCode}/{version}/route02.kml
+gotomars/kml/{placeCode}/{version}/route03.kml
+gotomars/kml/{placeCode}/{version}/route04.kml
 gotomars/playfields/{playfieldCode}/{version}/...
 gotomars/resource-packs/{packCode}/{version}/...
 gotomars/game-modes/{modeCode}/{version}/mode.json
@@ -394,6 +412,16 @@ gotomars/event-releases/{eventPublicID}/{releasePublicID}/asset-index.json
 - 同一个 map / KML 修复时不会污染所有旧 release
 - APP 与小程序可共用相同资源版本，不必重复发两套发布目录

+补充约束：
+
+- 正式资源目录只认 `OSS / CDN`，不认仓库本地目录
+- `tmp/` 只作为临时收件箱，不作为任何正式发布源
+- 当前 manual 多赛道 demo 已切到：
+  - `gotomars/kml/lxcb-001/2026-04-07/route01.kml`
+  - `gotomars/kml/lxcb-001/2026-04-07/route02.kml`
+  - `gotomars/kml/lxcb-001/2026-04-07/route03.kml`
+  - `gotomars/kml/lxcb-001/2026-04-07/route04.kml`
+
 ---

 ## 8. 数据库建模建议