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

2026-04-07 19:05:18 +08:00
parent 1a6008449e
commit 6cd16f08dd
102 changed files with 16087 additions and 3556 deletions
--- 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. 当前后续开发建议

 文档整理完之后，后面建议按这个顺序继续：