推进活动系统最小成品闭环与游客体验

f2f.md

@@ -0,0 +1,200 @@
+# 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`：通过
+
+## 交接结论
+- 当前不是架构失控阶段，主链总体稳定
+- 新线程优先不要扩新链
+- 先把游客模式做一次完整真回归
+- 再决定是继续收产品流，还是回到后台/总控协同线