# 准备页地图预览方案
> 文档版本：v1.0
> 最后更新：2026-04-07 12:18:00

本文档用于说明活动准备页的地图预览能力如何设计与落地。

当前目标不是直接进入实现，而是先把方案边界、分层、前后端职责和分阶段路径定清。

---

## 1. 目标

准备页当前已经具备：

- 活动状态摘要
- 赛道选择
- 设备准备
- 进入地图

但“本局对象预览”仍然主要是文字占位，对玩家帮助有限。

准备页地图预览的目标是：

1. 在进入地图前，让玩家建立空间预期
2. 在多赛道活动中，让玩家能直观看到当前赛道差异
3. 让准备页更像“出发前准备”，而不是工程参数页
4. 不打断当前 runtime 主链，也不额外制造一套重资源地图体系

---

## 2. 推荐方案

当前推荐采用：

**低级别正式瓦片做底图，前端动态叠加赛道**

也就是：

- 底图来源：现有正式瓦片资源
- 底图级别：选择一个较低 zoom 作为预览缩略底图
- 叠加层：前端根据当前赛道数据在预览图上动态绘制起点、终点、控制点和腿线

这是一个“混合预览方案”：

- 不单独制作新的预览地图资源
- 不在前端完整拼装高精度交互地图
- 只在准备页做只读预览

---

## 3. 为什么选这个方案

### 3.1 不新增独立地图资源

如果单独为准备页制作预览地图资源，会带来：

- 资源重复
- 发布链复杂度上升
- 底图与正式地图不一致风险

使用低级别正式瓦片作为预览底图，可以保持：

- 同源
- 一致
- 低成本

### 3.2 多赛道切换更自然

多赛道场景下：

- 底图通常是同一张地图
- 差异主要在赛道叠加层

因此最合理的方式是：

- 底图固定
- 切换赛道时仅重绘 overlay

这样：

- 切换更快
- 数据结构更清楚
- 不需要为每个 variant 重新生成整张预览图

### 3.3 前后端职责清楚

后端负责：

- 提供底图预览所需元数据
- 提供赛道叠加所需坐标数据

前端负责：

- 展示底图
- 动态叠加赛道
- 在准备页进行只读预览

这符合当前项目一直坚持的分层原则。

---

## 4. 整体分层

准备页地图预览建议分成 4 层。

### 4.1 地图底图层

来源：

- 当前正式瓦片资源

形式：

- 低级别缩略底图

职责：

- 提供地点区域的空间背景

### 4.2 预览元数据层

来源：

- 后端预览元数据

职责：

- 告诉前端如何把经纬度投到预览图坐标系中

### 4.3 赛道叠加层

来源：

- variant 控制点与腿线数据

职责：

- 在准备页上画出当前赛道

### 4.4 准备页展示层

职责：

- 只读展示
- 切换赛道联动预览
- 不承担局内交互

---

## 5. 后端需要提供的最小字段

V1 不要求后端提供完整预览图 URL，而是先提供“底图元数据 + 赛道 overlay 元数据”。

建议后端提供以下最小结构：

```json
{
  "preview": {
    "mode": "full",
    "baseTiles": {
      "tileBaseUrl": "https://.../tiles/",
      "zoom": 15,
      "tileSize": 256
    },
    "viewport": {
      "width": 800,
      "height": 450,
      "minLon": 117.0000,
      "minLat": 36.6000,
      "maxLon": 117.0800,
      "maxLat": 36.6600
    },
    "variants": [
      {
        "variantId": "variant_a",
        "name": "A线",
        "routeCode": "route-variant-a",
        "controls": [
          { "id": "start", "kind": "start", "lon": 117.01, "lat": 36.61 },
          { "id": "c1", "kind": "control", "lon": 117.02, "lat": 36.615 },
          { "id": "finish", "kind": "finish", "lon": 117.03, "lat": 36.62 }
        ],
        "legs": [
          { "from": "start", "to": "c1" },
          { "from": "c1", "to": "finish" }
        ]
      }
    ]
  }
}
```

其中关键字段是：

- `baseTiles.tileBaseUrl`
- `baseTiles.zoom`
- `viewport.width / height`
- `viewport.minLon / minLat / maxLon / maxLat`
- `variants[].controls`
- `variants[].legs`

这些字段足够前端做只读预览。

---

## 6. 前端如何消费

前端准备页的消费方式建议如下：

### 6.1 底图渲染

- 使用低级别瓦片作为底图来源
- 按 `viewport` 与 `zoom` 计算需要的瓦片范围
- 只在准备页内绘制一张静态缩略底图

### 6.2 赛道叠加

- 根据 `viewport` 把控制点经纬度投影到预览图坐标
- 在 canvas 或同等绘制层上叠加：
  - 起点
  - 终点
  - 控制点
  - 腿线

### 6.3 多赛道切换

- 切换赛道时不重新换底图
- 只重绘叠加层

### 6.4 展示层级

准备页只做：

- 只读预览
- 不拖拽
- 不缩放
- 不交互打点

---

## 7. 多赛道场景如何处理

多赛道场景是这套方案的重点。

当前建议规则：

1. 同一活动下，所有 variant 共用一张底图
2. 当前选中的 variant 决定叠加层内容
3. 如果活动允许手动选赛道，切换赛道时预览同步切换
4. 如果活动是随机分配或后台指定：
   - 准备页在最终绑定前可只显示地点底图
   - 一旦后端返回最终绑定赛道，再显示该赛道 overlay

这套设计和当前多赛道 Variant 架构是一致的：

- 底图属于地图对象
- 叠加属于 variant 对象

---

## 8. 预览级别建议

建议预览能力分成 3 档：

### 8.1 `none`

- 不显示地图预览
- 只显示地点、地图、赛道文字信息

适用于：

- 不允许赛前预览的正式比赛

### 8.2 `summary`

- 显示底图
- 只显示简化赛道范围、起终点或大致区域
- 不暴露完整点位和腿线

适用于：

- 需要局前空间感，但不允许完整剧透路线

### 8.3 `full`

- 显示底图
- 显示完整点位与腿线

适用于：

- 体验活动
- 教学活动
- 低门槛公开活动

V1 建议先直接支持：

- `none`
- `full`

后面再补 `summary`。

---

## 9. 分阶段实施建议

### 9.1 V1

只做：

- 低级别瓦片底图
- 前端动态赛道叠加
- 支持多赛道切换联动
- 只读展示

不做：

- 复杂预览交互
- 预览模式细分
- 缩放与拖拽

### 9.2 V2

补：

- `none / summary / full`
- 不同活动类型的预览策略
- 更细的赛道保密规则

### 9.3 V3

考虑扩展到：

- 活动详情页缩略预览
- 活动列表卡片缩略图
- 赛后结果页路线回看缩略图

---

## 10. 不建议的方案

当前不建议：

### 10.1 单独制作一套预览地图资源

问题：

- 成本高
- 一致性差
- 发布链复杂

### 10.2 前端直接现场拼完整高精度瓦片地图

问题：

- 性能波动大
- 首次加载慢
- 多端一致性差

### 10.3 后端为每个 variant 预生成完整大图

问题：

- 多赛道下资源重复
- 每次改赛道都要重生图
- 扩展性不如“底图固定 + 叠加切换”

---

## 11. 当前建议结论

准备页地图预览最推荐的路线是：

**使用低级别正式瓦片作为预览底图，由前端在准备页动态叠加当前赛道。**

这条路线的优点是：

- 不新增独立地图资源
- 底图与正式地图同源
- 多赛道切换成本低
- 前后端职责清晰
- 易于分阶段落地

当前建议优先推进：

1. 后端补预览元数据最小字段
2. 前端在准备页实现只读底图 + overlay
3. 先支持 `full`
4. 后续再扩 `summary / none`