cmr-mini/b2f.md

# b2f
> 文档版本：v1.40
> 最后更新：2026-04-07 16:29:08

说明：

- 本文件由 backend 维护，写给 frontend
- 只保留当前有效事项、联调基线和压缩归档
- 已完成旧项不再逐条长留，只保留必要结论

---

## 待确认

### B2F-045

- 时间：2026-04-07 16:29:08
- 谁提的：backend
- 当前事实：
  - backend 已补游客模式最小公开接口：
    - `GET /public/experience-maps`
    - `GET /public/experience-maps/{mapAssetPublicID}`
    - `GET /public/events/{eventPublicID}`
    - `GET /public/events/{eventPublicID}/play`
    - `POST /public/events/{eventPublicID}/launch`
  - 当前游客模式语义：
    - 只允许默认体验活动
    - 只允许基于已发布 release
    - `public launch` 返回结构与正式 launch 基本同构
    - 会额外返回：
    - `launch.source = public-default-experience`
    - `launch.business.isGuest = true`
  - 当前不开放：
    - `/me/entry-home`
    - `/me/results`
    - 历史成绩
    - 报名态
  - 本轮已定位并修复 `F2B-019` 的根因：
    - `POST /public/events/{eventPublicID}/launch` 在创建游客身份时会写入 `login_identities`
    - 旧库约束不允许 `identity_type = 'guest'`
    - 已补 migration：
      - [0015_guest_identity.sql](D:/dev/cmr-mini/backend/migrations/0015_guest_identity.sql)
- 需要对方确认什么：
  - frontend 重启 backend 并应用最新 migration 后，重新回归：
    - `POST /public/events/evt_demo_001/launch`
  - 若仍异常，只回传：
    - `status`
    - `error.code`
    - `eventId`
    - `deviceKey`
- 是否已解决：是

### B2F-044

- 时间：2026-04-07 16:08:20
- 谁提的：backend
- 当前事实：
  - backend 已补地图列表与默认活动最小接口：
    - `GET /experience-maps`
    - `GET /experience-maps/{mapAssetPublicID}`
  - 当前地图列表字段：
    - `placeId`
    - `placeName`
    - `mapId`
    - `mapName`
    - `coverUrl`
    - `summary`
    - `defaultExperienceCount`
    - `defaultExperienceEventIds`
  - 当前地图详情字段：
    - `tileBaseUrl`
    - `tileMetaUrl`
    - `defaultExperiences[]`
  - `defaultExperiences[]` 已带：
    - `eventId`
    - `title`
    - `subtitle`
    - `eventType`
    - `status`
    - `statusCode`
    - `ctaText`
    - `isDefaultExperience`
    - `showInEventList`
    - `currentPresentation`
    - `currentContentBundle`
- 需要对方确认什么：
  - frontend 地图列表第一刀可直接按这组字段开始接线。
  - 如仍缺字段，只回传“字段名 + 使用位置”。
- 是否已解决：否

### B2F-041

- 时间：2026-04-07 13:12:00
- 谁提的：backend
- 当前事实：
  - backend 已把准备页地图预览 V1 的只读字段挂到：
    - `GET /events/{eventPublicID}`
    - `GET /events/{eventPublicID}/play`
  - 当前字段为：
    - `preview.mode`
    - `preview.baseTiles.tileBaseUrl`
    - `preview.baseTiles.zoom`
    - `preview.baseTiles.tileSize`
    - `preview.viewport.width / height / minLon / minLat / maxLon / maxLat`
    - `preview.variants[].controls`
    - `preview.variants[].legs`
    - `preview.selectedVariantId`
  - 三条标准 demo 当前都已具备 preview 元数据。
- 需要对方确认什么：
  - frontend 可按这组字段开始准备页地图预览 V1 接线。
  - 当前只做只读预览，不把 preview 当成正式 launch 前置条件。
- 是否已解决：否

### B2F-040

- 时间：2026-04-07 10:58:18
- 谁提的：backend
- 当前事实：
  - 首页 `ongoingSession` 语义已固定：
    - 只认 `launched`
    - 只认 `running`
  - 以下状态都不算进行中：
    - `finished`
    - `failed`
    - `cancelled`
  - backend 已支持：
    - `POST /sessions/{sessionPublicID}/finish`
    - `status = cancelled`
- 需要对方确认什么：
  - frontend 首页“进行中”只在 `ongoingSession` 存在时显示。
  - 建议按钮：
    - `恢复`
    - `放弃`
  - `放弃` 必须调用 `finish(cancelled)`，然后清本地恢复快照，再刷新 `/me/entry-home`。
- 是否已解决：否

### B2F-038

- 时间：2026-04-03 19:13:57
- 谁提的：backend
- 当前事实：
  - backend 已给活动列表第一刀补齐最小摘要字段，返回位于：
    - `GET /cards`
    - `GET /home`
    - `GET /me/entry-home`
  - 当前字段为：
    - `summary`
    - `status`
    - `statusCode`
    - `timeWindow`
    - `ctaText`
    - `isDefaultExperience`
    - `eventType`
    - `currentPresentation`
    - `currentContentBundle`
- 需要对方确认什么：
  - frontend 按这组字段完成列表页最小接线。
  - 如果仍缺字段，请只回传“缺什么字段、用于哪个页面块”。
- 是否已解决：否

---

## 已确认

### B2F-043

- 时间：2026-04-07 13:51:50
- 谁提的：backend
- 当前事实：
  - backend 已开始提供运维入口第一期：
    - `POST /admin/ops/tile-releases/import`
    - `POST /admin/ops/course-sets/import-kml-batch`
  - backend 也已开始提供统一资源纳管入口：
    - `GET /admin/assets`
    - `POST /admin/assets/register-link`
    - `POST /admin/assets/upload`
    - `GET /admin/assets/{assetPublicID}`
  - 当前已新增独立运维工作台：
    - `GET /admin/ops-workbench`
  - 这批接口与页面主要服务运维录入和发布准备，不要求 frontend 直接接入。
  - 当前 API 总数同步更新为：
    - `101`
- 需要对方确认什么：
  - 无
- 是否已解决：是

### B2F-042

- 时间：2026-04-07 12:38:13
- 谁提的：backend
- 当前事实：
  - manual 多赛道 demo 当前已切到 4 条正式 OSS KML：
    - `gotomars/kml/lxcb-001/2026-04-07/route01.kml`
    - `gotomars/kml/lxcb-001/2026-04-07/route02.kml`
    - `gotomars/kml/lxcb-001/2026-04-07/route03.kml`
    - `gotomars/kml/lxcb-001/2026-04-07/route04.kml`
  - frontend 当前只需消费发布结果，无需读取本地临时目录。
- 需要对方确认什么：
  - 无
- 是否已解决：是

### B2F-034

- 时间：2026-04-07 09:46:00
- 谁提的：backend
- 当前事实：
  - 玩家进入游戏只认“已发布 release”。
  - `currentPresentation / currentContentBundle` 当前表示的是：
    - 当前已发布 release 实际绑定的展示版本
    - 当前已发布 release 实际绑定的内容包
  - 它们不是 event 草稿默认值。
  - `play.canLaunch` 当前已收紧，不是“有 release 就真”。
- 需要对方确认什么：
  - frontend 页面文案应按“当前发布展示版本 / 当前发布内容包版本”理解。
- 是否已解决：是

### B2F-032

- 时间：2026-04-03 18:42:00
- 谁提的：backend
- 当前事实：
  - backend 已接收 frontend 调试日志，并以此作为联调事实依据。
  - 当前建议前端日志至少带：
    - `eventId`
    - `releaseId`
    - `manifestUrl`
    - `game.mode`
    - `playfield.kind`
    - `details.seq`
- 需要对方确认什么：
  - frontend 继续按结构化日志回传事实，不靠截图猜测。
- 是否已解决：是

---

## 阻塞

- 当前无 backend 侧新增阻塞。
- 若 frontend 发现问题，请直接回传：
  - 当前 `eventId`
  - 当前 `releaseId`
  - 当前 `manifestUrl`
  - 当前页面阶段
  - 结构化日志片段

---

## 已完成

### 归档摘要（保留必要结论）

- 时间：2026-04-07 12:18:00
- 谁提的：backend
- 当前事实：
  - `Bootstrap Demo` 当前会准备三条标准 demo 的基础已发布态：
    - `evt_demo_001`
    - `evt_demo_score_o_001`
    - `evt_demo_variant_manual_001`
  - 三条 demo 当前都已清理历史残留 ongoing session。
  - manual 多赛道当前已确认：
    - `assignmentMode = manual`
    - `variantCount = 2`
    - `detailCanLaunch = true`
  - 积分赛当前已确认：
    - `game.mode = score-o`
    - `playfield.kind = control-set`
  - 活动列表当前已能稳定返回 3 张标准 demo 卡片。
- 需要对方确认什么：
  - 无
- 是否已解决：是

---

## 下一步

- frontend 继续按当前联调基线推进：
  - 活动列表第一刀
  - 详情页/准备页语义收口
  - 准备页地图预览 V1
- backend 继续保持：
  - 一键测试链稳定
  - 结构化日志可追踪
  - demo 数据可重复复现