# ADR-003: 可视化方案变更——Cesium 3D → AMap 2D

## 修改记录

| 日期 | 变更 |
|------|------|
| 2026-07-18 | ADR-003++ 表格化，修正 3 项已完成项状态（角色图标/信息窗体/左右联动），补充交叉引用 |

## ADR-003++

| 状态 | 项 | 说明 | 验证 |
|------|-----|------|------|
| ✅ | setFitView | 自动适配视野，含 ResizeObserver 降级 | `AmapMap.vue:208-222` |
| ✅ | 角色图标 | 酒店红(`mark_r.png`)、景点蓝(`mark_b.png`)+emoji | `AmapMap.vue:149-158` |
| ✅ | 信息窗体 | 点击标记弹出到达/离开/停留/状态 | `AmapMap.vue:162-174` |
| ✅ | 左右联动 | 点击景点→地图弹跳居中 (`highlightSpot` prop) | `AmapMap.vue:275-282` |
| ⏸ | 多源地图切换 | 备选底图（Mapbox/Leaflet） | 未开始 |
| ⏸ | 双层描边路线 | 6px 浅底色 + 3px 主题色实线 | 当前单层 `strokeWeight:5` |
| ⏸ | 方案切换过渡 | 平滑动画 | 未实现 |
| ⏸ | 轻量轨迹预览 | 轨迹动画 + 进度条 | 未实现 |

## 状态

✅ 已采纳

## 背景

项目原本继承旧毕业设计的 Cesium 3D 地球作为路线可视化方案。但在旅行规划场景下，3D 地球存在以下问题：

- 用户认知门槛高：普通用户不习惯 3D 地球的旋转/缩放操作
- 加载性能差：Cesium.js 7MB+，严重影响首屏加载
- 坐标转换复杂：高德 GCJ-02 坐标需额外转换为 WGS-84，存在精度损失
- 与现有技术栈不匹配：后端已全部使用高德 API（POI 搜索、驾车路径），前端高德 JS API 可形成生态闭环

## 决策

1. 完全删除 Cesium 3D 相关代码（cesium_utils.py、frontend/static/Cesium/、CesiumMap.vue）
2. 前端地图组件改用高德 JS API 2.0，重写为 [AmapMap.vue](../structure/frontend.md#4-可复用组件)（`v=2.0`，287 行，含 setFitView / InfoWindow / 角色图标 / 左右联动）
3. 后端 pipeline.py 不再生成 Cesium HTML
4. 清除所有 Cesium 相关配置文件（server.py /Build 挂载 ✅ 已清除、config.py 的 CESIUM_TOKEN ✅ 已清除）

## 理由

| 维度 | 3D 地球（Cesium） | 2D/2.5D 地图（高德 AMap） |
|------|-------------------|--------------------------|
| 用户熟悉度 | 低，有认知门槛 | 极高，用户每天都在用 |
| 核心交互 | 旋转/倾斜/缩放（需学习） | 平移/缩放/点击（零成本） |
| 加载性能 | 7MB+ Cesium.js，启动慢 | 按需加载，轻量快速 |
| 坐标兼容 | 需 GCJ-02→WGS-84 转换 | 原生支持 GCJ-02，与后端完美对齐 |
| 技术生态 | 与 Vue 集成需额外封装 | 高德 JS API + Vue 成熟方案 |
| 维护成本 | 双坐标系转换 + 双视图切换 | 单一坐标系，单一地图方案 |
| 求职价值 | GIS/智慧城市领域 | Web 开发适用范围更广 |

## 落地影响

### 正面

- 用户加载速度提升（移除 7MB Cesium.js）
- 开发效率提升（不需处理坐标转换）
- 技术栈统一（前后端共用高德 API）
- 代码量减少约 500 行（cesium_utils.py + CesiumMap.vue 相关代码）

### 负面

- 失去 3D 可视化能力（旅行规划场景下不关键）
- 原 Cesium 相关的技术演示价值需通过独立 demo 保留