mini-prog/f2f.md

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：通过

交接结论

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