Improve pairing planning and statistics visibility

2026-07-07 01:04:47 +08:00
parent 2da2121829
commit 36a406ae49
22 changed files with 2085 additions and 459 deletions
@@ -0,0 +1,63 @@
+# D-InSAR Province Coverage Pairing Design
+
+Date: 2026-07-06
+
+## Goal
+
+Provide a planning mode for near-term province-wide D-InSAR delivery. The user enters a target production time range as the scene pool and selects a province/AOI. The system builds standard D-InSAR candidate pairs, then greedily selects pairs that add the most new AOI spatial coverage. The time range is a freshness/pool constraint, not the primary coverage objective.
+
+## Scope
+
+- Reuse `pairing_metric_cache` as the only candidate source.
+- Keep the existing standard D-InSAR thresholds: temporal baseline, overlap, center distance, same mode, same polarization, same family, orbit availability.
+- Add a planning endpoint that returns normal `RadarPair` rows, so existing pair list, batch save, copy, and production flow remain unchanged.
+- Store the selected network through `pairing_network_runs` / `pairing_network_edges` for traceability.
+
+## Greedy Policy
+
+1. Build candidate windows from `master_imaging_date` to `slave_imaging_date`.
+2. Start with the requested target window.
+3. Query candidates in the target pool plus `extension_days`.
+4. When an AOI is available, prefer candidates that add new uncovered AOI area.
+5. Use target-window temporal coverage as a secondary score and diagnostic.
+6. Score each candidate:
+   - new AOI area covered
+   - total AOI area covered by the pair
+   - new target days covered
+   - existing target coverage overlap
+   - scene overlap ratio
+   - D-InSAR quality score
+   - shorter temporal baseline and smaller center distance as tie-breakers
+7. Select the best edge, mark covered AOI area and days, then repeat until:
+   - AOI area has no meaningful new coverage candidates
+   - no candidate adds coverage
+   - `max_pairs` is reached
+
+## Coverage Semantics
+
+Coverage here means AOI spatial coverage when an AOI is supplied. Temporal coverage is reported separately to show whether the selected pairs span the requested production window. For province-wide use, the user must select the province AOI and set an AOI overlap threshold appropriate for production planning.
+
+## API
+
+`POST /pairing/coverage-plan`
+
+Form fields:
+
+- `target_date_from`, `target_date_to`: required `YYYYMMDD`
+- standard pairing fields: `time_baseline_min`, `time_baseline_max`, `overlap_threshold`, `spatial_baseline_max_meters`, `aoi_overlap_threshold`, `allowed_satellites`
+- `extension_days`: default 15
+- `max_pairs`: default 200
+- `require_orbit_data`: default true
+- `files` or `aoi_geojson`: optional AOI, same as `/find-pairs`
+
+Response:
+
+- `pairs`: selected `RadarPair` rows
+- `coverage`: requested range, effective query range, covered days, coverage ratio, uncovered ranges
+- `warnings`, `network_run_id`, `candidate_count`, `selected_edge_count`
+
+## Notes
+
+- This is a planning tool, not a new production engine.
+- Existing batch splitting remains the operational control for producing 100-by-100 or any user-selected batch size.
+- Produced pairs should still be filtered in the pair list by existing result status indicators before batch creation.