完善活动运营域与联调标准化

2026-04-03 13:11:41 +08:00
parent 0e28f70bad
commit 129ea935db
56 changed files with 11004 additions and 196 deletions
--- a/backend/docs/开发说明.md
+++ b/backend/docs/开发说明.md
@@ -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. 当前后续开发建议

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