cmr-mini/f2b.md

# F2B 协作清单
> 文档版本：v2.5
> 最后更新：2026-04-07 21:24:00
> 历史归档： [f2b.archive.md](D:/dev/cmr-mini/f2b.archive.md)

说明：

- 本文件由前端维护，写给后端
- 主文件只保留当前仍有意义的信息
- 已完成的大段历史已转入归档

---

## 待确认

### F2B-019

- 时间：2026-04-07 21:24:00
- 提出方：前端
- 当前事实：
  - 游客模式第一刀前端已接到：
    - 地图列表
    - 地图详情
    - 公共活动详情
    - 公共准备页
    - 公共 launch
  - 前端直接实测 backend 公共接口结果如下：
    - `GET /public/experience-maps` -> `200`
    - `GET /public/events/evt_demo_001/play` -> `200`
    - `POST /public/events/evt_demo_001/launch` -> `500 internal_error`
  - 这说明游客模式“看地图/看活动/看准备页”已经通，但“真正进入地图”当前被 backend 公共 launch 卡住。
  - 当前 guest mode 只有默认体验活动可进：
    - `evt_demo_score_o_001` -> `403 event_not_public`
    - `evt_demo_variant_manual_001` -> `403 event_not_public`
- 需要对方确认什么：
  - 请 backend 优先检查 `POST /public/events/{eventPublicID}/launch` 的服务端错误原因。
  - 建议先用 `evt_demo_001` 作为游客模式第一刀的联调基线，修通后再扩别的 demo。
- 状态：待确认

### F2B-018

- 时间：2026-04-07 16:25:00
- 提出方：前端
- 当前事实：
  - 地图体验第一刀前端已完成：
    - 首页 `地图体验` 入口
    - 地图列表页
    - 地图详情页
    - 默认体验活动卡片跳活动详情页
  - 当前这条链仍依赖登录态，因为 backend 现有接口：
    - `GET /experience-maps`
    - `GET /experience-maps/{mapAssetPublicID}`
    - `GET /events/{eventPublicID}`
    - `GET /events/{eventPublicID}/play`
    - `POST /events/{eventPublicID}/launch`
    都走登录态 access token
  - backend 当前已经补齐这组接口。
- 需要对方确认什么：
  - 无
- 状态：已确认

### F2B-017

- 时间：2026-04-07 14:40:00
- 提出方：前端
- 当前事实：
  - 前端已新增产品方案文档：
    - [地图列表与默认体验活动方案](D:/dev/cmr-mini/doc/gameplay/地图列表与默认体验活动方案.md)
  - 当前建议方向是：
    - 增加 `地图列表` 作为默认体验活动入口层
    - 默认体验活动继续复用现有 `Event / Release / Launch / Session`
    - 默认体验活动可挂可不挂
    - 默认体验活动可以不出现在正式活动列表
  - 当前前端并不需要 backend 先做完整地图后台，只需要最小关系和最小摘要支持。
- 需要对方确认什么：
  - 请 backend 先评估并支持以下最小配合项：
    1. 地图/地点与默认体验活动的挂接关系
       - 能回答：某张地图下挂了哪些默认体验活动
    2. 活动摘要补两个稳定字段：
       - `isDefaultExperience`
       - `showInEventList`
    3. 地图列表最小字段建议：
       - `placeId`
       - `placeName`
       - `mapId`
       - `mapName`
       - `coverUrl`
       - `summary`
       - `defaultExperienceCount`
       - `defaultExperienceEventIds[]`
    4. 地图详情最小字段建议：
       - 地点名称
       - 地图名称
       - 地图预览图
       - 默认体验活动列表（最少 `eventId / title / subtitle / eventType / status / ctaText`）
  - 如 backend 对对象关系或字段命名有不同建议，请直接回：
    - 字段名
    - 所属接口
    - 是否建议第一阶段落地
- 状态：待确认

### F2B-016

- 时间：2026-04-07 14:25:00
- 提出方：前端
- 当前事实：
  - 前端已新增一份用于 backend 对齐的配置裁剪文档：
    - [最大配置模板后台落地裁剪表](D:/dev/cmr-mini/doc/config/最大配置模板后台落地裁剪表.md)
  - 该文档的目的不是让 backend 1:1 支持最大配置模板，而是把当前配置能力裁成三类：
    - 第一阶段必做
    - 第二阶段可做
    - 暂不进后台，继续留在程序默认值层
  - 该文档建议配合以下文档一起看：
    - [后端总体架构与当前执行清单](D:/dev/cmr-mini/doc/backend/后端总体架构与当前执行清单.md)
    - [后端第一阶段执行清单](D:/dev/cmr-mini/doc/backend/后端第一阶段执行清单.md)
- 需要对方确认什么：
  - 请 backend 以这三份文档为基线，对齐：
    - 第一阶段后台对象范围
    - 第一阶段应进入后台的配置字段
    - 暂不进后台、继续保留在程序默认值层的字段
  - 如 backend 对某块裁剪有异议，请直接指出：
    - 字段名
    - 希望调整到哪一阶段
    - 原因
- 状态：待确认

### F2B-015

- 时间：2026-04-07 13:46:00
- 提出方：前端
- 当前事实：
  - 准备页地图预览当前已改成：
    - 优先消费 `GET /events/{eventPublicID}/play` 返回的 `preview`
    - 按当前所选 `variantId` 生成预览点位
    - 底图优先仍使用 manifest 对应的正式瓦片源
  - 当前小程序侧现象是：准备页预览仍为空白
  - 前端已补结构化日志，当前会向 backend `client-logs` 上报：
    - `category=event-prepare`
    - `details.phase=prepare-preview`
    - `source`
    - `selectedVariantId`
    - `backendPreviewVariantCount`
    - `tileCount`
    - `controlCount`
    - `overlayAvailable`
    - `previewMode`
    - 失败时 `errorMessage`
- 需要对方确认什么：
  - 请 backend 拉取这批 `prepare-preview` 日志，并核对：
    - 当前 `play.preview.variants` 是否真的返回了多条 variant 预览数据
    - 当前所选 `selectedVariantId` 是否能在 `preview.variants[]` 中命中
    - 当前 preview viewport / baseTiles 是否与正式发布对象一致
  - 如果 backend 已确认日志中 `backendPreviewVariantCount > 0` 但前端仍空白，请回传对应日志片段与当前 demo 的 `eventId / releaseId`
- 状态：待确认

---

## 已确认

### F2B-C011

- 时间：2026-04-03 22:20:00
- 提出方：前端
- 当前事实：
  - backend 已通过 `B2F-035` 收紧 `play.canLaunch` 与 `launch`
  - 当前规则为：缺 `runtime / presentation / content bundle / manifest / 当前发布 release` 任一项时，均不可进入游戏
  - 前端已复测通过，当前按 `play.canLaunch` 作为正式阻断口径
- 需要对方确认什么：
  - 无
- 状态：已确认

### F2B-C012

- 时间：2026-04-03 23:52:00
- 提出方：前端
- 当前事实：
  - manual 多赛道准备页不显示选择区的根因已确认是发布 release 缺少：
    - `play.assignmentMode`
    - `play.courseVariants`
  - backend 已修复 demo/build/publish 链
  - 前端保留了多赛道空态兜底，但主因不在前端
- 需要对方确认什么：
  - 无
- 状态：已确认

### F2B-C013

- 时间：2026-04-03 23:52:00
- 提出方：前端
- 当前事实：
  - 活动卡片列表第一刀所需字段当前已足够
  - 前端已补齐列表与详情页联调日志：
    - `cardEventIds`
    - `clickedEventId`
    - `detailStatus`
    - `detailCanLaunch`
    - `detailCurrentPresentation`
    - `detailCurrentContentBundle`
- 需要对方确认什么：
  - 无
- 状态：已确认

---

## 阻塞

- 当前无

---

## 已完成

### F2B-D010

- 时间：2026-04-03 22:12:00
- 提出方：前端
- 当前事实：
  - 活动页与准备页已统一使用：
    - `当前发布展示版本`
    - `当前发布内容包版本`
  - 当两项为空时，前端统一解释为：
    - 当前发布 release 未绑定
    - 或当前尚未发布
- 需要对方确认什么：
  - 无
- 状态：已完成

### F2B-D011

- 时间：2026-04-07 12:06:00
- 提出方：前端
- 当前事实：
  - 首页 `ongoingSession` 已收成正式交互
  - 当前首页仅在 backend 返回 `ongoingSession` 时显示“进行中的游戏”
  - 支持：
    - `恢复`
    - `放弃`
  - `放弃` 会调用 `finish(cancelled)`，然后清理本地恢复快照并刷新首页
- 需要对方确认什么：
  - 无
- 状态：已完成

---

## 尾项

### F2B-011

- 时间：2026-04-03
- 提出方：前端
- 当前事实：
  - demo 历史 `ongoing session` 的回收口径仍是独立尾项
  - 当前不阻塞主线：多赛道、活动列表、运营摘要、runtime 主链均可继续联调
- 需要对方确认什么：
  - 后续请单独收口 demo 环境下 `launched / running` session 清理与 ongoing 判定规则
- 状态：待后续单独处理

---

## 下一步

- 当前前后端继续按 backend 一键测试环境联调
- 当前前端侧会优先关注：
  - 活动列表第一刀回归
  - 活动详情页/准备页用户化小修
  - 准备页地图预览 V1 稳定性
- 如后端语义或字段发生变化，再通过 `b2f.md` / `f2b.md` 做增量同步