insar-management-system-v2/docs/SENTINEL1_DATA_MANAGEMENT_ADAPTATION_PLAN_20260510.md

Sentinel-1 数据管理改造规划

日期：2026-05-10

本文只规划“让系统能管理哨兵一号 Sentinel-1 数据”的改造范围，不记录已完成实现。当前建议把目标分成两层：先支持 Sentinel-1 源数据入库、检索、预览、配对和分发；真正进入 ISCE2 / PyINT / SARscape 的 Sentinel-1 自动生产链路，作为后续独立阶段处理。

1. 目标边界

本轮建议做：

1. 扫描并登记 Sentinel-1 SLC .SAFE 解包目录。
2. 解析 Sentinel-1 基础元数据，包括卫星、成像模式、极化、起止时间、绝对轨道、相对轨道、升降轨、footprint。
3. 管理 Sentinel-1 精密轨道 .EOF 文件，并把影像按 acquisition time 匹配到覆盖该时间窗的轨道文件。
4. 在源数据检索、配对规划、任务批次和数据分发中正确显示和使用 Sentinel-1。
5. 对 Sentinel-1 配对增加必要的轻量约束，避免只靠 footprint 交叠产生不科学的候选对。

本轮不建议做：

1. 不把 Sentinel-1 自动送入现有 LT1 专用 ISCE2 / PyINT 流水线。
2. 不做 burst 级精确公共覆盖计算。
3. 不计算真实垂直基线，不把 footprint 中心距伪装成 SAR 空间基线。
4. 不强制支持 .SAFE.zip 直接入库；优先支持已解包的 .SAFE 目录，zip 可作为后续增强。

2. 当前代码现状

已有基础：

• backend/app/utils.py 已经有 parse_s1_radar_filename() 和 parse_s1_orbit_filename() 的雏形。
• backend/app/services/data_service.py 的 scan_radar_data() 是通用源数据扫描入口，理论上可以扫描 LT1 / S1 / GF3。
• radar_data 已有 satellite、satellite_family、imaging_date、imaging_mode、polarization、orbit_direction、product_type、source_product_token、has_orbit_data、orbit_file_path、geom、coverage_polygon 等通用字段。
• backend/app/services/pairing_cache_service.py 已经把 S1A/S1B 归为 S1 family，配对层具备同卫星族筛选能力。
• backend/app/copier.py 分发逻辑是复制原始产品目录，不再依赖 envi_import，这对 .SAFE 目录是有利的。

主要缺口：

• Sentinel-1 .SAFE 的关键元数据主要在 manifest.safe 和 annotation/*.xml，当前 find_xml_file() / parse_xml_metadata() 更偏 LT1 风格 XML，不能可靠解析 S1 footprint、升降轨、相对轨道。
• 当前精轨模块 backend/app/services/orbit_converter.py 基本写死 LT1 LT1A_GpsData_GAS_C_YYYYMMDD.txt，并会同步/转换到 ENVI、ISCE2 池；Sentinel-1 .EOF 不能走这套转换逻辑。
• 当前配对缓存只要求同升降轨、同 look direction、footprint 相交、同卫星族、同模式/极化等。对 Sentinel-1 来说还缺少“同相对轨道/同轨道方向/同 beam mode/必要时同 slice 或同 burst 覆盖”的约束。
• 前端卫星组 frontend/src/config/appConstants.js 目前只有 LT-1、GF-3；配对默认 allowed_satellites 是 LT1A/LT1B，导入 S1 后如果不改，会默认把 S1 排除。
• 现有 ISCE2 / PyINT 生产脚本明显是 LT1 专用，不能因为管理了 S1 数据就默认允许一键生产。

3. Sentinel-1 文件名能提供的信息

标准 Sentinel-1 SLC SAFE 名称通常类似：

S1A_IW_SLC__1SDV_20250101T104105_20250101T104132_XXXXXX_YYYYYY_ZZZZ.SAFE

可直接从文件名得到：

• satellite: S1A / S1B
• satellite_family: S1
• imaging_mode: IW / EW / SM
• product_type: SLC
• product_level: 可从 1SDV 中解析出 level 1
• polarization: DV、DH、SV、SH
• acquisition_start_time_utc
• acquisition_stop_time_utc
• imaging_date
• absolute_orbit，即文件名中的 6 位轨道号
• datatake id / product unique id

文件名通常不能可靠提供：

• footprint
• orbit direction，升轨/降轨
• relative orbit / track
• look direction
• burst 范围
• 精轨覆盖关系

因此只靠文件名可以完成“粗入库”，但要做可靠配对，至少还要读取 manifest.safe 或 annotation XML。

4. 建议新增的元数据模型

为了控制工作量，不建议把 Sentinel-1 所有元数据拆成大量列。建议采用“少量关键列 + JSON 扩展”的方式。

建议新增字段：

• acquisition_start_time_utc
• acquisition_stop_time_utc
• relative_orbit
• absolute_orbit
• slice_number
• sensor_operational_mode，可与现有 imaging_mode 保持一致或作为补充
• swath_list，可用 JSON 或逗号文本保存 IW1/IW2/IW3
• source_format，例如 SAFE_DIR、SAFE_ZIP、LT1_DIR
• metadata_json，保存 Sentinel-1 专用扩展信息

如果想更轻量，也可以第一阶段只增加：

• relative_orbit
• acquisition_start_time_utc
• acquisition_stop_time_utc
• metadata_json

这四个字段已经足够支撑 Sentinel-1 基础管理和更科学的配对过滤。

数据库处理要求：

• 新增 ORM 字段和 Pydantic schema 字段。
• 新增幂等迁移 010_sentinel1_source_fields.sql。
• 把该迁移加入 backend/app/db_maintenance.py 的 MIGRATION_FILES。
• 健康检查里至少确认新增列存在；如果后续扩展精轨库存表，再把库存一致性纳入健康检查。

5. 入库扫描设计

建议把现有解析逻辑拆成“产品类型适配器”：

SourceProductParser
  - LT1 parser
  - Sentinel1 SAFE parser
  - GF3 parser

Sentinel-1 parser 负责：

1. 识别 .SAFE 目录。
2. 从目录名解析粗元数据。
3. 读取 manifest.safe。
4. 读取 annotation XML 获取或校正：
   • pass / orbit direction
   • relative orbit
   • absolute orbit
   • footprint 坐标
   • start / stop time
   • polarization / swath
5. 生成 coverage_polygon、geom、min/max lon/lat。
6. 判断 insar_source_ready：
   • 必须是 SLC
   • 必须有 footprint
   • 必须有 imaging date / acquisition time
   • 必须有 orbit direction
   • Sentinel-1 推荐必须有 relative orbit

兼容策略：

• 已解包 .SAFE 目录优先。
• .SAFE.zip 不在第一阶段直接解析，除非用户明确需要。后续可以在扫描器里只读 zip 内 manifest.safe，但这会明显增加实现和测试量。
• 预览图优先复用 SAFE 内 preview/quick-look.png 或其他 quicklook 文件；当前 find_radar_preview_source() 已有关键词扫描，可少量适配。

6. Sentinel-1 精轨管理设计

Sentinel-1 精轨文件是 .EOF，匹配逻辑不是“卫星 + 日期等于影像日期”，而是：

orbit.satellite == scene.satellite
and orbit.validity_start <= scene.acquisition_time <= orbit.validity_stop

建议新增一个 Sentinel-1 orbit inventory 解析路径：

• 解析 S1A/S1B
• 解析轨道类型：AUX_POEORB / AUX_RESORB
• 解析 validity start / stop
• 记录原始 .EOF 路径

第一阶段可以不建独立轨道表，仍然把匹配结果写回 radar_data.has_orbit_data 和 radar_data.orbit_file_path。但代码上要避免把 .EOF 送进 LT1 的 txt->xml 转换流程。

更稳的设计是后续新增 orbit_files 表：

• satellite
• satellite_family
• orbit_type
• validity_start_utc
• validity_stop_utc
• file_path
• metadata_json

考虑到用户希望初级任务不要太复杂，第一阶段建议先不建表，只做扫描时内存索引和 radar_data 回填。

7. 配对逻辑改造

当前配对缓存可继续使用，但 Sentinel-1 应增加轻量硬约束。

建议硬约束：

• 同 satellite_family = S1
• 默认允许 S1A/S1B 跨星，但必须同 Sentinel-1 family
• 同 orbit_direction
• 同 relative_orbit
• 同 imaging_mode
• 同 polarization 或至少主极化兼容
• footprint 有交叠
• insar_source_ready = true

建议筛选指标：

• time_baseline_days
• scene_overlap_ratio
• scene_center_distance_meters，只作为 footprint 中心距，不叫真实空间基线
• has_orbit_data

不建议第一阶段做：

• 真实垂直基线计算
• TOPS burst 级 overlap
• 自动下载 ASF / Copernicus metadata
• Sentinel-1 burst id 图层化管理

配对缓存字段建议：

• 给 pairing_metric_cache 增加 same_relative_orbit 或通用 same_track。
• 或者在 SQL 硬约束里按 radar_data.relative_orbit 直接过滤。
• 在 selection_meta_json 中记录 relative_orbit、orbit_direction、source_family，便于追溯。

8. 数据分发设计

分发层整体可以复用：

• master 复制完整 .SAFE 目录到 Task_*/master/
• slave 复制完整 .SAFE 目录到 Task_*/slave/
• 如果启用精轨分发，则把 .EOF 复制到 Task_*/orbit/
• .dinsar_pair.json 中增加 Sentinel-1 专用元数据，如 relative orbit、acquisition start/stop、orbit EOF 路径

需要注意：

• .SAFE 目录可能很大，zip 分发开关已经存在的话可以复用。
• 不建议在分发阶段裁剪 SAFE 或抽取 measurement 文件，这会把“数据管理”变成“预处理”。
• 如果源数据是 .SAFE.zip，第一阶段可以要求用户先解包；否则分发逻辑要支持复制 zip 并在生产侧再解包。

9. 前端改造

需要处理的点：

• SATELLITE_GROUPS 增加 S1 / Sentinel-1。
• 源数据检索高级字段增加相对轨道、起止时间、源格式等字段。
• 配对弹窗默认不要固定 LT1A/LT1B；建议默认“不限定卫星”，或者根据当前检索结果自动选择可见卫星。
• 配对参数文案继续使用“footprint 中心距上限”，不要改回“空间基线”。
• 对 Sentinel-1 配对显示 relative_orbit 和 orbit_direction，让用户一眼能看出是不是同轨道。
• 生产提交页如果任务包是 Sentinel-1，但选择了 LT1 专用 PyINT/ISCE2 profile，应给出阻止或强提示。

10. 生产链路边界

现有生产引擎不应直接宣布支持 Sentinel-1：

• ISCE2 当前 pipeline 和 profile 明显是 LT1 定制，包含 LT1 wavelength、LT1 输入 resolver、LT1 轨道转换。
• PyINT / Gamma 当前输入搜索是 LT1*.tar.gz / LT1*.tiff，也属于 LT1 专用。
• SARscape 理论上能处理 Sentinel-1，但当前系统侧是否能用 raw SAFE 驱动 SARscape D-InSAR，需要单独验证模板、参数和 task runner。

所以建议第一阶段只做到：

Sentinel-1 数据管理 -> 配对规划 -> 批次保存 -> 数据分发

生产执行留到第二阶段：

Sentinel-1 Task_* -> 指定 Sentinel-1 engine/profile -> 预检 -> 生产

11. 实施阶段建议

阶段 1：管理与检索

工作内容：

• 完成 Sentinel-1 SAFE parser。
• 从 manifest.safe / annotation XML 提取 footprint、relative orbit、pass、start/stop time。
• 支持 .EOF 精轨扫描和时间窗匹配。
• 增加必要数据库字段和迁移。
• 前端增加 Sentinel-1 过滤和显示。

预估工作量：2-4 天。

风险：主要在不同 SAFE 版本 XML 结构差异，需要准备 3-5 个真实样本覆盖 S1A/S1B、IW、单双极化。

阶段 2：配对与分发

工作内容：

• 配对缓存加入 relative_orbit 约束。
• 配对结果、批次 item、.dinsar_pair.json 保留 Sentinel-1 扩展元数据。
• 分发 .SAFE + .EOF。
• 前端配对弹窗默认卫星选择调整。

预估工作量：1-2 天。

风险：如果数据库新增字段后没有正确标 dirty，需要强制重建 pairing cache。

阶段 3：生产预检保护

工作内容：

• 识别 task source family。
• Sentinel-1 批次提交到 LT1 专用 engine/profile 时阻止。
• 在生产面板显示“当前仅支持管理和分发，生产适配待完成”。

预估工作量：0.5-1 天。

风险：低。

阶段 4：Sentinel-1 生产适配

工作内容：

• 选择 SARscape、ISCE2 TOPS、GMTSAR 或其他处理链。
• 设计 Sentinel-1 专用 engine/profile。
• 做 TOPS 配准、轨道、DEM、burst overlap、输出发布包和 catalog 适配。

预估工作量：按引擎不同约 1-3 周，不建议和第一阶段混在一起。

12. 推荐最小方案

如果目标是“先把系统能管理哨兵数据”，推荐最小闭环如下：

1. 只支持已解包 .SAFE 目录入库。
2. 只解析 SLC 产品。
3. 只新增 relative_orbit、acquisition_start_time_utc、acquisition_stop_time_utc、metadata_json 四类关键字段。
4. .EOF 精轨只做匹配和路径保存，不做转换。
5. 配对只增加同 relative orbit 约束，不做真实空间基线。
6. 分发复制完整 SAFE 和 EOF。
7. 生产页阻止 Sentinel-1 进入 LT1 专用 profile。

这个方案对现有 LT1 链路侵入最小，能让 Sentinel-1 数据先进入“可检索、可配对、可分发、可追踪”的状态。

13. 验收标准

最小验收：

• 扫描一个包含 S1A/S1B .SAFE 的目录后，radar_data 能看到 S1 数据。
• 源数据检索可以按 Sentinel-1、IW、SLC、极化、升降轨、相对轨道过滤。
• 每个 S1 scene 有 footprint，可在地图上显示。
• 有匹配 .EOF 时 has_orbit_data = true，orbit_file_path 指向 EOF。
• 配对结果不会跨 relative orbit。
• 批次保存和数据分发能生成 Task_*，其中包含 master/slave SAFE 和可选 orbit EOF。
• Sentinel-1 批次不会误提交到 LT1 专用生产 profile。

14. 需要用户确认的输入

开工前最好确认：

1. Sentinel-1 数据池是 .SAFE 解包目录，还是 .SAFE.zip 为主。
2. 精轨 .EOF 是否已经本地保存，还是希望后续系统自动下载。
3. 第一阶段是否只做管理/配对/分发，不接生产。
4. 是否接受新增少量数据库字段和一份幂等迁移。