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

2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
--- a/backend/README.md
+++ b/backend/README.md
@@ -1,12 +1,67 @@
 # Backend
-> 文档版本：v1.22
-> 最后更新：2026-04-03 18:56:46
+> 文档版本：v1.41
+> 最后更新：2026-04-07 18:15:01


 这套后端现在已经能支撑一条完整主链：

 `entry -> auth -> home/cards -> event play -> launch -> session -> result`

+当前已实现接口总数：
+
+- `116`
+
+开发环境补充说明：
+
+- `/admin/ops-workbench` 与 `/ops/admin/*` 在 `APP_ENV != production` 时默认免登录可用。
+- 即使浏览器里残留旧的玩家 token、过期 token 或非 ops token，运维链也会自动回退到 dev ops 上下文。
+- 生产环境不变，仍然必须使用正式 ops token。
+- 运维后台当前采用“左侧流程导航 + 中间单主视图 + 右侧状态/日志”结构，不再把地图、路线、活动、发布动作平铺在一个长页面里。
+- `资源总览` 先展示关键统计与当前运行时信息；地图页只保留关联活动数量和摘要，活动明细统一放到 `活动管理 / 活动编排`。
+- `地图 / 地点管理` 当前按“地图列表优先”组织：
+  - 先看地图列表
+  - 右上角只放 `添加地图 / 添加地点`
+  - 地点编辑区改成省/市两级选择
+  - 一张地图只属于一个地点，一个地点可挂多张地图
+
+新增的游客模式公开接口：
+
+- `GET /public/experience-maps`
+- `GET /public/experience-maps/{mapAssetPublicID}`
+- `GET /public/events/{eventPublicID}`
+- `GET /public/events/{eventPublicID}/play`
+- `POST /public/events/{eventPublicID}/launch`
+
+这组接口用于支撑“未登录游客只体验默认活动”的最小链路。
+
+新增的地图资源与默认体验活动接口：
+
+- `GET /experience-maps`
+- `GET /experience-maps/{mapAssetPublicID}`
+
+这组接口用于支撑“地图列表下的默认活动”最小产品化需求。
+
+新增的运维地图管理接口：
+
+- `GET /ops/admin/region-options`
+- `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}`
+
+这组接口用于把运维后台收成统一主流程：
+
+- 地图管理：列表 / 新增 / 编辑 / 详情 / 关联活动
+- KML / 赛道管理：围绕当前地图查看赛道集和默认路线
+- 活动管理：列表 / 新增 / 修改 / 详情 / 默认绑定 / 发布
+- 运维后台 UI 当前也已按“左侧导航 + 单主视图 + 右侧常驻状态栏”收口，不再把所有功能平铺在一个长页面里
+- 主区当前已改成宽屏自适应，不再固定窄宽度浪费屏幕空间
+
 并且已经按“配置驱动游戏”收口：

 - 业务对象是 `event`
@@ -29,6 +84,16 @@
    - `presentation`
    - `content bundle`
    时，玩家才允许正式进入
+- 游客模式当前只允许进入：
+  - `is_default_experience = true` 的活动
+  - 且必须基于当前已发布 release
+- 游客模式当前不开放：
+  - `/me/entry-home`
+  - `/me/results`
+  - 用户历史成绩与报名态
+- 游客模式 `launch` 会复用正式 session 模型，但返回：
+  - `launch.source = public-default-experience`
+  - `launch.business.isGuest = true`

 当前 workbench 里新增的“当前 Launch 实际配置摘要”仅用于调试：

@@ -54,20 +119,84 @@
 当前 demo 真实输入第一刀也已经接入：

 - workbench 的玩法切换会自动填入 backend 内置的：
+  - `game manifest`
  - `presentation schema`
  - `content manifest`
 - 这些 demo 资源通过 backend 提供的 dev 路由读取：
+  - `GET /dev/demo-assets/manifests/{demoKey}`
  - `GET /dev/demo-assets/presentations/{demoKey}`
  - `GET /dev/demo-assets/content-manifests/{demoKey}`

 当前 workbench 的 `Bootstrap` 语义也已经拆开：

 - `Bootstrap Demo（只准备数据）`
-  - 只准备 demo 测试数据，不额外重新发布当前玩法
+  - 只准备 demo 测试数据和基础已发布态，不额外重新发布当前玩法
 - `Bootstrap + 发布当前玩法`
  - 先准备 demo，再对当前选中的玩法执行一遍“发布活动配置（自动补 Runtime）”
 - 这两条路由只服务联调，不进入正式客户端发布链
+- 当前三条标准 demo 在 `Bootstrap Demo（只准备数据）` 后都会直接具备：
+  - 当前 release
+  - runtime
+  - presentation
+  - content bundle
+- 也就是说，frontend 当前从首页选顺序赛、积分赛、多赛道时，已经可以直接走“当前已发布 release”语义联调入口、详情和 `canLaunch`
 - 当前联调样例文案也已从 `Demo ...` 收口为中文活动样例，便于前端和总控直接对口排查
+- 当前 manual 多赛道 demo 也已切到 4 条正式 OSS KML：
+  - `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`
+- 资源目录约束同步明确：
+  - 正式资源目录只认 `OSS / CDN`
+  - 本地 `tmp/` 仅作为临时收件箱，不参与正式发布源
+- 当前运维入口第一期已开始落地，先开放两条最小录入链：
+  - `POST /admin/ops/tile-releases/import`
+  - `POST /admin/ops/course-sets/import-kml-batch`
+- 当前目标是先把：
+  - 地图瓦片版本录入
+  - KML 批量录入并组装为 `course set / variants`
+  收成可重复执行的运维入口，而不是继续依赖手工脚本或改代码上传 OSS
+- 当前运维入口第二期已起步，开始支持统一资源纳管：
+  - `GET /admin/assets`
+  - `POST /admin/assets/register-link`
+  - `POST /admin/assets/upload`
+  - `GET /admin/assets/{assetPublicID}`
+- 当前边界：
+  - 允许“上传文件”与“登记外链”两种录入模式
+  - backend 负责 OSS 存储和资源对象登记
+  - 运维后台当前开始使用独立鉴权链：
+    - `/ops/auth/*`
+    - `/ops/admin/*`
+  - 设计目标：
+    - 运维账号与前端玩家账号完全分离
+    - 生产环境走手机号验证码注册/登录
+    - 后续可扩多租户与角色分级
+  - 已新增独立运维入口：
+    - `GET /admin/ops-workbench`
+  - 当前开始把“调试后台”和“运维后台”拆开：
+    - `/dev/workbench` 继续只做联调、回归、日志与摘要
+    - `/admin/ops-workbench` 只做资源录入、OSS 纳管、地图/KML 导入
+  - 当前开发环境为了录资源和调发布方便，运维后台默认免登录放行：
+    - 可直接打开 `/admin/ops-workbench`
+    - 可直接调用 `/ops/admin/*`
+    - 只有主动验证运维账号链路时，才需要使用 `/ops/auth/*`
+  - `Import Tile Release / Import KML Batch` 当前已从调试工作台主操作区迁到：
+    - `/admin/ops-workbench`
+  - `/dev/workbench` 当前只保留运维后台入口说明与跳转，不再承载正式资源录入操作
+  - `/admin/ops-workbench` 当前已收成 5 块结构：
+    - 资源总览
+    - 地图资源管理
+    - 资源录入
+    - 赛道集管理
+    - 活动绑定
+    - 发布中心
+  - 当前地图资源管理第一刀已接进运维后台：
+    - 读取地点列表
+    - 新建地点
+    - 读取地点详情
+    - 新建地图资源
+    - 读取地图详情
+    - 查看当前瓦片版本与默认活动摘要

 当前活动卡片列表最小产品化第一刀也已经进入 backend：

@@ -96,6 +225,29 @@
 - `isDefaultExperience` 当前由卡片显式字段控制
 - `timeWindow / ctaText` 当前先按后端派生规则提供，允许后续继续演进

+当前“准备页地图预览 V1”也已开始接入，但仍保持只读增强项边界：
+
+- 当前只把预览字段挂在：
+  - `GET /events/{eventPublicID}`
+  - `GET /events/{eventPublicID}/play`
+- 当前新增字段为：
+  - `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 关键字段
+
 ## 文档导航

 - [文档索引](D:/dev/cmr-mini/backend/docs/README.md)