Files

T

Harmon d108b33f80 docs: govern and archive superseded notes

- add documentation governance and cleanup audit documents

- update README and docs index to distinguish current vs historical sources

- move superseded planning, SBAS, Gamma, and experiment notes into docs/archive

- fix remaining archive text garbling in two documents

2026-04-27 08:06:09 +08:00

21 KiB

Raw Blame History

InSAR 配对系统重构方案

更新日期：2026-04-13
状态：待实施
适用范围：Z:\Code\Insar_management_system_v2 当前代码基线

1. 文档目标

这份文档不是抽象算法说明，而是基于当前系统现状给出的可落地重构方案，目标是：

重构 D-InSAR 配对内核，解决当前正确性、稳定性和可维护性问题
尽量复用现有数据库自动维护、root/cursor 自维护、manifest inventory、自检面板
明确开发机条件下的迁移策略
为后续实现提供分阶段执行顺序、表设计、接口边界和验收口径

2. 当前系统基础与约束

2.1 当前可直接复用的系统能力

当前系统已经具备以下基础设施，重构应直接接入，而不是另起一套平行机制：

数据库启动自维护
- backend/app/db_maintenance.py
- ensure_database_ready() 会在启动时创建表、补缺列、应用 SQL migration，并可在开发机上按环境变量执行整库 schema reset
root 与 cursor 自维护
- backend/app/services/root_registry_service.py
- 启动时会根据 .env 自动同步 managed_roots 与 scan_cursors
manifest inventory 自维护
- backend/app/services/manifest_inventory_service.py
- 会维护 path_inventory、scan_cursors.last_seen_*、fingerprint 与 root 缺失状态
结果目录自维护
- backend/app/services/dinsar_scan_service.py
- D-InSAR 统一扫描链路已经是“发布 -> manifest inventory -> catalog rebuild -> compat sync”
健康检查和一致性检查
- backend/app/services/health_service.py
- frontend/src/HealthCheckPanel.jsx
- 当前自检已包含：数据库 schema、worker、catalog、source roots、D-InSAR bridge、一致性统计、系统维护入口

2.2 当前配对系统的核心问题

现有配对系统的主要问题不是功能不够多，而是核心语义不稳定：

SQL 路径和 Python fallback 路径不是同一算法
同日影像会出现反向重复配对
start_date 在 SQL 主路径上已失效，但接口仍保留
star 策略没有固定参考像角色
sequential 对同日多景不稳定
all 策略排序与前端描述不一致
aoi_overlap_threshold=0 的语义前后端不一致
当前任务命名与配对唯一性混在一起，业务主键不稳定

2.3 当前系统约束

当前扫描模式是 manual-only，调度器默认关闭
- backend/app/scheduler.py
radar_data 是当前源影像事实表，配对系统必须以它为唯一源
dinsar_task_batches / dinsar_task_items 已经是生产任务落地表
result_products / dinsar_product_profiles 已经承担结果资产追踪
健康检查和统计接口已上线，新增配对系统状态应并入现有面板

3. 重构总目标

本轮重构的目标不是继续修补 find_dinsar_pairs_v2，而是将配对系统改造成四层结构：

影像事实层
配对指标缓存层
网络选择层
任务物化层

核心原则：

候选对生成与网络选择分层
所有策略共享同一候选池
所有配对方向统一规范化
所有结果可追溯到策略版本、参数快照和候选边来源
不再保留“算法不等价的 fallback”

4. 目标架构

4.1 Layer A：影像事实层

沿用现有 radar_data 表作为唯一源影像事实表。

重构要求：

radar_data.id 继续作为数据库主键
引入明确的场景业务键 scene_uid
- 优先复用 radar_data.unique_id
- 若历史数据存在 unique_id 缺失或不稳定，启动时执行一次回填
- 回填规则：hash(normalized file_path)，并写入新列或标准化字段
所有配对相关对象都基于 scene_uid 或 radar_data.id 建立引用

建议：

本轮实现阶段直接在 radar_data 上新增：
- scene_uid
- scene_signature
- pairing_eligible
- pairing_updated_at
如果希望减少变更面，也可以只新增 scene_uid 与 pairing_updated_at

4.2 Layer B：配对指标缓存层

这是本次重构的核心。

目标：

将“任意两个影像是否可配、其基础指标是什么”从请求时临时计算，改为可维护的持久化缓存
缓存只保存与 AOI 无关的基础指标
AOI 相关指标在请求时动态叠加计算

建议新增表：

`pairing_metric_cache`

一行代表一个规范化后的影像对。

建议字段：

id
master_scene_ref_id
slave_scene_ref_id
master_scene_uid
slave_scene_uid
pair_uid
metric_version
orientation_rule_version
time_baseline_days
spatial_baseline_meters
scene_overlap_ratio
orbit_direction
same_satellite
same_imaging_mode
same_polarization
master_imaging_date
slave_imaging_date
master_satellite
slave_satellite
master_imaging_mode
slave_imaging_mode
master_polarization
slave_polarization
master_file_path
slave_file_path
status
computed_at

唯一约束：

unique(master_scene_ref_id, slave_scene_ref_id, metric_version)

关键约定：

master/slave 不是请求期可变概念，而是规范化方向
规范化规则：
- 早时间 = master
- 同时间时，较小 scene_uid 或较小 id = master

4.3 Layer C：缓存状态与脏队列

为了接入现有“自动维护 + 健康检查”体系，建议新增两张状态表。

`pairing_cache_state`

建议设计为单例表或按 cache_scope='global' 管理。

字段建议：

id
cache_scope
metric_version
status
scene_count
pair_count
dirty_scene_count
last_full_rebuild_at
last_incremental_reconcile_at
last_error
updated_at

状态建议：

READY
DIRTY
REBUILDING
DEGRADED
FAILED

`pairing_dirty_scenes`

用于增量维护。

字段建议：

id
scene_ref_id
scene_uid
reason
marked_at
resolved_at
status

唯一约束建议：

unique(scene_ref_id, status='PENDING') 或代码层去重

4.4 Layer D：网络选择层

网络选择层不直接查 radar_data，而是查 pairing_metric_cache。

建议新增：

`pairing_network_runs`

代表一次配对请求或一次已保存的网络。

字段建议：

id
network_run_id
strategy
policy_version
request_hash
request_params_json
aoi_source
aoi_hash
aoi_summary_json
candidate_count
selected_edge_count
warning_count
status
fallback_used
created_by
created_at

`pairing_network_edges`

代表某个网络 run 选中的边。

字段建议：

id
network_run_ref_id
metric_cache_ref_id
edge_rank
selection_reason
selection_score
selection_meta_json
is_reference_edge
created_at

唯一约束：

unique(network_run_ref_id, metric_cache_ref_id)

4.5 Layer E：任务物化层

当前 dinsar_task_batches / dinsar_task_items 可继续保留。

但建议增加可追溯字段：

在 dinsar_task_items 上新增：

network_run_id
network_edge_id
policy_version
selection_strategy
scene_pair_uid

在结果侧建议同步补充：

result_products.pair_key 继续保留
在 dinsar_product_profiles 或 params_json 中补充：
- network_run_id
- network_edge_id
- policy_version
- master_scene_uid
- slave_scene_uid

这样最终可以把：

配对网络
任务项
生产结果

串成一条可追踪链路。

5. 配对算法设计

5.1 候选对生成

候选对生成只负责回答：

这两个场景在基础事实上是否可配
基础指标是什么

不负责回答：

用什么策略选
最后是否进入任务

基础硬约束：

master != slave
方向规范化后只保留一个方向
同轨向
日期格式合法
几何相交

基础指标：

time_baseline_days
spatial_baseline_meters
scene_overlap_ratio

注意：

same_satellite
same_imaging_mode
same_polarization

只作为缓存事实，不在缓存层提前删边，以便不同请求复用同一缓存。

5.2 请求期过滤

请求期过滤发生在 pairing_metric_cache 之上：

time_baseline_min/max
spatial_baseline_max_meters
overlap_threshold
allowed_satellites
cross_satellite_pairing
require_same_imaging_mode
require_same_polarization
master_date_from/to
slave_date_from/to
aoi_overlap_threshold

AOI 处理原则：

AOI 不进入持久化 pair cache 主键
AOI 相关 overlap 在请求时动态计算
0 不再表示数值阈值，而统一转成 null
前后端统一语义：
- null = 不启用 AOI 覆盖阈值
- 0 < x <= 1 = 启用阈值

5.3 四种策略的正式定义

`all`

返回全部合法候选边
排序统一为稳定顺序：
- master_imaging_date
- slave_imaging_date
- selection_score desc
- pair_uid

不再使用“数据库返回顺序”作为结果语义。

`sequential`

基于稳定时间序列排序构图
排序键：
- acquisition_time_utc
- 无则 imaging_date
- 再无则 scene_uid
每景连接后续 N 景
同日多景必须稳定，不允许受候选池原始顺序影响

`star`

参考像必须固定角色
本系统建议统一采用：
- 参考像始终为 master
若物理上参考像日期晚于目标像，则在选择层进行拒绝或显式反转并记录相位方向规则

本轮建议：

为降低复杂度，先采用“参考像必须是 master”的严格规则
如果用户选择的参考像晚于部分场景，则这些边不入网，并给出 warning

`sbas`

本轮不采用“简单按 overlap 贪心去重”的旧实现。

建议目标：

图连通
每景至少达到最小连接数
时间覆盖尽量连续
每景度数受控，避免过密
AOI 覆盖尽量多样

可落地实现：

从合法候选边中先构造基础时间邻接骨架
保证每个场景至少连接前后最近邻
再按综合评分补边
每补一条边，对已覆盖区域施加惩罚
达到目标连通性和最大边数后停止

综合评分建议：

selection_score = w_time * time_score + w_spatial * spatial_score + w_overlap * overlap_score + w_aoi * aoi_gain - w_redundancy * redundancy_penalty

5.4 删除旧 fallback 的原则

本轮不再保留“Python 语义独立 fallback”。

替代方案：

候选边缓存是主路径
如果缓存不存在或脏数据过多：
- 返回明确的 DEGRADED / DIRTY 状态
- 允许管理员触发重建
- 或在安全阈值内自动执行增量重建

也就是说：

可以有“降级状态”
不能再有“悄悄换算法”

6. 与现有扫描和自动维护机制的集成

6.1 源影像扫描后的集成点

当前源影像扫描入口：

backend/app/services/data_service.py::scan_radar_data
backend/app/scheduler.py::scan_data_job

建议改造：

在 scan_radar_data() 中，对新增、更新、删除的 radar_data 记录执行：

标记 pairing_dirty_scenes
更新 pairing_cache_state.status = DIRTY
根据变更规模决定是否立即增量重建

建议阈值：

变更场景数 <= SMALL_RECONCILE_LIMIT
- 扫描结束后直接执行增量 reconcile
变更场景数 > SMALL_RECONCILE_LIMIT
- 仅标脏，不在扫描链路内同步重建
- 由管理员在自检面板手动触发

这与当前 manual-only 模式兼容，不依赖后台常驻调度器。

6.2 启动期自维护

当前启动期会执行：

ensure_database_ready()
root_registry_service.sync_from_settings()
manifest_inventory_service.sync_manifest_roots()
catalog bootstrap
health check

建议新增启动动作：

pairing_service.bootstrap_pairing_cache_state()

只做轻量检查：

新表是否存在
是否有缓存状态行
metric_version 是否匹配当前版本
dirty scene 是否堆积

不建议启动即全量重建，避免启动时间失控。

6.3 数据库自动维护策略

当前数据库自维护具备两个模式：

常规模式：建表、补列、应用 migration
开发机强制 reset 模式：整库 schema reset

由于本轮是配对内核重构，且当前是开发机，推荐采用：

6.4 migration 文件策略

当前 db_maintenance.py 中 migration 顺序为：

001_st_intersection_agg.sql
002_spatial_functions.sql
003_pairing_enhancement.sql

建议新增：

004_pairing_refactor.sql

该 migration 负责：

创建新 pairing 表
创建必要索引
创建候选边计算函数或 SQL helper view
如有需要，保留旧函数为 deprecated wrapper

建议：

不要在 004 里继续强化 find_dinsar_pairs_v2
将旧函数标记 deprecated，仅作为过渡壳
新逻辑直接走新 service + 新表

7. 自检与一致性检测升级

7.1 Health 接口扩展

当前健康检查聚合点：

backend/app/services/health_service.py::get_health_status

建议新增检查项：

`pairing_system`

字段建议：

ok
status
metric_version
scene_count
pair_count
dirty_scene_count
network_run_count_last_7d
last_full_rebuild_at
last_incremental_reconcile_at
last_error
duplicate_reverse_pair_count
orphan_metric_scene_ref_count
task_without_network_ref_count
result_without_pair_trace_count

判定规则建议：

READY 且无关键异常 -> ok=true
DIRTY 但 dirty 数量较少 -> ok=false，级别 warn
存在重复反向边、孤儿引用、版本漂移 -> ok=false，级别 error

7.2 Health 面板扩展

当前 HealthCheckPanel.jsx 已能展示结构化卡片。

建议新增卡片：

配对系统

展示内容：

缓存状态
指标版本
场景数 / 缓存对数
dirty scene 数
最近全量 / 增量时间
关键错误数

操作按钮建议：

增量修复配对缓存
全量重建配对缓存
清理旧网络记录

7.3 Statistics 接口扩展

当前 /statistics 已承担一致性统计角色。

建议追加：

pairing_consistency

字段建议：

metric_cache_count
duplicate_reverse_pair_count
invalid_orientation_count
network_edge_orphan_count
task_orphan_count
result_trace_missing_count

8. API 重构计划

8.1 后端接口

当前接口：

POST /api/find-pairs

建议分两阶段改造。

Phase 1：保持前端可用

保留：

POST /api/find-pairs

但内部改为：

从 pairing_metric_cache 查询
选择网络
返回 network_run_id + pairs

Phase 2：正式 API

新增：

POST /api/pairing/preview
POST /api/pairing/networks/{network_run_id}/materialize-batch
POST /api/pairing/reconcile-dirty
POST /api/pairing/rebuild-cache
GET /api/pairing/health
GET /api/pairing/networks/{network_run_id}

8.2 请求模型

PairingRequest 应清理为正式语义：

删除 start_date
aoi_overlap_threshold 前端空值统一传 null
strategy 继续保留：
- all
- sequential
- star
- sbas
reference_image_id 仅在 star 时有效

8.3 返回模型

建议新增返回字段：

network_run_id
policy_version
candidate_count
selected_edge_count
degraded
warnings

9. 前端改造计划

涉及文件：

frontend/src/components/PairingModal.jsx
frontend/src/hooks/usePairingLogic.js
frontend/src/store/pairingStore.js

改造原则：

前端不再承载配对语义补丁
所有“0 表示不限”“默认排序说明”等语义统一交回后端协议
结果列表显示：
- network_run_id
- strategy
- policy_version
- warning

界面调整建议：

all 策略文案改为“全部合法候选边，按稳定顺序展示”
star 明确说明“参考像固定为主像”
sequential 明确说明“同日多景按稳定键排序”
AOI 覆盖阈值为空时传 null

10. 旧代码处理策略

10.1 可以删除的内容

在新缓存路径稳定后，可以删除：

spatial_service.find_dinsar_pairs() 中当前 Python fallback
旧 _apply_star_strategy() 非固定角色实现
旧 start_date 兼容逻辑

10.2 需要保留过渡一段时间的内容

旧前端 find-pairs 调用入口
旧 task_alias / pair_key 命名辅助

但注意：

命名只能作为展示与兼容字段
不能继续作为算法主键

11. 实施阶段划分

Phase 0：开发机切换准备

确认当前开发机允许 DB reset
记录 .env 中路径配置
保留现有 managed_roots / path_inventory / manifest publish 目录，不做文件层清理
准备新 migration 与 ORM

验收：

可以安全启动一次 schema reset

Phase 1：数据模型落地

新增 pairing 相关 ORM
新增 004_pairing_refactor.sql
接入 ensure_database_ready()
建立 pairing_cache_state 初始化逻辑

验收：

后端启动后新表自动创建
健康检查不报 schema 错

Phase 2：候选缓存引擎

实现 pairing_metric_cache 全量构建
实现 pairing_dirty_scenes
在 scan_radar_data() 中接入 dirty 标记

验收：

能从 radar_data 构建稳定 pair cache
同日反向重复为 0

Phase 3：网络选择器

重写 all / sequential / star / sbas
删除算法不等价 fallback
为 find-pairs 接口切换到新内核

验收：

同一输入重复请求结果稳定
star 固定参考像角色
sequential 同日多景稳定

Phase 4：任务物化与结果追踪

dinsar_task_items 增加 network trace 字段
结果 manifest / product profile 补充配对追踪字段

验收：

任一结果可追溯到 network edge

Phase 5：自维护与自检

健康检查新增 pairing_system
Health 面板新增配对卡片与修复按钮
Statistics 新增 pairing consistency

验收：

能显示 dirty scene 数、缓存状态、重复边异常
能从 UI 触发增量修复与全量重建

Phase 6：清理旧逻辑

删除旧 fallback
删除 start_date
下线旧语义说明

验收：

配对链路只剩单一语义实现

12. 测试矩阵

本轮至少补以下自动化测试：

12.1 候选缓存层

同日双景只生成单方向边
同日多景生成顺序稳定
不同轨向不生成边
时间基线越界不入缓存

12.2 请求过滤层

allowed_satellites 生效
cross_satellite_pairing=false 生效
require_same_imaging_mode/polarization 生效
aoi_overlap_threshold=null 与 0.2 行为不同

12.3 策略层

all 顺序稳定
sequential 连接数正确
star 参考像固定为 master
sbas 至少满足基础连通性

12.4 集成层

扫描新增源影像后 dirty scene 正确增加
执行增量 reconcile 后 dirty scene 清零
find-pairs 返回 network_run_id
materialize-batch 后任务项带 network trace

12.5 自检层

重复边异常能被 health 检出
孤儿网络边能被 health 检出
任务无 network trace 能被 statistics 检出

13. 风险与取舍

13.1 本轮明确接受的取舍

开发机允许整库 reset
不迁移旧配对记录
不保留旧 fallback

13.2 需要重点控制的风险

首轮全量构建 pair cache 可能较慢
radar_data.unique_id 可能不稳定，需要一次性规范
旧结果如果缺少 trace 字段，需要通过 manifest/profile 尽可能补齐
若前端仍传 0，后端必须做强制归一化，不能再依赖 UI 自觉

14. 推荐实施顺序

建议严格按下面顺序推进：

先落表和缓存状态，不先改前端
再实现候选缓存和增量脏标记
再重写四种策略
再接任务物化追踪
最后接健康检查与自修复入口

不要反过来做：

不要先改 UI 文案
不要先修补 find_dinsar_pairs_v2
不要保留旧 fallback 到最后

15. 本轮结论

在当前代码基线上，最合理的重构路线不是继续维护“实时 SQL + Python fallback”模式，而是：

用 radar_data 作为唯一事实层
用 pairing_metric_cache 承载稳定候选对
用 pairing_network_runs / edges 承载策略结果
用 pairing_cache_state / dirty_scenes 承接自维护
用现有 HealthCheckPanel 和 /statistics 承接自检

这样做的直接收益是：

正确性可锁定
结果可追溯
与现有 DB 自维护、扫描链路、自检体系自然对接
后续再接 SBAS、跨卫星和多引擎生产时不会继续堆积配对债务

21 KiB Raw Blame History

InSAR 配对系统重构方案

1. 文档目标

2. 当前系统基础与约束

2.1 当前可直接复用的系统能力

2.2 当前配对系统的核心问题

2.3 当前系统约束

3. 重构总目标

4. 目标架构

4.1 Layer A：影像事实层

4.2 Layer B：配对指标缓存层

pairing_metric_cache

4.3 Layer C：缓存状态与脏队列

pairing_cache_state

pairing_dirty_scenes

4.4 Layer D：网络选择层

pairing_network_runs

pairing_network_edges

4.5 Layer E：任务物化层

5. 配对算法设计

5.1 候选对生成

5.2 请求期过滤

5.3 四种策略的正式定义

all

sequential

star

sbas

5.4 删除旧 fallback 的原则

6. 与现有扫描和自动维护机制的集成

6.1 源影像扫描后的集成点

6.2 启动期自维护

6.3 数据库自动维护策略

推荐落地策略

6.4 migration 文件策略

7. 自检与一致性检测升级

7.1 Health 接口扩展

pairing_system

7.2 Health 面板扩展

7.3 Statistics 接口扩展

8. API 重构计划

8.1 后端接口

Phase 1：保持前端可用

Phase 2：正式 API

8.2 请求模型

8.3 返回模型

9. 前端改造计划

10. 旧代码处理策略

10.1 可以删除的内容

10.2 需要保留过渡一段时间的内容

11. 实施阶段划分

Phase 0：开发机切换准备

Phase 1：数据模型落地

Phase 2：候选缓存引擎

Phase 3：网络选择器

Phase 4：任务物化与结果追踪

Phase 5：自维护与自检

Phase 6：清理旧逻辑

12. 测试矩阵

12.1 候选缓存层

12.2 请求过滤层

12.3 策略层

12.4 集成层

12.5 自检层

13. 风险与取舍

13.1 本轮明确接受的取舍

13.2 需要重点控制的风险

14. 推荐实施顺序

15. 本轮结论

21 KiB

Raw Blame History

`pairing_metric_cache`

`pairing_cache_state`

`pairing_dirty_scenes`

`pairing_network_runs`

`pairing_network_edges`

`all`

`sequential`

`star`

`sbas`

`pairing_system`