fquiz/REFACTOR_SUMMARY.md

高程数据管理重构总结

重构目标

将高程数据管理从"数据集中心"模式重构为"文件中心"模式，去掉 ElevationDataset 概念，扁平化为 ElevationFileRecord，每条记录对应一个高程文件。

重构成果

1. 数据库层面

新增表: elevation_file_record

• 合并了原 elevation_dataset 的核心字段
• 新增 file_size 字段记录文件大小
• 新增 file_name 字段单独存储文件名
• 包含完整的分析、地形状态追踪字段

更新关联表:

• elevation_apply_job 添加 file_record_id 字段（保留 dataset_id 用于向后兼容）
• elevation_data_import_job 添加 file_record_id 字段（保留 dataset_id 用于向后兼容）

迁移脚本: api/migrations/001_add_elevation_file_record.sql

• 自动从旧表迁移数据
• 创建必要的索引
• 提供兼容性视图

2. 后端 API

新增的 File Record API（推荐使用）

端点	方法	说明
/api/v1/elevation/records	GET	获取文件记录列表
/api/v1/elevation/records	POST	上传文件并创建记录（上传即创建）
/api/v1/elevation/records/{id}	GET	获取文件记录详情
/api/v1/elevation/records/{id}	PATCH	更新文件记录
/api/v1/elevation/records/{id}	DELETE	删除文件记录
/api/v1/elevation/records/{id}/analyze	POST	触发分析任务
/api/v1/elevation/records/{id}/terrain/build	POST	生成地形瓦片
/api/v1/elevation/records/{id}/preview	GET	预览文件数据

保留的 Dataset API（向后兼容）

原有的 /api/v1/elevation/datasets/* 端点保持不变，继续支持旧版前端。

更新的 Apply API

POST /api/v1/elevation/jobs/apply-line 现在同时支持：

• file_record_id: 使用新的文件记录 ID（推荐）
• dataset_id: 使用旧的数据集 ID（向后兼容）

3. 代码文件

新增文件

1. 模型层: api/app/models/elevation.py

   • 添加 ElevationFileRecord 模型类

2. Schema 层: api/app/schemas/elevation.py

   • ElevationFileRecordSummary
   • ElevationFileRecordListResponse
   • ElevationFileRecordCreateRequest
   • ElevationFileRecordUpdateRequest
   • ElevationFileRecordAnalyzeResponse
   • ElevationFileRecordTerrainBuildResponse
   • ElevationFileRecordPreviewResponse
   • ElevationFileRecordUploadResponse

3. Service 层: api/app/services/elevation_file_record_service.py

   • list_file_records(): 列出文件记录
   • get_file_record_by_id(): 获取单条记录
   • create_file_record_from_upload(): 上传并创建记录
   • update_file_record(): 更新记录
   • delete_file_record(): 删除记录
   • queue_file_record_analysis(): 队列分析任务
   • queue_file_record_terrain_build(): 队列地形构建任务
   • preview_file_record(): 预览文件数据
   • serialize_file_record(): 序列化记录

4. API 路由: api/app/api/v1/elevation.py

   • 新增 /records 路由组
   • 保留 /datasets 路由用于向后兼容

5. 前端页面: web/src/app/admin/elevation-records/page.tsx

   • 全新的简化界面（从 1760 行简化到 ~600 行）
   • 上传即创建，无需先创建数据集
   • 每行直接对应一个文件
   • 简化的操作流程

6. 迁移脚本: api/migrations/001_add_elevation_file_record.sql

   • 数据库结构变更
   • 数据迁移逻辑

7. 迁移文档: api/migrations/README.md

   • 迁移说明和步骤

更新文件

1. api/app/models/elevation.py: 添加 ElevationFileRecord 模型
2. api/app/schemas/elevation.py: 添加新的 Schema 定义，更新 ElevationApplyJobSummary 和 ElevationApplyJobCreateRequest
3. api/app/api/v1/elevation.py: 添加新路由，更新 apply 端点支持双 ID

4. 用户体验改进

旧流程（数据集中心）

1. 创建数据集（填写编码、名称）
2. 导入文件到数据集
3. 分析数据集
4. 预览/地形/回填

新流程（文件中心）

1. 直接上传文件（填写来源、分辨率、备注）→ 自动创建记录 + 触发分析
2. 分析完成后：预览/地形/回填

简化点：

• 去掉了"数据集"这个中间层概念
• 上传即创建，一步到位
• 列表直接显示文件，不需要展开查看
• 操作更直观（针对文件而非数据集）

使用指南

执行数据库迁移

# 备份数据库
pg_dump -U your_user your_database > backup.sql

# 执行迁移
psql -U your_user -d your_database -f api/migrations/001_add_elevation_file_record.sql

API 使用示例

上传文件（新 API）

curl -X POST http://localhost:8000/api/v1/elevation/records \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@elevation_data.tif" \
  -F "source=SRTM" \
  -F "resolution_m=30" \
  -F "notes=高程数据" \
  -F "trigger_analysis=true"

回填线路（支持新旧 ID）

# 使用新的 file_record_id
curl -X POST http://localhost:8000/api/v1/elevation/jobs/apply-line \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "line_id": "line123",
    "file_record_id": "record456",
    "mode": "fill_null_only"
  }'

# 使用旧的 dataset_id（向后兼容）
curl -X POST http://localhost:8000/api/v1/elevation/jobs/apply-line \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "line_id": "line123",
    "dataset_id": "dataset789",
    "mode": "fill_null_only"
  }'

前端访问

• 新页面: http://localhost:3000/admin/elevation-records
• 旧页面: http://localhost:3000/admin/elevation（继续可用）

向后兼容策略

1. 数据库层: 保留旧表，新表独立存在，通过 ID 复用实现兼容
2. API 层: 旧 /datasets 端点继续工作，新 /records 端点并行存在
3. 前端: 旧页面和新页面可以同时访问
4. Apply Job: 同时支持 file_record_id 和 dataset_id 参数

后续清理计划

当确认新系统运行稳定（建议观察 1-2 周）后，可执行清理：

-- 删除旧表
DROP TABLE IF EXISTS elevation_dataset_file_meta CASCADE;
DROP TABLE IF EXISTS elevation_dataset CASCADE;

-- 删除旧字段
ALTER TABLE elevation_apply_job DROP COLUMN IF EXISTS dataset_id;
ALTER TABLE elevation_data_import_job DROP COLUMN IF EXISTS dataset_id;

-- 删除兼容性视图
DROP VIEW IF EXISTS elevation_dataset_compat;

删除旧前端页面：

# 可选：删除旧的前端页面
rm web/src/app/admin/elevation/page.tsx

注意事项

1. 执行迁移前务必备份数据库
2. 迁移脚本是幂等的，可以安全重复执行
3. 新旧 API 可以并存，逐步切换客户端
4. 建议先在测试环境验证完整流程
5. 迁移后立即测试核心功能：上传、分析、预览、地形生成、回填

测试清单

• 数据库迁移成功执行
• 旧数据成功迁移到新表
• 上传新文件并创建记录
• 触发文件分析
• 预览文件数据
• 生成地形瓦片（栅格格式）
• 使用新 file_record_id 回填线路
• 使用旧 dataset_id 回填线路（兼容性测试）
• 删除文件记录
• 旧前端页面仍能正常工作
• 新前端页面所有功能正常

技术债务

• 需要为 elevation_tasks.py 添加新的任务函数：
  • analyze_elevation_file_record_job
  • build_elevation_file_record_terrain_job
• Service 层某些函数仍依赖 dataset 结构，需要进一步适配
• 完整删除旧代码前需要确认所有客户端已切换

结论

重构成功将高程数据管理从 1760 行复杂代码简化到约 600 行，去除了不必要的"数据集"抽象层，使功能更加直观和易用。新旧系统可以并存运行，提供了平滑的迁移路径。