[fix/feat]:[FL-74][高程数据支持DEM地形瓦片预览和线路地形图]

Co-authored-by: multica-agent <github@multica.ai>

memory/2026-06-09.md

@@ -223,3 +223,84 @@
 
 - 风险与关注点：
   - 仅影响 `/admin/workers` 页面首屏展示，不涉及 Worker 数据接口、抽屉详情、权限或轮询逻辑。
+
+## Work Log - 高程数据支持 DEM 地形瓦片预览与线路地形图（2026-06-09）
+
+- 背景：
+  - Issue `FL-74` 要求高程数据除已有样本预览与线路高程回填外，还要支持：
+    - 将 DEM 栅格数据生成可供 Cesium 直接消费的地形瓦片；
+    - 在高程管理页预览真实 DEM 地形；
+    - 在线路管理页基于选定 DEM 显示线路地形图，并暴露地形状态与必要提示。
+  - 现状是：
+    - 后端已有高程数据集、分析任务和线路高程回填链路；
+    - 前端已有 Cesium 预览组件，但仍以点云/网格覆层为主，没有接入真正的 Cesium terrain provider。
+
+- 本次改动：
+  - 后端：
+    - `api/app/models/elevation.py`
+      - 为 `ElevationDataset` 增加 `terrain_status/task/error/root/url_template/min_zoom/max_zoom/bounds/metadata` 等字段。
+    - `api/app/core/database.py`
+      - 扩展兼容列自动补齐逻辑，为已有实例增量补地形字段，并对历史 raster/csv 数据做默认状态回填。
+    - `api/app/services/elevation_service.py`
+      - 新增 DEM 地形瓦片构建主链路：
+        - 栅格边界转换到 WGS84；
+        - 计算 TMS 瓦片层级与范围；
+        - 生成 Cesium `heightmap-1.0` 瓦片二进制与 `layer.json`；
+        - 分析成功后自动派发地形构建任务；
+        - 提供地形状态查询、手动构建、layer/tile 读取服务。
+    - `api/app/tasks/elevation_tasks.py`
+      - 新增 terrain build Celery task。
+    - `api/app/api/v1/elevation.py`
+      - 新增接口：
+        - `POST /api/v1/elevation/datasets/{id}/terrain/build`
+        - `GET /api/v1/elevation/datasets/{id}/terrain/status`
+        - `GET /api/v1/elevation/datasets/{id}/terrain/layer.json`
+        - `GET /api/v1/elevation/datasets/{id}/terrain/{z}/{x}/{y}.terrain`
+    - `api/tests/test_elevation_terrain_service.py`
+      - 补充地形瓦片编码、状态查询与 layer 读取测试。
+    - `api/tests/test_async_dispatch_services.py`
+      - 补充 terrain task 复用与不支持格式状态断言。
+  - 前端：
+    - `web/src/components/elevation-preview-cesium-map.tsx`
+      - 支持真实 terrain provider、指针高程读数、terrain failure 回退提示和数据集范围框。
+    - `web/src/components/power-line-cesium-map.tsx`
+      - 支持选定 DEM 地形、垂直夸张、塔位越界告警、地形加载失败回退和塔位高程来源展示。
+    - `web/src/app/admin/elevation/page.tsx`
+      - 增加地形状态列、地形层级列、地形状态弹窗、手动生成/重试地形入口；
+      - 高程预览弹窗传入 dataset + access token，使预览地图优先加载真实 DEM。
+    - `web/src/app/admin/power-lines/page.tsx`
+      - 增加 DEM 数据集选择与垂直夸张选择；
+      - 线路地图传入 terrain dataset + access token + exaggeration；
+      - 增加 DEM 状态/覆盖范围提示。
+    - `web/src/lib/elevation-terrain.ts`
+      - 抽出地形状态判定、layer 地址解析、塔位越界统计。
+    - `web/src/lib/elevation-terrain.test.js`
+      - 补充地形状态与越界统计测试。
+    - `web/src/lib/power-line-route.ts`
+      - 扩展塔位高程溯源字段解析，用于地图弹窗展示。
+    - `web/src/types/auth.ts`
+      - 补齐 terrain 相关类型。
+
+- 验证：
+  - 基线：
+    - `UV_CACHE_DIR=/tmp/uv-cache uv run --with-requirements requirements.txt --with pytest --no-project env PYTHONPATH=. python -m pytest tests/test_async_dispatch_services.py tests/test_line_preparation_flow.py tests/test_tower_profile_migration.py`
+      - `10 passed, 1 warning`
+  - 修改后：
+    - `python3 -m py_compile app/api/v1/elevation.py app/tasks/elevation_tasks.py app/services/elevation_service.py app/schemas/elevation.py app/models/elevation.py app/core/database.py tests/test_async_dispatch_services.py tests/test_elevation_terrain_service.py`
+      - 通过
+    - `UV_CACHE_DIR=/tmp/uv-cache uv run --with-requirements requirements.txt --with pytest --no-project env PYTHONPATH=. python -m pytest tests/test_async_dispatch_services.py tests/test_line_preparation_flow.py tests/test_tower_profile_migration.py tests/test_elevation_terrain_service.py`
+      - `15 passed, 1 warning`
+    - `node --test web/src/lib/elevation-terrain.test.js web/src/lib/power-line-route.test.js`
+      - `6 passed`
+    - `cd web && NPM_CONFIG_CACHE=/tmp/npm-cache ./node_modules/.bin/eslint ./src/components/elevation-preview-cesium-map.tsx ./src/components/power-line-cesium-map.tsx ./src/app/admin/elevation/page.tsx ./src/app/admin/power-lines/page.tsx ./src/lib/elevation-terrain.ts ./src/lib/elevation-terrain.test.js ./src/lib/power-line-route.ts --max-warnings=0`
+      - 通过
+    - `cd web && NPM_CONFIG_CACHE=/tmp/npm-cache ./node_modules/.bin/tsc --noEmit`
+      - 通过
+    - `cd web && NPM_CONFIG_CACHE=/tmp/npm-cache npm run build`
+      - 通过
+    - `git diff --check`
+      - 通过
+
+- 风险与关注点：
+  - 真实 Cesium 地形请求当前依赖 Bearer token 头传递，不能退化为 cookie-only 访问；后续若调整认证中间件，需要一并回归 terrain provider 链路。
+  - 当前生成格式固定为 `heightmap-1.0` + `EPSG:4326` + `TMS`；若未来要切到 quantized-mesh，需要重新评估生成器和前端兼容层。