zhangyan/cmr-mini

Fork 0

Files

zhangyan 114c524044 完善一键回归与真实输入准备

2026-04-03 14:18:11 +08:00

22 KiB

Raw Blame History

T2B 协作清单

文档版本：v1.11 最后更新：2026-04-03 14:16:17

说明：

本文件由总控维护，写给后端线程
目标是把“后台生产闭环”第一阶段需要落地的东西讲清楚
只写当前阶段实施说明，不写长讨论稿
正式架构文档以后台生产闭环架构草案为准

0. 当前阶段状态与下一步

backend 当前已完成：

生产骨架对象落库与 /dev/workbench 最小联调台
MapRuntimeBinding -> EventRelease -> launch.runtime 主链接通
EventPresentation / ContentBundle / EventRelease 第一阶段接通
Event 默认 active 三元组固化：
- currentPresentationId
- currentContentBundleId
- currentRuntimeBindingId
publish 默认继承当前 active 三元组
Bootstrap Demo 与 一键补齐 Runtime 并发布 已可从空白状态跑完整测试链
一键标准回归 与 回归结果汇总 已接入标准联调入口
workbench 日志已补齐：
- 分步日志
- 真实错误
- stack
- 最后一次 curl
- 预期判定

当前主线不再是继续补对象，而是进入：

联调标准化阶段

本阶段 backend 的核心任务只有 3 件事：

固化“一键测试”链路，确保从空白环境可重复跑通
固化详细日志口径，失败时明确定位在哪一步
固化稳定测试数据，并逐步支持更接近生产的真实输入

当前认为“联调标准化第一版”已经基本到位，backend 下一步应进入：

真实输入替换第一刀

优先顺序建议：

先替换真实 KML / 赛道文件
再替换真实地图资源 URL
再替换真实内容 manifest / presentation schema
最后再补真实活动文案样例

原则：

仍走同一条一键回归链
不重新设计联调流程
只是把 demo 输入逐步换成更接近生产的真实输入

当前进一步明确 backend 的执行口径如下：

0.1 一键测试链路

请继续以这条链作为唯一标准联调入口维护：

Bootstrap Demo
-> 一键补齐 Runtime 并发布
-> launch / play / result / history 回归

要求：

从空白环境直接可跑
不依赖手工预铺 6~8 个对象
同一条链可反复执行
失败时能明确知道卡在哪一跳

0.2 详细日志口径

workbench 和相关 backend 调试输出，当前应至少统一包含：

当前步骤名
核心输入参数
真实错误信息
stack
最后一次 curl
预期判定

不要只输出“失败了”，要能回答：

是哪一步失败
为什么失败
用什么请求复现

0.3 稳定测试数据

当前 demo 数据不要继续散落手工维护，统一以 backend 准备的一键测试数据为准。

后续逐步支持以下更接近生产的真实输入：

地图资源 URL
KML / 赛道文件
内容 manifest
presentation schema
活动文案样例

0.4 当前不建议做

联调标准化阶段不要继续发散去做：

新对象扩张
新管理面板
更复杂 workbench UI
复杂后台运营功能
与当前联调闭环无关的页面能力

当前不建议 backend 继续发散去做：

更多新对象
更多 workbench 管理按钮
更复杂后台 UI
过早扩大奖励、社交、审核流

1. 本次目标

本次不是让 backend 一次性做完整后台，而是先搭出最小生产骨架，让下面这条链能真正闭环：

地图输入
-> 瓦片版本
-> KML 导入
-> 赛道 variant
-> 活动绑定
-> release
-> launch
-> 客户端消费

当前重点是：

先把对象模型定下来
先让地图、KML、活动三条输入链有正式落点
先让客户端只认发布产物

补充确认：

本次接受 backend 采用增量演进方式推进
不要求一次性推翻当前已稳定联调的：
- Event
- EventRelease
- Session 主链

当前补充确认：

生产骨架第一阶段与活动运营域第二阶段第四刀已经完成
backend 当前下一步应切到“联调标准化”，而不是继续新增对象层级

2. 本次范围

2.1 本次必须做

定义并落库以下核心对象：
- Place
- MapAsset
- TileRelease
- CourseSet
- CourseVariant
- CourseSource
- Event
- EventPresentation
- ContentBundle
- MapRuntimeBinding
- EventRelease
先让 KML 不再只是文件，而能转成 CourseVariant
先让活动不再只是页面概念，而能正式绑定：
- 展示定义
- 内容包
- 运行绑定
- 发布版本
第一阶段优先落以下对象：
- Place
- MapAsset
- TileRelease
- CourseSource
- CourseSet
- CourseVariant
- MapRuntimeBinding
第一阶段允许暂缓完整落库：
- EventPresentation
- ContentBundle 但对象语义必须先在架构上定清楚

2.2 本次先不做

奖励系统
社交系统
复杂审核流
完整后台 UI
大而全的素材编排器
高级权限体系

3. 后端对象最小理解

3.1 地图运行域

`Place`

地点
上层业务对象
一个地点下可有多张地图

`MapAsset`

某个地点下的一张地图资源
一张地图可有多个瓦片版本

`TileRelease`

某张地图的具体瓦片发布版本

`CourseSet`

一组赛道集合
例如：校园顺序赛、校园积分赛

`CourseVariant`

一个具体可运行赛道方案
顺序赛 8 点 / 12 点
积分赛 A / B / C 方案
客户端最终只应认这个对象

`CourseSource`

原始输入源
KML 只是来源，不是最终业务对象

3.2 活动运营域

`Event`

活动业务对象
默认体验活动和定制活动都属于它

`EventPresentation`

活动卡片、详情页、H5 schema

`ContentBundle`

图片、音频、动画、文创、结果页资源等内容包

`MapRuntimeBinding`

活动运行时绑定哪张地图、哪条赛道、哪套瓦片、哪套配置

`EventRelease`

客户端真正消费的活动发布版本

4. 最小关系建议

建议 backend 先按这个关系理解：

Place 1 -> N MapAsset
MapAsset 1 -> N TileRelease
MapAsset 1 -> N CourseSet
CourseSet 1 -> N CourseVariant
CourseVariant N -> 1 CourseSource
Event 1 -> N EventPresentation
Event 1 -> N ContentBundle
Event 1 -> N MapRuntimeBinding
Event 1 -> N EventRelease

其中：

MapRuntimeBinding 负责引用：
- placeId
- mapId
- tileReleaseId
- courseSetId
- courseVariantId

5. 后端第一阶段建议实施顺序

第一步：按增量方式落库最小对象

建议先把表和基础模型定下来。

第一阶段优先级建议：

places
map_assets
tile_releases
course_sources
course_sets
course_variants
map_runtime_bindings

第二阶段再补：

event_presentations
content_bundles

说明：

当前稳定的 events / event_releases / sessions 主链保留
本次是在现有骨架上增量补生产对象，不做一次性替换式重构

第二步：先打通 KML 导入链

目标：

上传 KML
保存 CourseSource
解析控制点与起终点
生成一个 CourseVariant
归入某个 CourseSet

第三步：先打通活动绑定链

目标：

一个 Event 可绑定：
- EventPresentation
- ContentBundle
- MapRuntimeBinding

第四步：先打通发布链

目标：

生成 EventRelease
launch 先继续返回当前稳定字段：
- resolvedRelease
- business
- variant
第二阶段再补完整运行对象字段：
- placeId
- mapId
- tileReleaseId
- courseVariantId
- eventReleaseId

第五步：把第一阶段生产骨架接口接入 `/dev/workbench`

目标：

不让第一阶段对象只停留在 API 目录里
在 workbench 里形成最小可操作联调面板
用于验证对象关系和生产闭环，不用于替代正式后台

本步建议只做：

A. 地点与地图

Place 列表
新建 Place
在 Place 下新建 MapAsset
在 MapAsset 下新建 TileRelease
查看详情

B. 赛道与 KML

CourseSource 列表
新建 CourseSource
新建 CourseSet
在 CourseSet 下新建 CourseVariant
查看详情

C. 运行绑定

MapRuntimeBinding 列表
新建 MapRuntimeBinding
选择：
- place
- map
- tile release
- course variant
查看详情

本步明确不做：

完整后台 UI
Event 全量编辑
EventPresentation 可视化搭建
ContentBundle 大资源管理台
Build / Release 全流程可视化
删除、批量操作、审核流

一句话：

workbench 当前只做“第一阶段生产骨架联调台”，不做“正式后台管理系统”。

第六步：进入“最小接线”阶段

目标：

把 MapRuntimeBinding 和当前 EventRelease 接起来
让运行对象开始逐步进入 launch
保持当前前端稳定链不被打断

本步建议优先做：

A. `EventRelease` 接 `MapRuntimeBinding`

在 EventRelease 上补 runtimeBindingId
查询 EventRelease 时可带出最小 runtime binding 摘要

B. `launch` 新增 `runtime` 摘要块

保留当前稳定字段：
- resolvedRelease
- business
- variant
新增一个兼容性的 runtime 块，建议最少返回：
- runtimeBindingId
- placeId
- mapId
- tileReleaseId
- courseSetId
- courseVariantId
如字段成本不高，可附带：
- placeName
- mapName
- routeCode

C. `workbench` 最小接线验证

在 /dev/workbench 上增加：
- EventRelease 选择或查看
- 绑定 runtimeBinding
- 查看 release 当前已接入的运行对象摘要

本步明确要求：

不修改旧字段语义
不移除旧字段
不让前端现有 launch 链断掉
先做到“后端可挂接、可透出、可验证”

6. 当前接口落地方向

当前阶段建议 backend 后续接口逐步收敛到：

6.1 生产侧接口

创建地点
创建地图
创建瓦片版本记录
上传 KML
生成赛道 variant
创建活动
保存活动展示定义
保存内容包引用
保存运行绑定
创建活动 release

6.2 客户端消费接口

活动列表
活动详情
launch
session start
session finish
result
history

关键要求：

客户端只消费 release 产物
不再消费原始 KML
不再消费地图原始资产
launch 采用两阶段兼容，不要求第一阶段打断当前前端稳定链

6.3 workbench 联调台

backend 下一步建议把以下接口先接到 /dev/workbench：

Place
MapAsset
TileRelease
CourseSource
CourseSet
CourseVariant
MapRuntimeBinding

接入目标：

list
create
detail
binding

不建议当前阶段接入：

edit
delete
batch
审核流

6.4 最小接线阶段接口方向

backend 下一步建议新增或补齐以下能力：

EventRelease 挂接 runtimeBindingId
查询 EventRelease 时返回最小运行绑定摘要
launch 返回新增 runtime 摘要块

当前目标不是让前端强依赖新字段，而是先让：

release 和 runtime binding 接上
launch 能把运行对象透出来
前后端可以开始验证运行对象链是活的

6.5 第四刀：发布闭环阶段

在第三刀已经完成：

MapRuntimeBinding -> EventRelease
launch.runtime 兼容透出

之后，下一步建议进入真正的发布闭环阶段。

目标：

不再要求“先 publish，再手工 bind runtime”
改为 publish 时就能直接产出带 runtimeBindingId 的完整 EventRelease
保持当前旧接口和旧字段完全兼容

本步建议优先做：

A. publish/build 接口支持 `runtimeBindingId`

在当前发布链中允许显式传入 runtimeBindingId
如果传入，则发布完成后直接把 release 绑好 runtime
如果不传入，则继续保持当前兼容行为

B. workbench publish 面板接入 runtime 选择

在 /dev/workbench 的发布操作区增加 Runtime Binding 选择
支持一条完整联调链：
- 选 release source / build
- 选 runtimeBindingId
- publish
- 直接 launch 验证

C. release 查询继续返回 runtime 摘要

Get Release
launch

都继续透出当前最小 runtime 摘要，供前端和总控验证。

本步关键要求：

只加能力，不改旧语义
新流程优先，但旧流程继续可用
发布结果尽量原子，避免漏掉 runtime 挂接

7. 当前需要 backend 重点注意的边界

KML 只是输入源，不是最终业务对象
活动不是素材仓库，活动只引用 ContentBundle
地图上层必须有 Place，不要让 MapAsset 直接当最上层
客户端最终必须只认 EventRelease
launch 返回必须落到具体：
- placeId
- mapId
- tileReleaseId
- courseVariantId
- eventReleaseId

8. 当前待 backend 回写确认

请 backend 线程后续重点回写以下确认：

第一阶段表结构是否接受这套对象拆分
Place / MapAsset / TileRelease / CourseSource / CourseSet / CourseVariant / MapRuntimeBinding 是否按当前顺序推进
KML 导入链是否准备按 CourseSource -> CourseVariant 落
活动是否接受拆成：
- Event
- EventPresentation
- ContentBundle
- MapRuntimeBinding
- EventRelease
launch 两阶段兼容方案是否按当前确认推进
workbench 是否按“第一阶段生产骨架联调台”接入，且只做 list / create / detail / binding

本轮新增执行项：

是否按“第三刀最小接线”推进：
- MapRuntimeBinding -> EventRelease
- launch.runtime 摘要透出
- 继续保持旧字段兼容
是否按“第四刀发布闭环”推进：
- publish 直接支持 runtimeBindingId
- workbench publish 面板增加 runtime 选择
- 继续保留“先 publish，再 bind runtime”的兼容路径
是否进入“活动运营域第二阶段”：
- EventPresentation 最小落库
- ContentBundle 最小落库
- EventRelease 明确绑定 presentation / bundle / runtime
是否进入“活动运营域第二阶段第二刀”：

event detail 透出最小 presentation / bundle 摘要
release detail 透出最小 presentation / bundle / runtime 摘要
launch 增加兼容性的 presentation / contentBundle 摘要块
publish 在未显式传入时允许按 event 当前默认配置自动补齐 presentation / bundle

9. 一句话结论

本次给 backend 的实施要求很简单：

先别继续围绕散装页面和散装配置推进，先把地图运行域和活动运营域的最小骨架搭起来。

当前下一步重点已经进一步明确为：

活动运营域第二阶段第三刀第一版已完成，backend 下一步切到“展示定义统一导入与默认绑定”阶段。

6.6 第五刀：前端正式接线阶段

当前 backend 已完成第四刀第一版：

publish 直接支持 runtimeBindingId
workbench publish 区支持直接填写 Runtime Binding ID
发布成功返回 runtime
旧的“先 publish，再 bind runtime”路径继续兼容

因此下一步建议正式进入前端接线阶段。

目标：

前端开始正式消费 launch.runtime
活动准备页、地图页、结果页、历史页开始逐步展示运行对象摘要
继续保持旧字段兼容，不要求一轮切掉老逻辑

前端第一阶段建议优先做：

A. `launch.runtime` 消费

读取并缓存：
- runtimeBindingId
- placeId
- mapId
- tileReleaseId
- courseSetId
- courseVariantId
如后端已返回名称摘要，也同步接入：
- placeName
- mapName
- routeCode

B. 准备页与地图页最小展示

在准备页展示当前地点 / 地图 / 赛道摘要
在地图页调试或摘要区透出当前 runtime 对象

C. 结果与历史摘要逐步接入

先不强改所有列表
优先让单局结果页和历史详情页能看见：
- place
- map
- variant
- routeCode

当前阶段原则：

前端正式上场，但只接新增摘要，不推翻现有稳定页面主链
resolvedRelease / business / variant 旧字段仍继续保留和可用
如果后端某些名称摘要尚未补齐，前端先按 ID + 已有字段兜底

6.7 第六刀之后的下一步：活动运营域第二阶段第二刀

当前 backend 已完成：

0009_event_ops_phase2.sql
EventPresentation 最小落库
ContentBundle 最小落库
EventRelease 已可绑定：
- presentationId
- bundleId
- runtimeBindingId
publish 已支持显式挂接：
- presentationId
- contentBundleId
- runtimeBindingId

因此下一步建议进入“活动运营域第二阶段第二刀”。目标是：

让 EventPresentation / ContentBundle 不只存在于后台和 publish 输入里
而是正式进入可查询、可验证、可消费的发布摘要

建议顺序：

A. `event detail` 透出当前展示与内容包摘要

建议最少返回：

currentPresentation
- presentationId
- templateKey
- version
currentContentBundle
- bundleId
- bundleType
- version

B. `Get Release` 透出完整最小摘要

建议 release detail 同时包含：

presentation
contentBundle
runtime

前两者先以摘要形式返回，不先做复杂 schema 下发。

C. `launch` 增加兼容性的活动运营摘要块

在保持旧字段与当前 runtime 不变的前提下，新增：

presentation
contentBundle

建议最少包括：

presentationId
templateKey
bundleId
bundleType

D. publish 增加默认补齐逻辑

如果 publish 未显式传入：

presentationId
contentBundleId

允许按 event 当前默认配置自动补齐。

本步明确不建议做：

前端立即全面消费 presentation / bundle
复杂活动页面 schema 下发
内容包全量资源编排
正式后台大 UI

6.8 活动运营域第二阶段第三刀：发布摘要闭环与内容包导入入口

当前已确认：

frontend 已完成“活动运营域摘要第一刀”
当前前端进入联调回归与小范围修复阶段
backend 下一步不应继续围绕前端页面做字段补丁，而应继续把活动运营域本身做完整

本刀建议拆成两步，但按一个阶段推进。

A. 先把 release 摘要闭环

目标：

让 EventRelease 真正成为活动运营域统一发布产物
保证以下几处返回的摘要语义一致：
- event detail
- event play
- launch
- release detail

建议 release detail 最少透出：

presentation
- presentationId
- templateKey
- version
contentBundle
- bundleId
- bundleType
- version
runtime
- runtimeBindingId
- placeId
- mapId
- tileReleaseId
- courseVariantId

同时建议 /dev/workbench 的 release 查看区，能直接验证这三类摘要。

B. 再打开 `ContentBundle` 统一导入入口

目标：

不再只手工创建 ContentBundle
让后续静态资源、音频、动画、文创等内容，先通过统一导入入口进入 bundle

当前阶段建议只做“入口”和“元信息”，不做完整资源平台。

建议最小能力：

新增 ContentBundle Import 最小接口
接收：
- bundleType
- sourceType
- manifestUrl 或等价资源清单入口
- version
- title
创建后生成：
- bundleId
- bundleType
- version
- assetManifest
- status

当前明确不做：

复杂资源上传工作流
大文件管理台
资源审核流
全量 H5 schema 组装

关键原则：

ContentBundle 先做统一导入入口，不先做复杂资源管理系统
frontend 当前不消费资源明细，只继续认摘要
先把“发布对象完整”和“内容资源有正式入口”两件事做起来

6.9 活动运营域第二阶段第四刀：展示定义统一导入与默认绑定

当前已确认：

backend 已完成：
- event detail / play / launch / release detail 活动运营摘要闭环
- ContentBundle 统一导入入口第一版
frontend 当前不再扩新页面链，继续联调回归

所以下一步 backend 不建议继续围绕玩家侧摘要补字段，而应继续把活动运营域生产链做完整。

A. 打开 `EventPresentation` 统一导入入口

目标：

后续外部活动卡片/H5 搭建系统，不再只靠手工创建 presentation
而是通过统一入口把展示定义正式导入 backend