# 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` 当前先按后端派生规则提供，允许后续继续演进

## 文档导航

- [文档索引](D:/dev/cmr-mini/backend/docs/README.md)
- [系统架构](D:/dev/cmr-mini/backend/docs/系统架构.md)
- [核心流程](D:/dev/cmr-mini/backend/docs/核心流程.md)
- [API 清单](D:/dev/cmr-mini/backend/docs/接口清单.md)
- [数据模型](D:/dev/cmr-mini/backend/docs/数据模型.md)
- [配置管理方案](D:/dev/cmr-mini/backend/docs/配置管理方案.md)
- [资源对象与目录方案](D:/dev/cmr-mini/backend/docs/资源对象与目录方案.md)
- [后台管理最小方案](D:/dev/cmr-mini/backend/docs/后台管理最小方案.md)
- [开发说明](D:/dev/cmr-mini/backend/docs/开发说明.md)

## 快速启动

1. 配置环境变量，参考 [`.env.example`](D:/dev/cmr-mini/backend/.env.example)
2. 按顺序执行 [migrations](D:/dev/cmr-mini/backend/migrations)
3. 启动服务

```powershell
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`