完善活动运营域与联调标准化
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# 后台管理最小方案
|
||||
> 文档版本：v1.0
|
||||
> 最后更新：2026-04-02 09:01:17
|
||||
> 文档版本：v1.1
|
||||
> 最后更新：2026-04-03 11:02:42
|
||||
|
||||
## 1. 目标
|
||||
|
||||
@@ -132,6 +132,8 @@
|
||||
- 当前选用资源包版本
|
||||
- 当前玩法模式
|
||||
- 少量覆盖项
|
||||
- 展示定义（`EventPresentation`）
|
||||
- 内容包（`ContentBundle`）
|
||||
|
||||
第一版只开放少量覆盖项：
|
||||
|
||||
@@ -160,6 +162,7 @@
|
||||
- build 状态
|
||||
- release 列表
|
||||
- 当前生效 release
|
||||
- 当前绑定的 `presentation / bundle / runtime`
|
||||
- 发布人
|
||||
- 发布时间
|
||||
|
||||
@@ -169,6 +172,7 @@
|
||||
- 查看 build 产物
|
||||
- 发布 build
|
||||
- 回滚当前 release
|
||||
- 查看 release 当前绑定的 `presentation / bundle / runtime`
|
||||
|
||||
## 4. 后台第一版页面建议
|
||||
|
||||
@@ -183,6 +187,14 @@
|
||||
|
||||
这 6 页够把“资源录入 -> Event 组装 -> 发布 -> launch”跑通。
|
||||
|
||||
补充：
|
||||
|
||||
- 当前第二阶段已经把 `EventPresentation` 和 `ContentBundle` 收成正式最小对象
|
||||
- `EventRelease` 现在允许同时绑定：
|
||||
- `presentation`
|
||||
- `content bundle`
|
||||
- `runtime binding`
|
||||
|
||||
## 5. 对象模型建议
|
||||
|
||||
后台第一版建议围绕这些对象展开：
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 开发说明
|
||||
> 文档版本：v1.1
|
||||
> 最后更新：2026-04-02 09:35:44
|
||||
> 文档版本：v1.12
|
||||
> 最后更新：2026-04-03 13:04:32
|
||||
|
||||
|
||||
## 1. 环境变量
|
||||
@@ -29,7 +29,7 @@
|
||||
|
||||
```powershell
|
||||
cd D:\dev\cmr-mini\backend
|
||||
go run .\cmd\api
|
||||
.\start-backend.ps1
|
||||
```
|
||||
|
||||
如果你想固定跑开发工作台常用端口 `18090`，直接执行：
|
||||
@@ -55,6 +55,55 @@ cd D:\dev\cmr-mini\backend
|
||||
|
||||
- 用户主链：`bootstrap -> auth -> entry/home -> event play/launch -> session -> result`
|
||||
- 后台运营链：`maps/playfields/resource-packs -> admin event source -> build -> publish -> rollback`
|
||||
- 第一阶段生产骨架联调台：`places -> map-assets -> tile-releases -> course-sources -> course-sets -> course-variants -> runtime-bindings`
|
||||
- 第三刀最小接线验证：`runtimeBinding -> release -> launch.runtime`
|
||||
- 第四刀发布闭环验证：`runtimeBinding -> publish(runtimeBindingId) -> release -> launch.runtime`
|
||||
- 活动运营域第二阶段验证：`presentation -> content bundle -> publish(presentationId, contentBundleId, runtimeBindingId) -> release`
|
||||
- 活动运营域第二阶段第二刀验证：`event detail / play / launch -> presentation + content bundle 摘要`
|
||||
- 活动运营域第二阶段第三刀验证：`release 摘要闭环 + content bundle import`
|
||||
- 活动运营域第二阶段第四刀验证：`presentation import -> event 默认 active 绑定 -> publish 空参继承`
|
||||
- workbench 一键验证增强：`一键默认绑定发布` 与 `一键补齐 Runtime 并发布`
|
||||
- `/dev/bootstrap-demo` 现在也会回填最小生产骨架：`place / map asset / tile release / course source / course set / course variant / runtime binding`
|
||||
|
||||
### 2.1 当前推荐验证方式
|
||||
|
||||
如果目标是验证“从测试数据准备到 release 继承是否完整”，优先使用 workbench 的一键流，而不是手工逐个点按钮。
|
||||
|
||||
当前推荐顺序：
|
||||
|
||||
1. `Bootstrap Demo`
|
||||
2. `一键补齐 Runtime 并发布`
|
||||
|
||||
当前这条一键链会自动完成：
|
||||
|
||||
- demo event / source / build / release 准备
|
||||
- presentation 导入
|
||||
- content bundle 导入
|
||||
- event 默认 active 绑定保存
|
||||
- 最小生产骨架准备：
|
||||
- `place`
|
||||
- `map asset`
|
||||
- `tile release`
|
||||
- `course source`
|
||||
- `course set`
|
||||
- `course variant`
|
||||
- `runtime binding`
|
||||
- publish
|
||||
- release 回读校验
|
||||
|
||||
当前日志能力：
|
||||
|
||||
- 每一步都会写到“响应日志”
|
||||
- 失败时会直接输出：
|
||||
- 错误消息
|
||||
- stack
|
||||
- 最后一次 curl
|
||||
- 成功时“预期结果”面板会直接给出：
|
||||
- `Release ID`
|
||||
- `Presentation`
|
||||
- `Content Bundle`
|
||||
- `Runtime Binding`
|
||||
- `判定`
|
||||
|
||||
## 3. 当前开发约定
|
||||
|
||||
@@ -134,6 +183,7 @@ Redis 后面只在需要性能优化、限流或短期票据缓存时再接。
|
||||
- 入口解析
|
||||
- 首页聚合
|
||||
- event play
|
||||
- 第一阶段生产骨架对象
|
||||
- 配置导入、preview build、publish build
|
||||
- launch
|
||||
- session start / finish
|
||||
@@ -144,6 +194,11 @@ Redis 后面只在需要性能优化、限流或短期票据缓存时再接。
|
||||
|
||||
- `publish build` 现在会真实上传 `manifest.json` 和 `asset-index.json` 到 OSS
|
||||
- 如果上传失败，接口会直接报错，不再出现“数据库里已有 release，但 OSS 上没有对象”的假成功
|
||||
- `Save Event Defaults` 会把当前 event 的默认 active 绑定写入：
|
||||
- `currentPresentationId`
|
||||
- `currentContentBundleId`
|
||||
- `currentRuntimeBindingId`
|
||||
- 之后 `Publish Build` 如果不显式填写这三项，会优先继承 event 默认 active 绑定
|
||||
|
||||
并且支持：
|
||||
|
||||
@@ -152,6 +207,29 @@ Redis 后面只在需要性能优化、限流或短期票据缓存时再接。
|
||||
- curl 导出
|
||||
- request history
|
||||
|
||||
当前第一阶段生产骨架联调台只做：
|
||||
|
||||
- `list`
|
||||
- `create`
|
||||
- `detail`
|
||||
- `binding`
|
||||
|
||||
明确不做：
|
||||
|
||||
- 正式后台 UI
|
||||
- `edit`
|
||||
- `delete`
|
||||
- `batch`
|
||||
- 审核流
|
||||
|
||||
活动运营域第二阶段当前也只做最小动作：
|
||||
|
||||
- `list`
|
||||
- `create`
|
||||
- `detail`
|
||||
- `publish 绑定`
|
||||
- `import`
|
||||
|
||||
## 6. 当前推荐联调顺序
|
||||
|
||||
### 场景一：小程序快速进入
|
||||
@@ -190,6 +268,164 @@ Redis 后面只在需要性能优化、限流或短期票据缓存时再接。
|
||||
5. `events/{id}`
|
||||
6. `events/{id}/launch`
|
||||
|
||||
### 场景五：第一阶段生产骨架最小闭环
|
||||
|
||||
在 `/dev/workbench` 的 `后台运营` 模式中，按下面顺序操作：
|
||||
|
||||
1. `List Places` 或 `Create Place`
|
||||
2. 在该 `Place` 下 `Create Map Asset`
|
||||
3. 在该 `MapAsset` 下 `Create Tile Release`
|
||||
4. `Create Course Source`
|
||||
5. 在该 `MapAsset` 下 `Create Course Set`
|
||||
6. 在该 `CourseSet` 下 `Create Variant`
|
||||
7. `Create Runtime Binding`
|
||||
|
||||
成功后应能拿到这些 ID：
|
||||
|
||||
- `placeId`
|
||||
- `mapAssetId`
|
||||
- `tileReleaseId`
|
||||
- `courseSourceId`
|
||||
- `courseSetId`
|
||||
- `courseVariantId`
|
||||
- `runtimeBindingId`
|
||||
|
||||
建议第一次联调时用这组最小规则：
|
||||
|
||||
- `Place` 先建 1 个
|
||||
- 每个 `Place` 先只建 1 个 `MapAsset`
|
||||
- 每个 `MapAsset` 先只建 1 个 `TileRelease`
|
||||
- 每个 `CourseSet` 先只建 1 个默认 `CourseVariant`
|
||||
- `RuntimeBinding` 先只绑定当前正在验证的 `Event`
|
||||
|
||||
这条链当前只验证对象关系闭环，不验证：
|
||||
|
||||
- 发布链切换
|
||||
- `launch` 返回运行对象字段
|
||||
- `EventPresentation`
|
||||
- `ContentBundle`
|
||||
|
||||
### 场景六：第三刀最小接线验证
|
||||
|
||||
在 `/dev/workbench` 的 `后台运营` 模式中，先完成“场景五”，再按下面顺序操作：
|
||||
|
||||
1. `Get Pipeline`
|
||||
2. 确认当前 `Release ID`
|
||||
3. 填或复用 `Runtime Binding ID`
|
||||
4. `Bind Runtime`
|
||||
5. `Get Release`
|
||||
6. 切回 `前台联调`
|
||||
7. 对同一个 `event` 执行 `Launch`
|
||||
|
||||
### 场景七：活动运营域第二阶段最小闭环
|
||||
|
||||
在 `/dev/workbench` 的 `后台运营` 模式中，按下面顺序操作：
|
||||
|
||||
1. `Get Event`
|
||||
2. `Create Presentation`
|
||||
3. `Create Bundle`
|
||||
4. `Assemble Source`
|
||||
5. `Build Source`
|
||||
6. 在发布区填：
|
||||
- `Runtime Binding ID`
|
||||
- `Presentation ID`
|
||||
- `Content Bundle ID`
|
||||
7. `Publish Build`
|
||||
8. `Get Release`
|
||||
|
||||
成功后应能在 release 返回中看到：
|
||||
|
||||
- `runtime`
|
||||
- `presentation`
|
||||
- `contentBundle`
|
||||
|
||||
并且这 3 类绑定当前都已固化到 `event_release`。
|
||||
|
||||
成功后应能看到：
|
||||
|
||||
- `GET /admin/releases/{releasePublicID}` 返回 `runtime`
|
||||
- `POST /events/{eventPublicID}/launch` 返回 `launch.runtime`
|
||||
|
||||
当前阶段的约束是：
|
||||
|
||||
- 只新增 `runtime` 字段块
|
||||
- 不改旧的：
|
||||
- `resolvedRelease`
|
||||
- `business`
|
||||
- `variant`
|
||||
- release 如果没挂 `runtimeBindingId`，则 `launch.runtime` 为空
|
||||
|
||||
### 场景八：活动运营域第二阶段第三刀验证
|
||||
|
||||
在 `/dev/workbench` 的 `后台运营` 模式中，先完成“场景七”，再按下面顺序操作：
|
||||
|
||||
1. `Create Presentation` 或直接复用现有 `Presentation ID`
|
||||
2. `Import Bundle`
|
||||
3. `Get Bundle`
|
||||
4. `Get Pipeline`
|
||||
5. `Publish Build`
|
||||
6. `Get Release`
|
||||
7. 切回 `前台联调`
|
||||
8. `Event Detail`
|
||||
9. `Event Play`
|
||||
10. `Launch`
|
||||
|
||||
成功后应能同时看到这三组摘要：
|
||||
|
||||
- `release.presentation.templateKey / version`
|
||||
- `release.contentBundle.bundleType / version`
|
||||
- `release.runtime.placeId / mapId / tileReleaseId / courseVariantId`
|
||||
|
||||
同时客户端消费侧应保持一致：
|
||||
|
||||
- `GET /events/{eventPublicID}`
|
||||
- `GET /events/{eventPublicID}/play`
|
||||
- `POST /events/{eventPublicID}/launch`
|
||||
|
||||
当前 Content Bundle Import 只做统一导入入口，不做复杂资源平台：
|
||||
|
||||
- 输入：
|
||||
- `title`
|
||||
- `bundleType`
|
||||
- `sourceType`
|
||||
- `manifestUrl`
|
||||
- `version`
|
||||
- `assetManifest`
|
||||
- 输出：
|
||||
- `bundleId`
|
||||
- `bundleType`
|
||||
- `version`
|
||||
- `assetManifest`
|
||||
- `status`
|
||||
|
||||
### 场景七：第四刀发布闭环验证
|
||||
|
||||
在 `/dev/workbench` 的 `后台运营` 模式中，先完成“场景五”，再按下面顺序操作：
|
||||
|
||||
1. `Create Runtime Binding`
|
||||
2. `Get Pipeline`
|
||||
3. 确认 `Build ID`
|
||||
4. 在发布区填 `Runtime Binding ID`
|
||||
5. `Publish Build`
|
||||
6. `Get Release`
|
||||
7. 切回 `前台联调`
|
||||
8. 对同一个 `event` 执行 `Launch`
|
||||
|
||||
成功后应能看到：
|
||||
|
||||
- `POST /admin/builds/{buildID}/publish` 返回带 `runtime`
|
||||
- `GET /admin/releases/{releasePublicID}` 返回同一条 `runtime`
|
||||
- `POST /events/{eventPublicID}/launch` 返回同一条 `launch.runtime`
|
||||
|
||||
当前第四刀的兼容要求是：
|
||||
|
||||
- 旧的“先 `publish`，再 `bind runtime`”路径继续可用
|
||||
- 新的“`publish` 时直接传 `runtimeBindingId`”优先推荐
|
||||
- 不修改旧的：
|
||||
- `resolvedRelease`
|
||||
- `business`
|
||||
- `variant`
|
||||
|
||||
## 7. 当前后续开发建议
|
||||
|
||||
文档整理完之后，后面建议按这个顺序继续：
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# API 清单
|
||||
> 文档版本：v1.1
|
||||
> 最后更新：2026-04-02 11:05:32
|
||||
> 文档版本：v1.8
|
||||
> 最后更新：2026-04-03 12:36:15
|
||||
|
||||
|
||||
本文档只记录当前 backend 已实现接口，不写未来规划接口。
|
||||
@@ -140,6 +140,18 @@
|
||||
- `event`
|
||||
- `release`
|
||||
- `resolvedRelease`
|
||||
- `runtime`
|
||||
- `currentPresentation`
|
||||
- `currentContentBundle`
|
||||
|
||||
当前摘要字段最少包括：
|
||||
|
||||
- `currentPresentation.presentationId`
|
||||
- `currentPresentation.templateKey`
|
||||
- `currentPresentation.version`
|
||||
- `currentContentBundle.contentBundleId`
|
||||
- `currentContentBundle.bundleType`
|
||||
- `currentContentBundle.version`
|
||||
|
||||
### `GET /events/{eventPublicID}/play`
|
||||
|
||||
@@ -156,6 +168,9 @@
|
||||
- `event`
|
||||
- `release`
|
||||
- `resolvedRelease`
|
||||
- `runtime`
|
||||
- `currentPresentation`
|
||||
- `currentContentBundle`
|
||||
- `play.assignmentMode`
|
||||
- `play.courseVariants`
|
||||
- `play.canLaunch`
|
||||
@@ -164,6 +179,15 @@
|
||||
- `play.ongoingSession`
|
||||
- `play.recentSession`
|
||||
|
||||
当前摘要字段最少包括：
|
||||
|
||||
- `currentPresentation.presentationId`
|
||||
- `currentPresentation.templateKey`
|
||||
- `currentPresentation.version`
|
||||
- `currentContentBundle.contentBundleId`
|
||||
- `currentContentBundle.bundleType`
|
||||
- `currentContentBundle.version`
|
||||
|
||||
### `POST /events/{eventPublicID}/launch`
|
||||
|
||||
鉴权：
|
||||
@@ -192,10 +216,33 @@
|
||||
- `launch.source`
|
||||
- `launch.resolvedRelease`
|
||||
- `launch.variant`
|
||||
- `launch.runtime`
|
||||
- `launch.presentation`
|
||||
- `launch.contentBundle`
|
||||
- `launch.config`
|
||||
- `launch.business.sessionId`
|
||||
- `launch.business.sessionToken`
|
||||
|
||||
当前活动运营摘要最少包括：
|
||||
|
||||
- `launch.presentation.presentationId`
|
||||
- `launch.presentation.templateKey`
|
||||
- `launch.presentation.version`
|
||||
- `launch.contentBundle.contentBundleId`
|
||||
- `launch.contentBundle.bundleType`
|
||||
- `launch.contentBundle.version`
|
||||
|
||||
`launch.runtime` 当前为兼容新增字段，最少会带：
|
||||
|
||||
- `runtimeBindingId`
|
||||
- `placeId`
|
||||
- `mapId`
|
||||
- `tileReleaseId`
|
||||
- `courseSetId`
|
||||
- `courseVariantId`
|
||||
|
||||
如当前 release 尚未挂接 runtime binding，则该字段为空。
|
||||
|
||||
### `GET /events/{eventPublicID}/config-sources`
|
||||
|
||||
鉴权：
|
||||
@@ -466,12 +513,16 @@
|
||||
请求体重点：
|
||||
|
||||
- `buildId`
|
||||
- `runtimeBindingId` 可选
|
||||
- `presentationId` 可选
|
||||
- `contentBundleId` 可选
|
||||
|
||||
返回重点：
|
||||
|
||||
- `release.releaseId`
|
||||
- `release.manifestUrl`
|
||||
- `release.configLabel`
|
||||
- `runtime.runtimeBindingId` 可选
|
||||
|
||||
## 9. Admin 资源对象
|
||||
|
||||
@@ -738,6 +789,145 @@
|
||||
- `overrides`
|
||||
- `notes`
|
||||
|
||||
### `GET /admin/events/{eventPublicID}/presentations`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看某个 event 下的展示定义列表
|
||||
|
||||
### `POST /admin/events/{eventPublicID}/presentations`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 为 event 创建一条最小 presentation 定义
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `code`
|
||||
- `name`
|
||||
- `presentationType`
|
||||
- `schema`
|
||||
|
||||
### `POST /admin/events/{eventPublicID}/presentations/import`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 通过统一导入入口创建展示定义
|
||||
- 第一阶段只记录：
|
||||
- `templateKey`
|
||||
- `sourceType`
|
||||
- `schemaUrl`
|
||||
- `version`
|
||||
- `title`
|
||||
|
||||
核心参数：
|
||||
|
||||
- `title`
|
||||
- `templateKey`
|
||||
- `sourceType`
|
||||
- `schemaUrl`
|
||||
- `version`
|
||||
|
||||
### `GET /admin/presentations/{presentationPublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看单条 presentation 明细
|
||||
|
||||
### `GET /admin/events/{eventPublicID}/content-bundles`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看某个 event 下的内容包列表
|
||||
|
||||
### `POST /admin/events/{eventPublicID}/content-bundles`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 为 event 创建一条最小 content bundle
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `code`
|
||||
- `name`
|
||||
- `entryUrl`
|
||||
- `assetRootUrl`
|
||||
- `metadata`
|
||||
|
||||
### `POST /admin/events/{eventPublicID}/content-bundles/import`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 通过统一导入入口为 event 创建内容包
|
||||
- 先记录 `bundleType / sourceType / manifestUrl / version / assetManifest`
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `title`
|
||||
- `bundleType`
|
||||
- `sourceType`
|
||||
- `manifestUrl`
|
||||
- `version`
|
||||
- `assetManifest`
|
||||
|
||||
### `GET /admin/content-bundles/{contentBundlePublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看单条 content bundle 明细
|
||||
|
||||
### `POST /admin/events/{eventPublicID}/defaults`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 固化 event 当前默认 active 绑定
|
||||
- 后续 publish 在未显式传参时，优先继承：
|
||||
- `presentationId`
|
||||
- `contentBundleId`
|
||||
- `runtimeBindingId`
|
||||
|
||||
核心参数：
|
||||
|
||||
- `presentationId`
|
||||
- `contentBundleId`
|
||||
- `runtimeBindingId`
|
||||
|
||||
### `GET /admin/events/{eventPublicID}/pipeline`
|
||||
|
||||
鉴权：
|
||||
@@ -782,6 +972,57 @@
|
||||
|
||||
- 将某次成功 build 发布成正式 release
|
||||
- 自动切换 event 当前 release
|
||||
- 可选在发布时直接挂接：
|
||||
- `runtimeBindingId`
|
||||
- `presentationId`
|
||||
- `contentBundleId`
|
||||
- 如果未显式传入 `runtimeBindingId / presentationId / contentBundleId`，会优先按 event 当前默认 active 绑定自动补齐
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `runtimeBindingId` 可选
|
||||
- `presentationId` 可选
|
||||
- `contentBundleId` 可选
|
||||
|
||||
### `GET /admin/releases/{releasePublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看单个 release 明细
|
||||
- 带出当前已挂接的最小 runtime / presentation / content bundle 摘要
|
||||
|
||||
当前 release 摘要最少包括：
|
||||
|
||||
- `presentation.presentationId`
|
||||
- `presentation.templateKey`
|
||||
- `presentation.version`
|
||||
- `contentBundle.contentBundleId`
|
||||
- `contentBundle.bundleType`
|
||||
- `contentBundle.version`
|
||||
- `runtime.runtimeBindingId`
|
||||
- `runtime.placeId`
|
||||
- `runtime.mapId`
|
||||
- `runtime.tileReleaseId`
|
||||
- `runtime.courseVariantId`
|
||||
|
||||
### `POST /admin/releases/{releasePublicID}/runtime-binding`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 将某个 `runtimeBindingId` 挂接到指定 release
|
||||
- 为后续 `launch.runtime` 提供运行对象来源
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `runtimeBindingId`
|
||||
|
||||
### `POST /admin/events/{eventPublicID}/rollback`
|
||||
|
||||
@@ -797,4 +1038,247 @@
|
||||
|
||||
- `releaseId`
|
||||
|
||||
## 10. Admin 生产骨架
|
||||
|
||||
说明：
|
||||
|
||||
- 当前是总控确认后的第一阶段生产骨架接口
|
||||
- 重点先覆盖：
|
||||
- `Place`
|
||||
- `MapAsset`
|
||||
- `TileRelease`
|
||||
- `CourseSource`
|
||||
- `CourseSet`
|
||||
- `CourseVariant`
|
||||
- `MapRuntimeBinding`
|
||||
- 这批接口不会替换现有 `events / event_releases / launch` 主链，而是增量补运行域对象
|
||||
|
||||
### `GET /admin/places`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 获取地点对象列表
|
||||
|
||||
### `POST /admin/places`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 新建地点对象
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `code`
|
||||
- `name`
|
||||
- `region`
|
||||
- `coverUrl`
|
||||
- `description`
|
||||
- `centerPoint`
|
||||
- `status`
|
||||
|
||||
### `GET /admin/places/{placePublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看地点详情
|
||||
- 同时带出该地点下的地图资产列表
|
||||
|
||||
### `POST /admin/places/{placePublicID}/map-assets`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 在某个地点下创建地图资产
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `code`
|
||||
- `name`
|
||||
- `mapType`
|
||||
- `legacyMapId`
|
||||
- `coverUrl`
|
||||
- `description`
|
||||
- `status`
|
||||
|
||||
### `GET /admin/map-assets/{mapAssetPublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看地图资产详情
|
||||
- 同时带出瓦片版本和赛道集合摘要
|
||||
|
||||
### `POST /admin/map-assets/{mapAssetPublicID}/tile-releases`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 为某个地图资产创建瓦片版本
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `legacyVersionId`
|
||||
- `versionCode`
|
||||
- `tileBaseUrl`
|
||||
- `metaUrl`
|
||||
- `publishedAssetRoot`
|
||||
- `metadata`
|
||||
- `status`
|
||||
- `setAsCurrent`
|
||||
|
||||
### `GET /admin/course-sources`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 获取赛道原始输入源列表
|
||||
|
||||
### `POST /admin/course-sources`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 新建赛道原始输入源
|
||||
- 用于承接 KML / GeoJSON 等输入
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `legacyPlayfieldId`
|
||||
- `legacyVersionId`
|
||||
- `sourceType`
|
||||
- `fileUrl`
|
||||
- `checksum`
|
||||
- `parserVersion`
|
||||
- `importStatus`
|
||||
- `metadata`
|
||||
|
||||
### `GET /admin/course-sources/{sourcePublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看单个赛道输入源详情
|
||||
|
||||
### `POST /admin/map-assets/{mapAssetPublicID}/course-sets`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 在某个地图资产下创建赛道集合
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `code`
|
||||
- `mode`
|
||||
- `name`
|
||||
- `description`
|
||||
- `status`
|
||||
|
||||
### `GET /admin/course-sets/{courseSetPublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看赛道集合详情
|
||||
- 同时带出它的 variant 列表
|
||||
|
||||
### `POST /admin/course-sets/{courseSetPublicID}/variants`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 为某个赛道集合创建具体可运行赛道方案
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `sourceId`
|
||||
- `name`
|
||||
- `routeCode`
|
||||
- `mode`
|
||||
- `controlCount`
|
||||
- `difficulty`
|
||||
- `configPatch`
|
||||
- `metadata`
|
||||
- `status`
|
||||
- `isDefault`
|
||||
|
||||
### `GET /admin/runtime-bindings`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 获取活动运行绑定列表
|
||||
|
||||
### `POST /admin/runtime-bindings`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 把活动和地点、地图资产、瓦片版本、赛道方案正式绑定起来
|
||||
|
||||
请求体重点：
|
||||
|
||||
- `eventId`
|
||||
- `placeId`
|
||||
- `mapAssetId`
|
||||
- `tileReleaseId`
|
||||
- `courseSetId`
|
||||
- `courseVariantId`
|
||||
- `status`
|
||||
- `notes`
|
||||
|
||||
### `GET /admin/runtime-bindings/{runtimeBindingPublicID}`
|
||||
|
||||
鉴权：
|
||||
|
||||
- Bearer token
|
||||
|
||||
用途：
|
||||
|
||||
- 查看单个运行绑定详情
|
||||
|
||||
|
||||
|
||||
@@ -1,9 +1,8 @@
|
||||
# 数据模型
|
||||
> 文档版本：v1.0
|
||||
> 最后更新：2026-04-02 08:28:05
|
||||
> 文档版本：v1.3
|
||||
> 最后更新：2026-04-03 12:36:15
|
||||
|
||||
|
||||
当前 migration 共 6 版。
|
||||
当前 migration 共 10 版。
|
||||
|
||||
## 1. 迁移清单
|
||||
|
||||
@@ -13,6 +12,10 @@
|
||||
- [0004_results.sql](D:/dev/cmr-mini/backend/migrations/0004_results.sql)
|
||||
- [0005_config_pipeline.sql](D:/dev/cmr-mini/backend/migrations/0005_config_pipeline.sql)
|
||||
- [0006_resource_objects.sql](D:/dev/cmr-mini/backend/migrations/0006_resource_objects.sql)
|
||||
- [0007_variant_minimal.sql](D:/dev/cmr-mini/backend/migrations/0007_variant_minimal.sql)
|
||||
- [0008_production_skeleton.sql](D:/dev/cmr-mini/backend/migrations/0008_production_skeleton.sql)
|
||||
- [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)
|
||||
|
||||
## 2. 表分组
|
||||
|
||||
@@ -114,6 +117,51 @@
|
||||
- 支撑后台第一版按“资源对象 + 版本”管理
|
||||
- 给后续 event 引用组装和发布流程提供稳定边界
|
||||
|
||||
### 2.8 第一阶段生产骨架
|
||||
|
||||
- `places`
|
||||
- `map_assets`
|
||||
- `tile_releases`
|
||||
- `course_sources`
|
||||
- `course_sets`
|
||||
- `course_variants`
|
||||
- `map_runtime_bindings`
|
||||
|
||||
职责：
|
||||
|
||||
- 把地图运行域和活动运行绑定正式落库
|
||||
- 把 KML 输入源和最终赛道方案拆开
|
||||
- 在不推翻当前 `events / event_releases / game_sessions` 主链的前提下，增量补生产骨架
|
||||
|
||||
### 2.9 活动运营域第二阶段
|
||||
|
||||
- `event_presentations`
|
||||
- `content_bundles`
|
||||
|
||||
职责：
|
||||
|
||||
- 把活动展示定义和内容包从临时 JSON 概念收成正式对象
|
||||
- 让 `event_releases` 明确绑定：
|
||||
- `presentation_id`
|
||||
- `content_bundle_id`
|
||||
- `runtime_binding_id`
|
||||
- 保持现有 `resolvedRelease / business / variant / runtime` 稳定返回不变
|
||||
|
||||
### 2.10 Event 默认 active 绑定
|
||||
|
||||
- `events.current_presentation_id`
|
||||
- `events.current_content_bundle_id`
|
||||
- `events.current_runtime_binding_id`
|
||||
|
||||
职责：
|
||||
|
||||
- 固化 event 当前默认 active：
|
||||
- `presentation`
|
||||
- `content bundle`
|
||||
- `runtime binding`
|
||||
- 支撑 publish 在未显式传入时的默认继承
|
||||
- 不改变前端当前稳定消费的 release / launch 字段语义
|
||||
|
||||
## 3. 当前最关键的关系
|
||||
|
||||
### `tenant -> entry_channel`
|
||||
@@ -160,6 +208,42 @@
|
||||
|
||||
一套内容/音频/主题资源可有多个版本。
|
||||
|
||||
### `place -> map_asset -> tile_release`
|
||||
|
||||
- `Place` 是地点上层对象
|
||||
- `MapAsset` 是地点下的一张具体地图资产
|
||||
- `TileRelease` 是某张地图的具体瓦片发布版本
|
||||
|
||||
### `course_source -> course_variant -> course_set`
|
||||
|
||||
- `CourseSource` 是原始输入源，例如 KML
|
||||
- `CourseVariant` 是最终可运行赛道方案
|
||||
- `CourseSet` 是一组方案集合
|
||||
|
||||
### `event_release -> map_runtime_binding`
|
||||
|
||||
- `event_releases.runtime_binding_id` 已预留给第一阶段生产骨架
|
||||
- 当前客户端联调仍以 `resolvedRelease` 为主
|
||||
- 第二阶段会继续把 `placeId / mapId / tileReleaseId / courseVariantId` 收到 `launch` 稳定返回中
|
||||
|
||||
### `event -> event_presentation`
|
||||
|
||||
- 一个 `event` 可有多条展示定义
|
||||
- 当前最小用途是给 `event_release` 提供明确绑定目标
|
||||
|
||||
### `event -> content_bundle`
|
||||
|
||||
- 一个 `event` 可有多条内容包
|
||||
- 当前最小用途是给 `event_release` 提供内容资源绑定目标
|
||||
|
||||
### `event_release -> presentation / content_bundle / runtime`
|
||||
|
||||
- 这是当前活动运营域第二阶段的最小闭环
|
||||
- `release` 现在可以稳定固化：
|
||||
- 展示定义
|
||||
- 内容包
|
||||
- 运行绑定
|
||||
|
||||
## 4. 当前已落库但仍应注意的边界
|
||||
|
||||
### 4.1 不要把玩法细节塞回事件主表
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 核心流程
|
||||
> 文档版本：v1.1
|
||||
> 最后更新：2026-04-02 11:03:02
|
||||
> 文档版本：v1.2
|
||||
> 最后更新：2026-04-03 11:22:50
|
||||
|
||||
|
||||
## 1. 总流程
|
||||
@@ -113,6 +113,8 @@ APP 当前主链是手机号验证码：
|
||||
- `event`
|
||||
- `release`
|
||||
- `resolvedRelease`
|
||||
- `currentPresentation`
|
||||
- `currentContentBundle`
|
||||
- `play.assignmentMode`
|
||||
- `play.courseVariants[]`
|
||||
- `play.canLaunch`
|
||||
@@ -160,6 +162,8 @@ APP 当前主链是手机号验证码：
|
||||
- `launch.source`
|
||||
- `launch.resolvedRelease`
|
||||
- `launch.variant`
|
||||
- `launch.presentation`
|
||||
- `launch.contentBundle`
|
||||
- `launch.config`
|
||||
- `launch.business.sessionId`
|
||||
- `launch.business.sessionToken`
|
||||
@@ -179,6 +183,11 @@ APP 当前主链是手机号验证码：
|
||||
- `launch.variant.id`
|
||||
- `launch.variant.assignmentMode`
|
||||
|
||||
活动运营域第二阶段第二刀新增建议消费摘要：
|
||||
|
||||
- `launch.presentation.presentationId`
|
||||
- `launch.contentBundle.contentBundleId`
|
||||
|
||||
补充说明：
|
||||
|
||||
- 如果活动声明了多赛道 variant，`launch` 会返回本局最终绑定的 `variant`
|
||||
|
||||
Reference in New Issue
Block a user