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

# SBAS 系统集成与数据管理审计报告

更新日期：2026-04-06

## 1. 审计范围

本次审计聚焦三件事：

- 当前 ISCE2 SBAS 实验是否已经真实读取并使用精密轨道
- 现有系统的数据管理方案是否适合承接 SBAS/PS-InSAR 生产口
- 如果后续要把实验方案嵌入系统，推荐怎样分阶段落地

本报告基于当前仓库实现与已成功的实验产物，不涉及对现有 D-InSAR 生产链的破坏性修改。

## 2. 结论摘要

- 结论 1：当前 SBAS 实验已经真实读取并使用精密轨道，不只是“数据库里有轨道路径”。
- 结论 2：当前系统可以完成 PS/SBAS 选片和实验产物生成，但还不能把 `psinsar` 产物作为正式生产结果注册、编目、健康检查和发布。
- 结论 3：当前数据管理整体偏“路径驱动”，原始数据身份、存储位置、运行产物三层边界不够清晰，因此用户会感到“数据管理比较松散”。
- 结论 4：轨道管理反而是当前较完整的一块，已经具备源目录扫描、池同步、一致性检查和数据库状态统计能力。

## 3. 审计发现

### P0 / 高优先级

#### 3.1 结果编目和发布入口仍然是 D-InSAR 专用，`psinsar` 实验产物无法直接接入系统

证据：

- `backend/app/services/result_catalog_service.py:707-713`
  - `_load_manifest()` 只接受 `product_type == dinsar`
- `backend/app/services/result_catalog_service.py:750-753`
  - 即使读入 manifest，也把 `product_type` 固定写成 `dinsar`
- `backend/app/routers/dinsar_products.py:107-140`
  - 现有编目 API 和后台任务只暴露 `/dinsar-products/*`
- `backend/app/services/health_service.py:124-170`
  - 结果目录健康检查只统计 `catalog_name == dinsar`
- `experiments/isce2_sbas_timeseries/scratch/lt1a_strip1_hh_descending_e123p3_n46p1/publish/mintpy_sbas_unified_v1/manifest.json:2-9`
  - 当前实验成功产物的 manifest 是 `schema_version = psinsar.publish.v1`，`catalog_name = psinsar`

影响：

- 实验已经能产出发布级 bundle，但系统当前不会把它识别为正式产品
- 不能复用现有结果页、目录重建、健康检查、产品详情接口
- 后续如果直接“硬塞”进 D-InSAR 目录，会污染现有 D-InSAR 语义

建议：

- Phase 1 不要新建一套完全独立的产品表，继续复用 `result_products` / `result_assets`
- 但必须让 catalog 服务显式支持 `catalog_name = psinsar`
- 最小可行改造是新增 `psinsar` manifest 解析路径，或把当前 catalog service 抽象成多 catalog 分发器

#### 3.2 `ps_task_batches` / `ps_task_items` 目前只是选片快照，不是生产记录

证据：

- `backend/app/models/orm.py:516-550`
  - `PsTaskBatchORM` / `PsTaskItemORM` 只保存批次、`file_path`、日期、极化、是否有轨道和状态
- `backend/app/routers/task_batches.py:281-320`
  - 创建 `/task-batches/ps` 时只是把选中的影像元数据写入 `ps_task_items`
- `backend/app/routers/pairing.py:124-147`
  - 现有 `find-ps-timeseries` 只负责找 stack
- `backend/app/services/spatial_service.py:444-481`
  - `find_ps_timeseries_data()` 只返回按轨道方向分组的影像栈
- `backend/app/services/job_handlers.py:306-321`
  - 对 `PS_STACK` 的后台处理目前只是复制选中的影像路径

影响：

- 系统里没有“某次 SBAS 生产运行”的业务主记录
- 无法稳定记录 `work_dir`、`publish_dir`、运行环境、参数版本、DEM、轨道来源、水体掩膜来源
- 无法形成真正可追溯、可重跑、可审计的生产口

建议：

- 新增业务表 `ps_timeseries_runs`
- 保留 `ps_task_batches` 作为“输入栈定义”
- 把真正的处理运行、产物发布、失败重试、步骤状态全部挂到 `ps_timeseries_runs + workflow_runs`

#### 3.3 数据身份与存储路径耦合过深，迁移和重构成本偏高

证据：

- `backend/app/models/orm.py:22-40`
  - `RadarDataORM` 直接保存 `file_path`、`orbit_file_path`、`preview_cache_path`
- `backend/app/models/orm.py:82-101`
  - `ResultProductORM` 直接保存 `publish_dir`、`manifest_path`、`source_primary_path`、`primary_asset_path`
- `backend/app/models/orm.py:182-195`
  - `ResultAssetORM` 保存 `absolute_path`
- `backend/app/services/data_service.py:621-668`
  - `unique_id` 通过 `os.path.relpath()` 生成，并按 `unique_id` 做 upsert

影响：

- 数据身份会受存储根目录变化影响
- Windows 根目录变更、WSL 路径调整、NAS 迁移时，数据库主身份和存储位置语义混在一起
- 产物迁移到正式发布目录后，历史绝对路径会变成系统耦合点

建议：

- 把“数据身份”和“存储位置”拆开
- 原始影像层至少补充稳定的 `scene_uid` 或 `product_uid`
- 结果层至少补充稳定的 `run_id` / `product_id` 业务主键，把绝对路径退化为可替换的存储定位信息

### P1 / 中优先级

#### 3.4 原始影像与轨道的关联粒度偏粗，缺少轨道版本与来源追踪

证据：

- `backend/app/services/data_service.py:611-612`
  - 影像是否有轨道仅按 `(satellite, imaging_date)` 关联
- `backend/app/services/data_service.py:688-692`
  - 后续补关联时也是按同一键更新

影响：

- 当同一天存在多个候选轨道版本时，数据库层无法区分来源和版本
- 无法在结果层明确回答“本次 SBAS 用的是哪份轨道文件、其 checksum 是多少、来自 source 目录还是 ISCE2 pool”

建议：

- 最小可行做法：在 `RadarDataORM` 或新表中增加
  - `orbit_stem`
  - `orbit_checksum`
  - `orbit_source_type`
  - `orbit_pool_path`
- 更完整做法：单独建 `orbit_assets` / `orbit_bindings`

#### 3.5 数据扫描服务职责过重，扫描、轨道同步、预览缓存、数据库写入耦合在一起

证据：

- `backend/app/services/data_service.py:426-463`
  - 扫描原始轨道并同步 ENVI / ISCE2 池
- `backend/app/services/data_service.py:568-699`
  - 同一流程里完成影像元数据读取、轨道关联、数据库 upsert
- `backend/app/services/data_service.py:709-739`
  - 后面又继续做缓存重建候选收集

影响：

- 这个服务变成“总装配间”，测试和回归都更困难
- 后续要引入 SBAS 生产口时，很容易继续把更多责任塞进同一个服务

建议：

- 拆分为至少四块：
  - `radar_inventory_service`
  - `orbit_inventory_service`
  - `radar_catalog_service`
  - `preview_cache_service`

#### 3.6 Windows/WSL 双路径模型是当前现实，但需要收口到专门的路径层

证据：

- `backend/app/config.py:150-186`
  - 同时维护 Windows 轨道池、DEM、IDL、WSL distro、WSL Python 等配置
- `experiments/isce2_sbas_timeseries/scripts/build_lt1_stack_prep.py:140-149`
  - 实验准备阶段会解析 orbit XML
- `experiments/isce2_sbas_timeseries/scripts/build_lt1_stack_prep.py:171-193`
  - 同时生成 Windows 路径和 WSL 路径
- `experiments/isce2_sbas_timeseries/scripts/materialize_lt1_stack_scenes.py:98-103`
  - 物化阶段直接把 orbit XML 传给 ISCE2 sensor

影响：

- 当前方案能跑通，但如果没有统一的路径转换层，后续每个服务都可能自己拼接 `/mnt/*`
- 这会继续加重“数据管理松散”的体感

建议：

- 保留当前双路径现实，不要硬回避
- 但把路径转换统一收敛到 `timeseries_paths.py` 或类似组件
- 生产口只暴露业务字段，不让上层 UI 和业务逻辑直接感知 `/mnt/z` 与 `F:\`

### P2 / 正向发现

#### 3.7 轨道管理是当前系统里相对成熟的一块

证据：

- `backend/app/services/data_service.py:426-463`
  - 已有源目录扫描与 ENVI / ISCE2 轨道池同步
- `backend/app/routers/orbit.py:27-108`
  - 已有数据库统计、池一致性检查、缺口汇总

结论：

- 不需要为 SBAS 重新发明一套轨道管理
- 更合理的方向是复用现有轨道池和一致性检查能力，再补生产级 provenance

## 4. 关于“现在实验读取精密轨道了吗”

答案：是，已经读取，而且已进入实际处理链。

证据链如下：

1. 轨道解析入口：
   - `backend/app/isce2_pipeline/lt1_input_resolver.py:165-201`
   - `ensure_lt1_orbit_xml()` 会优先取已有 XML，找不到才从 LT-1 轨道 txt 生成 XML
2. Stack 准备阶段：
   - `experiments/isce2_sbas_timeseries/scripts/build_lt1_stack_prep.py:140-149`
   - 每景影像都调用 `ensure_lt1_orbit_xml()`
3. Stack 物化阶段：
   - `experiments/isce2_sbas_timeseries/scripts/materialize_lt1_stack_scenes.py:98-103`
   - `sensor.orbitFile = orbit_xml`
4. 实验 manifest 证据：
   - `experiments/isce2_sbas_timeseries/scratch/lt1a_strip1_hh_descending_e123p3_n46p1/stack_input_manifest.json:92-95`
   - `experiments/isce2_sbas_timeseries/scratch/lt1a_strip1_hh_descending_e123p3_n46p1/stack_input_manifest.json:123-126`
   - `experiments/isce2_sbas_timeseries/scratch/lt1a_strip1_hh_descending_e123p3_n46p1/stack_input_manifest.json:154-157`
   - manifest 已明确记录 `D:\\orbit_pools\\isce2\\LT1A_GpsData_GAS_C_*.xml`
5. 运行日志证据：
   - `experiments/isce2_sbas_timeseries/scratch/lt1a_strip1_hh_descending_e123p3_n46p1/stack_work/logs/run_01_reference.log:18`
   - `experiments/isce2_sbas_timeseries/scratch/lt1a_strip1_hh_descending_e123p3_n46p1/stack_work/logs/run_03_geo2rdr_coarseResamp.log:6`
   - 日志中已出现 `Orbit interpolation method: hermite`

结论补充：

- 当前 SBAS 实验使用的是 ISCE2 轨道池中的 XML 精轨
- 因此“精轨是否已读入”这件事在实验层已经成立
- 真正缺的不是“有没有轨道”，而是“系统如何把这次运行及其轨道 provenance 规范地登记为生产记录”

## 5. 集成设计建议

### 5.1 集成边界

当前最合理的系统集成边界不是 MintPy 运行目录，而是发布级 bundle：

- 入口文件：`manifest.json`
- 目录结构：`assets/`、`preview/`、`metadata/`

这与现有产品规范一致：

- `docs/ISCE2_SBAS_PRODUCT_SPEC.md:69-88`

因此：

- 不要直接注册 `stack_work/mintpy_sbas_*`
- 要注册 `publish/.../manifest.json` 所代表的一整个 bundle

### 5.2 推荐最小落地架构

#### 层 1：规划层，继续复用现有能力

- 继续使用 `find-ps-timeseries`
- 继续使用 `ps_task_batches` / `ps_task_items`
- 其职责只保留为“选片与栈定义”

#### 层 2：生产层，新增业务主记录

新增 `ps_timeseries_runs`，至少包含：

- `run_id`
- `batch_id`
- `catalog_name`
- `engine_code`
- `processor_code`
- `env_name`
- `wsl_distro`
- `work_dir`
- `publish_dir`
- `manifest_path`
- `reference_date`
- `direction`
- `params_json`
- `summary_json`
- `orbit_summary_json`
- `dem_path`
- `water_mask_source`
- `status`
- `error_message`
- `started_at`
- `ended_at`

#### 层 3：编目层，扩展现有结果目录

不要单独再造一套产品表，继续复用：

- `result_products`
- `result_assets`
- `result_issues`

但要新增 `psinsar` catalog 入口，支持：

- 解析 `psinsar.publish.v1`
- 注册 `catalog_name = psinsar`
- 单独的 catalog status / rebuild / health-check

#### 层 4：接口层

建议新增：

- `POST /timeseries-production/runs`
- `GET /timeseries-production/runs`
- `GET /timeseries-production/runs/{run_id}`
- `POST /timeseries-production/runs/{run_id}/retry-step`
- `GET /ps-products`
- `GET /ps-products/{product_id}`
- `POST /ps-products/rebuild-catalog`

### 5.3 与当前设计文档的一致性

当前仓库里的 SBAS 设计文档已经提前写出了这条路线：

- `docs/ISCE2_SBAS_TIMESERIES_DESIGN.md:227`
  - 建议新增 `ps_timeseries_runs`
- `docs/ISCE2_SBAS_TIMESERIES_DESIGN.md:292-296`
  - 建议新增 SBAS 相关 job types
- `docs/ISCE2_SBAS_TIMESERIES_DESIGN.md:306-313`
  - 建议新增 `timeseries_production` / `ps_products` / `psinsar_catalog_service`
- `docs/ISCE2_SBAS_TIMESERIES_DESIGN.md:563-575`
  - TODO 中已明确列出 ORM、路由、job handler、catalog 扩展和健康检查

所以本次审计的判断不是与现有设计冲突，而是说明：

- 实验层已经坐实
- 代码现实也证明下一步确实该进入“生产层与 catalog 层补齐”

## 6. 建议 TODO

### 6.1 立即做

- [ ] 新增 `ps_timeseries_runs` ORM / schema / migration
- [ ] 新增 `timeseries_production` router
- [ ] 新增 `PUBLISH_PSINSAR_PRODUCTS` 及相关 job handlers
- [ ] 让 catalog 服务支持 `psinsar.publish.v1`
- [ ] 把 `publish/.../manifest.json` 作为唯一注册入口

### 6.2 紧接着做

- [ ] 给 `ps_timeseries_runs` 记录 DEM、轨道、水体掩膜、运行环境版本
- [ ] 给轨道绑定补 provenance 字段或单独轨道资产表
- [ ] 把 Windows/WSL 路径转换收敛到独立路径服务
- [ ] 为 `psinsar` 增加 catalog health-check 与 rebuild

### 6.3 暂缓做

- [ ] 不要现在就改动现有 D-InSAR 生产链
- [ ] 不要把 SBAS 运行目录直接暴露为产品目录
- [ ] 不要为了 SBAS 先拆掉现有 `result_products`

## 7. 审计结论

如果现在问“SBAS 能不能开始往系统里接”，答案是：

- 能，但应该先接“发布 bundle + 生产记录 + psinsar catalog”
- 不能直接把实验目录粗暴塞进现有 D-InSAR 产品体系

如果现在问“系统的数据管理为什么显得松散”，核心原因是：

- 原始数据身份、物理存储路径、生产产物目录三层目前还没有彻底分开

如果现在问“下一步最值得做什么”，答案是：

- 先把 `ps_timeseries_runs + psinsar catalog` 这两个缺口补上

这样既不会动坏现有 D-InSAR 生产，又能把已经验证成功的 SBAS 实验稳稳接成系统能力。