cmr-mini/backend/README.md

Backend

文档版本：v1.22 最后更新：2026-04-03 18:56:46

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

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

并且已经按“配置驱动游戏”收口：

• 业务对象是 event
• 运行配置对象是 event_release
• 真正进入游戏时客户端消费的是 manifest_url
• session 会固化当时实际绑定的 release

当前还要明确一条业务规则：

• 玩家进入游戏，必须基于“已发布 release”
• event 默认绑定、活动草稿配置、未发布 presentation / content bundle 都不能直接作为玩家正式进入依据
• 当前 currentPresentation / currentContentBundle 在玩家链路里表示的是：
  • 当前已发布 release 实际绑定的展示版本摘要
  • 当前已发布 release 实际绑定的内容包摘要
• 它们不是 event 草稿默认值摘要
• 当前 play.canLaunch 和 launch 也已按同一套规则收口：
  • 只有当当前发布 release 同时具备：
    • manifest
    • runtime
    • presentation
    • content bundle 时，玩家才允许正式进入

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

• 它会由 backend 代读当前 launch 对应的 manifest
• 用来显示：
  • configUrl
  • releaseId
  • manifestUrl
  • schemaVersion
  • playfield.kind
  • game.mode
• 这块只服务联调排查，不参与正式客户端运行链路
• 正式客户端仍应直接消费 launch 返回的：
  • launch.config.configUrl
  • launch.resolvedRelease.manifestUrl

当前 workbench 里新增的“前端调试日志”也仅用于联调：

• frontend 可将页面侧调试日志 POST 到 /dev/client-logs
• backend 会临时保留最近 200 条日志，供 workbench 查看与清空
• 这块只用于联调排查，不替代正式生产日志体系

当前 demo 真实输入第一刀也已经接入：

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

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

• Bootstrap Demo（只准备数据）
  • 只准备 demo 测试数据，不额外重新发布当前玩法
• Bootstrap + 发布当前玩法
  • 先准备 demo，再对当前选中的玩法执行一遍“发布活动配置（自动补 Runtime）”
• 这两条路由只服务联调，不进入正式客户端发布链
• 当前联调样例文案也已从 Demo ... 收口为中文活动样例，便于前端和总控直接对口排查

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

• /cards
• /home
• /me/entry-home

这三处当前已统一补齐最小活动卡片摘要字段：

• summary
• status
• statusCode
• timeWindow
• ctaText
• isDefaultExperience
• eventType
• currentPresentation
• currentContentBundle

当前口径：

• 卡片摘要与详情页继续共用同一套“当前发布 release 摘要”语义
• currentPresentation / currentContentBundle 仍表示：
  • 当前已发布 release 实际绑定的展示版本摘要
  • 当前已发布 release 实际绑定的内容包摘要
• isDefaultExperience 当前由卡片显式字段控制
• timeWindow / ctaText 当前先按后端派生规则提供，允许后续继续演进

文档导航

• 文档索引
• 系统架构
• 核心流程
• API 清单
• 数据模型
• 配置管理方案
• 资源对象与目录方案
• 后台管理最小方案
• 开发说明

快速启动

1. 配置环境变量，参考 .env.example
2. 按顺序执行 migrations
3. 启动服务

cd D:\dev\cmr-mini\backend
.\start-backend.ps1

当前重点

• 统一登录：短信 + 微信小程序
• 多入口：tenant + entry_channel
• 首页聚合：/home、/cards、/me/entry-home
• 配置驱动启动：/events/{id}/play、/events/{id}/launch
• 局生命周期：start / finish / detail
• 局后结果：/sessions/{id}/result、/me/results
• 第一阶段生产骨架：places / map-assets / tile-releases / course-sources / course-sets / course-variants / runtime-bindings
• 第三刀最小接线：runtimeBinding -> eventRelease -> launch.runtime
• 第四刀发布闭环：publish(runtimeBindingId) -> eventRelease -> launch.runtime
• 活动运营域第二阶段：event_presentations / content_bundles / event_release -> presentation,bundle,runtime
• 活动运营域第二阶段第二刀：event detail / event play / launch -> presentation,bundle 摘要
• 活动运营域第二阶段第三刀：release 摘要闭环 + content bundle import
• 活动运营域第二阶段第四刀：presentation import + event 默认 active 绑定 + publish 默认继承
• 开发工作台：/dev/workbench
  • 用户主链调试
  • 资源对象与 Event 组装调试
  • Build / Publish / Rollback 调试
  • Release / RuntimeBinding 最小挂接验证
  • Event Presentation / Content Bundle 最小挂接验证
  • Content Bundle Import 最小导入验证
  • Presentation Import / Event 默认绑定 / Publish 默认继承验证
  • Runtime 自动补齐 + 默认绑定发布一键验证
  • Bootstrap Demo 自动回填最小生产骨架 ID
  • 一键测试环境：可从空白状态自动准备 demo event、source/build/release、presentation、content bundle、place、map asset、tile release、course source、course set、course variant、runtime binding，并输出逐步日志与预期判定
  • 一键标准回归：在标准发布链跑通后，继续自动验证 play / launch / result / history
  • 真实输入替换第一刀：Bootstrap Demo 已改用真实可访问的 KML 与地图资源 URL
  • manual 多赛道 demo：已切到真实 c01.kml / c02.kml 输入
  • 前端调试日志：
    • POST /dev/client-logs
    • GET /dev/client-logs
    • DELETE /dev/client-logs
  • 显式玩法入口：
    • 顺序赛：evt_demo_001
    • 积分赛：evt_demo_score_o_001
    • 多赛道：evt_demo_variant_manual_001