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（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 保留