# F2F 工作交接

- 文档版本：v1.0
- 最后更新：2026-04-07 21:45:00
- 维护方：前端线程 -> 新线程

## 当前主线状态

### 1. 活动主链
- 活动列表第一刀已完成：
  - 独立活动列表页已接通
  - 支持 `全部 / 体验`
  - 可跳活动详情页
- 活动详情页用户化第一刀已完成：
  - `当前状态`
  - `赛道与版本`
  - CTA 文案更像用户视角
- 准备页用户化第一刀已完成：
  - `当前准备状态`
  - `活动版本摘要`
  - `本局对象预览`
  - 设备准备区
- 结果页 / 历史页活动链衔接已完成一轮小修：
  - 单局结果页支持 `返回活动`
  - 历史结果页支持 `查看单局结果 / 返回活动`

### 2. 地图体验主链
- 地图体验第一刀已完成：
  - 首页有 `地图体验` 入口
  - 地图列表页已接通
  - 地图详情页已接通
  - 地图下默认体验活动可跳现有活动详情主链
- 当前对象模型口径：
  - `Place`
  - `MapAsset`
  - `Event`
  - `defaultExperienceEvents[]`
- 默认体验活动支持：
  - 可挂可不挂
  - 可以不显示在正式活动列表

### 3. 游客模式主链
- 游客模式第一刀已接上：
  - 登录页支持 `游客体验`
  - 游客可进地图列表、地图详情、默认体验活动详情、准备页、公共 `launch`
  - 活动详情 / 准备页无登录态时自动走 `/public/...`
  - 游客结果页优先展示本地结果摘要，不强制跳登录
- 之前 `/public/events/{id}/launch` 有 backend 500 问题，已在协作文档里反馈过。
- 用户最新口头反馈：backend 改后“能进了”，但未再做完整闭环确认。

### 4. 准备页地图预览 V1
- 已完成并可用：
  - 低级别正式瓦片做底图
  - 白膜压背景
  - 只叠 KML 点位，不画腿线，不画数字
  - 点位群尽量充满预览窗口
- 多赛道：
  - 已支持切换赛道后联动预览
  - 当前实现是：
    - 底图与缩放优先走 manifest 正式地图配置
    - 多赛道点位联动优先消费 backend `play.preview`
- 单赛道：
  - 强制回到稳定的 manifest 预览链
- 之前为预览排查加的 backend 临时日志已清理。

### 5. 准备页进入地图链
- 已补齐：
  - 防连点
  - 进度反馈
  - 12 秒超时兜底
  - 返回准备页后清理残留“正在进入地图”视觉状态
- 相关文件：
  - `miniprogram/pages/event-prepare/event-prepare.ts`
  - `miniprogram/pages/event-prepare/event-prepare.wxml`
  - `miniprogram/pages/event-prepare/event-prepare.wxss`

### 6. 恢复与 ongoing
- 冷启动恢复弹窗已取消
- 统一走首页 `进行中的游戏` 区块：
  - `恢复`
  - `放弃`
- `放弃` 会走 `finish(cancelled)`，然后清本地恢复快照并刷新首页

## 最近重要修复

### 1. 单独项目 www 类型检查干扰
- 已在根 `tsconfig.json` 中排除 `www`
- 现在根项目 `npm run typecheck` 可以通过

### 2. 多赛道准备页选择区
- 前面出现过“活动是多赛道，但准备页没有赛道区”的问题
- 已确认根因主要在 backend 发布 release 缺少：
  - `play.assignmentMode`
  - `play.courseVariants`
- 前端做了用户体验兜底：
  - 只要能判断是多赛道活动，即使后端暂未返回可选赛道，也保留赛道区空态提示

### 3. 积分赛误进顺序赛
- 已确认根因在 backend 首页卡片入口配置，不是前端玩法解析
- 当前主链已收口

## 协作文档现状

### 1. 前端 -> 后端
- 文件：`f2b.md`
- 当前版本：v2.5
- 当前重点：
  - `F2B-019`：游客模式公共 `launch` 曾返回 500，backend 文档称已修，但建议新线程视情况确认是否真正闭环

### 2. 前端 -> 总控
- 文件：`f2t.md`
- 当前版本：v2.0
- 说明：
  - 内容已经偏旧，没有完整覆盖游客模式、地图体验、预览 V1、event-prepare 启动防抖等后续改动
  - 如新线程继续与总控同步，建议先更新此文件

## 当前建议优先级

### P0：先做一轮游客模式真回归
建议测试：
1. 登录页点 `游客体验`
2. 进入地图列表
3. 进入地图详情
4. 点默认体验活动
5. 进入活动详情 / 准备页 / 地图
6. 正常完成或主动退出
7. 确认结果页、返回链、退出链是否正常

如果游客主链仍有问题，优先看：
- backend `/public/...` 返回
- `f2b.md` 里的 `F2B-019`

### P1：更新总控协作文档
- 把以下内容同步进 `f2t.md`：
  - 地图体验第一刀
  - 游客模式第一刀
  - 准备页预览 V1
  - 进入地图防抖/进度/超时

### P2：继续后台/运维平台协同
当前已落文档，可继续给 backend / 总控参考：
- `doc/backend/后台游戏定制支持方案.md`
- `doc/backend/后端总体架构与当前执行清单.md`
- `doc/config/最大配置模板后台落地裁剪表.md`
- `doc/gameplay/地图列表与默认体验活动方案.md`
- `doc/gameplay/准备页地图预览方案.md`

## 建议优先阅读文档

### 新线程先看这 6 份
1. `f2f.md`
   - 当前交接总览
2. `f2b.md`
   - 前端写给后端的当前待确认/已确认事项
3. `f2t.md`
   - 前端写给总控的当前状态
4. `doc/gameplay/准备页地图预览方案.md`
   - 准备页预览的设计与边界
5. `doc/gameplay/地图列表与默认体验活动方案.md`
   - 地图体验入口与默认体验活动模型
6. `doc/backend/后端总体架构与当前执行清单.md`
   - 后台/发布/游戏定制的大方向

### 如果要继续做后台协同，再看这 3 份
1. `doc/backend/后台游戏定制支持方案.md`
2. `doc/config/最大配置模板后台落地裁剪表.md`
3. `doc/backend/后端第一阶段执行清单.md`

## 关键文件

### 活动/地图体验
- `miniprogram/pages/home/home.ts`
- `miniprogram/pages/events/events.ts`
- `miniprogram/pages/event/event.ts`
- `miniprogram/pages/event-prepare/event-prepare.ts`
- `miniprogram/pages/experience-maps/experience-maps.ts`
- `miniprogram/pages/experience-map/experience-map.ts`
- `miniprogram/pages/result/result.ts`
- `miniprogram/pages/results/results.ts`

### API / 启动 / 预览
- `miniprogram/utils/backendApi.ts`
- `miniprogram/utils/backendLaunchAdapter.ts`
- `miniprogram/utils/gameLaunch.ts`
- `miniprogram/utils/prepareMapPreview.ts`

### 恢复 / 会话 / 首页 ongoing
- `miniprogram/pages/index/index.ts`
- `miniprogram/pages/home/home.ts`
- `miniprogram/pages/map/map.ts`

## 当前验证结果
- `npm run test:runtime-smoke`：通过
- `npm run typecheck`：通过

## 交接结论
- 当前不是架构失控阶段，主链总体稳定
- 新线程优先不要扩新链
- 先把游客模式做一次完整真回归
- 再决定是继续收产品流，还是回到后台/总控协同线