18 KiB
18 KiB
洪涝监测模块整改实施方案
日期：2026-05-14
目标：将当前分散的水体监测、洪涝检测、GF3 处理和结果管理，收敛为可部署、可维护、可扩展的洪涝灾害分析流水线。
1. 总体原则
- 新业务统一走
/flood/*。 - “水体监测”不再作为独立业务模块出现，只作为“洪涝灾害分析 -> 水体提取”步骤存在。
/water/*暂时保留兼容窗口，但标记 deprecated，不再新增功能。- 数据库优先新增表和回填数据，避免直接破坏旧表。
- 每个阶段独立提交，保证任一阶段都能构建、部署和回滚。
2. 目标流水线
场景准备 Scene
-> 水体提取 WaterExtraction
-> 洪涝检测 FloodDetection
-> 套合分析 FloodOverlay
-> 洪涝产品 FloodProduct / Report
其中水体提取是洪涝分析的前置步骤，不再和洪涝灾害分析并列成两个业务入口。
3. 阶段 1：收敛 API 契约
目标：先消灭“前端调用不存在接口”的问题，避免部署后出现静默 404。
修改范围：
frontend/src/api/flood.js
backend/app/routers/flood.py
docs/FLOOD_MODULE_REFACTOR_PLAN_20260514.md
处理方式：
frontend/src/api/flood.js只暴露后端当前真实支持的接口。- 暂时移除或注释未实现接口，例如
/flood/sources、/flood/ready-products、/flood/pairs保存删除、/flood/reports、/flood/results。 - 后端
/flood路由继续保留现有功能，但接口命名统一为preprocess、scenes、water-extractions、pairs/search、detections、detections/{id}/preview/{layer}。
验收标准：
npm run build 通过
前端 flood API 文件中没有明显会 404 的已导出函数
/flood 主流程现有功能不退化
4. 阶段 2：新增数据模型
目标：建立洪涝流水线需要的数据承载，不直接破坏旧表。
新增模型：
WaterExtractionORM -> water_extractions
FloodOverlayORM -> flood_overlays
FloodProductORM -> flood_products
关键取舍：
- 保留旧
WaterDetectionORM -> water_detections。 - 新表
water_extractions从旧表回填。 - 后续新任务写入
water_extractions。 - 旧接口读旧表或兼容映射，等稳定后再清理。
建议字段：
water_extractions:
id
scene_id
processor
task_id
input_path
output_path
preview_path
vector_path
water_area_km2
water_pixel_count
threshold_value
metadata_json
status
error_msg
created_at
updated_at
flood_overlays:
id
detection_id
flood_vector_path
hazard_points_hit
hazard_points_near
hazard_points_total
dinsar_products_intersecting
affected_area_km2
summary_json
created_at
flood_products:
id
product_id
detection_id
overlay_id
display_name
status
publish_dir
manifest_path
summary_json
created_at
验收标准：
alembic upgrade head 成功
旧 water_detections 数据可迁移到 water_extractions
模型 import 正常
5. 阶段 3：抽离 Service
目标：让 /flood 成为真正的业务路由，而不是代理 water.py 的壳。
新增服务：
backend/app/services/flood_analysis_service.py
backend/app/services/water_extraction_service.py
backend/app/services/flood_product_service.py
backend/app/services/flood_overlay_service.py
职责划分：
flood_analysis_service.py
场景列表、预处理提交、配对搜索、洪涝检测提交、检测列表
water_extraction_service.py
Otsu 水体提取、ENVI/SARscape 水体提取
flood_product_service.py
产品列表、manifest、产品包生成
flood_overlay_service.py
分类栅格矢量化、灾害点/DInSAR/AOI 套合
完成后：
backend/app/routers/flood.py不再import water as water_compat。backend/app/routers/water.py标记 deprecated，后续可反向调用新 service。water_detect_service.py逐步迁移到water_extraction_service.py。
验收标准：
flood.py 不再 import water.py
/water/* 旧接口仍可用
/flood/* 主接口可用
6. 阶段 4：补齐产品端点
目标：让“结果与任务”视图有真实后端数据。
主接口建议使用 products，避免和 DInSAR result/product 概念混淆：
POST /flood/detections/{id}/products
GET /flood/products
GET /flood/products/{id}
GET /flood/products/{id}/manifest
兼容别名可选：
GET /flood/results
GET /flood/results/{id}
GET /flood/results/{id}/manifest
验收标准：
前端结果视图能展示真实产品
manifest 能返回 JSON
没有空接口或静默失败
7. 阶段 5：实现套合分析
目标：把洪涝模块从检测工具提升为灾害分析模块。
新增接口：
POST /flood/detections/{id}/overlay
GET /flood/detections/{id}/impact
处理逻辑：
1. 读取 flood_detections.classified_path
2. 提取 class=2 洪涝区域
3. 栅格转矢量
4. 写 flood_overlays.flood_vector_path
5. 查询灾害点命中
6. 查询近邻风险点
7. 查询相交 DInSAR 产品
8. 查询 AI 诊断摘要
9. 写 summary_json
注意：
- AOI、PostGIS、DInSAR 产品几何不完整时，不让整个任务失败。
- 返回部分结果，并在
summary_json.warnings中说明缺失项。
验收标准：
POST overlay 能生成 flood_overlays 记录
GET impact 返回结构化 JSON
没有数据时返回空数组而不是 500
8. 阶段 6：前端重整
目标：只保留一个洪涝灾害分析工作台。
新增目录：
frontend/src/components/flood/
建议组件：
FloodStatusBadge.jsx
FloodButton.jsx
FloodSceneRow.jsx
FloodWaterExtractionRow.jsx
FloodDetectionRow.jsx
FloodOverlayPanel.jsx
FloodProductPanel.jsx
界面改成四站式：
1. 场景准备
2. 水体提取
3. 洪涝检测
4. 套合与产品
处理方式：
WaterMonitorPanel.jsx加弃用提示。- 左侧导航只引导用户进入洪涝灾害分析。
api/water.js和api/gf3.js标记 deprecated。- 新功能只接入
api/flood.js。
验收标准：
左侧导航只引导用户进入洪涝灾害分析
水体提取不再作为独立业务重复出现
套合分析和产品视图接真实接口
npm run build 通过
9. 阶段 7：报告生成壳
目标：先形成 Markdown 报告能力，再扩展 PDF。
新增接口：
POST /flood/reports
GET /flood/reports/{id}
第一版报告包含：
灾前/灾后场景信息
洪涝面积
灾害点命中
DInSAR 产品关联
AI 诊断摘要
套合统计
10. 推荐提交顺序
1. refactor flood api contract
2. add flood pipeline orm models
3. extract flood analysis services
4. add flood product endpoints
5. implement flood overlay impact analysis
6. consolidate flood frontend workspace
7. scaffold flood report generation
核心思路：先稳住接口和数据，再拆服务，再补业务能力，最后整理 UI。这样 Git 中的代码、迁移、前端调用和部署环境是闭合的，另一台服务器拉取后不会出现关键页面依赖未实现接口的问题。
11. 2026-05-15 补充设计：水体提取、灾害配对与套合展示
本节根据最新审阅意见补充。结论：洪涝工作台不应该继续以“手动选日期范围 + 查配对”为核心，而应该改成“灾害事件驱动”：
灾害时间 + 灾害位置
-> 过滤可用 SAR 场景匹配池
-> 推荐灾前/灾后配对
-> 执行洪涝检测
-> 套合分析
-> 结果展示与产品导出
11.1 水体提取视图复用管理页能力
当前管理页面已经具备三类能力，洪涝模块应复用，而不是重新做一套弱化版：
- 雷达数据查询能力：
/radar-data/search已支持成像日期、成像模式、极化方式、产品级别、行政区 AOI、上传 AOI 文件。 - 地图能力：
App.jsx中已经有源影像 footprint 上图、源影像预览缓存radar-data/{id}/thumb、地图定位和图层开关逻辑。 - 行政区 AOI 能力：
/aoi/regions/children与/aoi/regions/{treeId}/geometry已可用于按省/市范围查询和定位。
因此水体提取界面调整为：
左侧：场景匹配池
- 灾害位置 / AOI
- 成像日期范围
- 卫星、模式、极化、产品级别
- 只显示有 footprint 的数据
- 可显示源影像预览图
- 显示成像时间、极化方式、成像模式、产品级别
右侧：已完成地理编码场景 / 水体提取结果
- 场景 footprint 上图
- 水体提取掩膜上图
- 与源影像预览可叠加对比
前端复用建议：
复用 buildRadarSearchFormData / normalizeRadarSearchCriteria
复用 UnifiedDatePicker
复用 RadarDataRow 的预览状态表达
复用 App.jsx 中 updateRadarPreviewVisibility 的源影像预览图层逻辑
复用行政区 AOI 选择和地图定位逻辑
需要新增的洪涝专用组件：
FloodSourceSearchPanel.jsx
封装灾害位置、日期、极化、模式、产品级别过滤。
FloodSourceSceneRow.jsx
显示源影像：成像时间、极化方式、模式、产品级别、预览状态、上图按钮。
FloodWaterExtractionRow.jsx
显示水体提取结果：面积、状态、输入场景、上图按钮、错误信息。
地图图层约定：
source_preview:{radar_data_id} 源影像预览
source_footprint:{radar_data_id} 源影像覆盖范围
scene_footprint:{scene_id} 地理编码场景范围
water_mask:{water_extraction_id} 水体提取掩膜
11.2 洪涝检测配对改为灾害事件驱动
当前 /flood/pairs/search 只接收灾前/灾后日期区间和 overlap 阈值，实际使用体验不够：用户通常知道的是“灾害发生时间”和“灾害位置”，不是一开始就知道灾前灾后影像窗口。
新的配对入口应改为：
灾害名称 disaster_name 可选
灾害时间 disaster_date 必填
灾害位置 disaster_aoi 必填，来自行政区 / 地图框选 / 上传 SHP / GeoJSON
灾前窗口 pre_window_days 默认 30 天
灾后窗口 post_window_days 默认 30 天
最小 AOI 覆盖率 min_aoi_coverage_ratio 默认 0.3
最小两景重叠率 min_pair_overlap_ratio 默认 0.5
是否要求同极化 require_same_polarization 默认 true
是否要求同成像模式 require_same_imaging_mode 默认 false
卫星过滤 satellites 可选
极化过滤 polarization 可选
前端交互：
1. 用户选择灾害日期
2. 用户选择灾害位置
- 行政区：省 / 市
- 地图框选：后续实现
- 上传 SHP/GeoJSON：沿用现有 AOI 解析
3. 系统自动推导：
- 灾前窗口：disaster_date - pre_window_days 至 disaster_date - 1
- 灾后窗口：disaster_date 至 disaster_date + post_window_days
4. 后端返回：
- pre_pool
- post_pool
- candidate_pairs
- warnings
5. 用户在候选配对中选择一组提交洪涝检测
推荐新增接口：
POST /flood/disaster-pairs/search
请求格式：
{
"disaster_name": "汶川洪涝",
"disaster_date": "20260715",
"aoi_geojson": {},
"region_tree_id": "510000",
"pre_window_days": 30,
"post_window_days": 30,
"min_aoi_coverage_ratio": 0.3,
"min_pair_overlap_ratio": 0.5,
"require_same_polarization": true,
"require_same_imaging_mode": false,
"satellites": ["LT-1", "GF3"],
"polarization": "VV"
}
返回格式：
{
"disaster": {
"name": "汶川洪涝",
"date": "20260715",
"pre_range": ["20260615", "20260714"],
"post_range": ["20260715", "20260814"]
},
"aoi": {
"source": "region",
"name": "汶川县",
"aoi_geojson": {}
},
"pre_pool": [],
"post_pool": [],
"candidate_pairs": [
{
"pre": {
"scene_id": 1,
"radar_data_id": 10,
"imaging_date": "20260701",
"satellite": "LT-1",
"polarization": "VV",
"imaging_mode": "SM",
"aoi_coverage_ratio": 0.82,
"coverage_polygon": []
},
"post": {
"scene_id": 2,
"radar_data_id": 11,
"imaging_date": "20260718",
"satellite": "LT-1",
"polarization": "VV",
"imaging_mode": "SM",
"aoi_coverage_ratio": 0.79,
"coverage_polygon": []
},
"pair_overlap_ratio": 0.91,
"pre_delta_days": 14,
"post_delta_days": 3,
"score": 0.86,
"warnings": []
}
],
"warnings": []
}
排序建议：
score =
pair_overlap_ratio * 0.35
+ min(pre_aoi_coverage, post_aoi_coverage) * 0.30
+ time_score * 0.20
+ same_polarization_bonus * 0.10
+ same_mode_bonus * 0.05
后端实现建议：
1. 复用 radar search 的 AOI 解析能力，避免重复解析行政区和 SHP。
2. 查询 sar_scene_geo.status=DONE 的场景，并 join radar_data。
3. 按 disaster_date 自动构造灾前/灾后窗口。
4. 用 PostGIS 计算单景 AOI 覆盖率。
5. 用 footprint 相交面积计算 pair_overlap_ratio。
6. 返回匹配池和候选配对，而不是只返回最终 pairs。
兼容处理：
旧接口 POST /flood/pairs/search 保留，但只作为手动日期模式。
新工作台默认使用 POST /flood/disaster-pairs/search。
11.3 套合分析结果展示逻辑
套合分析不能只是一个“运行按钮”。它应展示“为什么这个洪涝结果重要”：
洪涝范围
灾害点命中
近洪涝风险点
DInSAR 产品关联
行政区影响统计
结果图层
产品/报告入口
前端 FloodOverlayPanel.jsx 设计：
顶部摘要：
- 洪涝面积
- 命中灾害点数量
- 近洪涝风险点数量
- 关联 DInSAR 产品数量
- warnings 数量
中部地图控制：
- 洪涝分类图
- 洪涝矢量范围
- 命中灾害点
- 近洪涝风险点
- DInSAR 产品 footprint
下部结果表：
- 灾害点列表：名称、类型、行政区、距离、是否命中
- DInSAR 产品列表：product_id、engine、形变量、AI 风险等级、预览/详情
- AOI 统计：行政区、洪涝面积、占比
后端 GET /flood/detections/{id}/impact 应保证即使没有运行套合，也返回稳定结构：
{
"detection_id": 1,
"flood_area_km2": 12.5,
"hazard_points": {
"inside_flood": [],
"near_flood": [],
"total_in_scene": 0
},
"dinsar_products": [],
"affected_aois": [],
"map_layers": {
"classified_preview": true,
"flood_vector_path": null,
"hazard_points": true,
"dinsar_footprints": true
},
"warnings": []
}
需要新增或完善的地图层约定：
flood_classified:{detection_id} 洪涝分类栅格预览
flood_vector:{overlay_id} 洪涝矢量面
hazard_inside:{overlay_id} 洪涝范围内灾害点
hazard_near:{overlay_id} 近洪涝风险点
dinsar_intersect:{overlay_id} 相交 DInSAR 产品 footprint
11.4 前端整改顺序调整
基于以上补充，前端整改顺序调整为：
1. 抽 FloodSourceSearchPanel，复用管理页雷达搜索/AOI 查询。
2. 水体提取页增加源影像预览图、成像时间、极化方式、模式、产品级别。
3. 洪涝检测页改为灾害事件输入：灾害时间 + 灾害位置。
4. 新增 /flood/disaster-pairs/search 后接入候选池和推荐配对。
5. 套合分析页接入 /flood/detections/{id}/overlay 和 /impact。
6. 结果与任务页从 flood_detections 过渡到 flood_products。
验收标准补充：
水体提取：
- 能按行政区/上传 AOI 查询源影像
- 能显示源影像预览图
- 列表中显示成像日期、极化方式、成像模式、产品级别
- 水体提取结果可叠加到地图
洪涝检测：
- 用户只需输入灾害时间和灾害位置即可获得匹配池
- 返回 pre_pool/post_pool/candidate_pairs
- 推荐配对可在地图上预览灾前/灾后 footprint
- 配对结果显示时间差、AOI 覆盖率、两景重叠率、极化一致性
套合分析：
- 运行后能看到摘要指标
- 能看到灾害点命中和近邻风险点列表
- 能看到关联 DInSAR 产品列表
- warnings 可见，不静默失败
12. 2026-05-15 第一轮落地记录
本轮先闭合三条可直接使用的业务链路，不把报告生成和完整产品包导出放进同一次改动。
12.1 已落地
后端：
1. 新增 POST /flood/disaster-pairs/search。
输入 disaster_date + region_tree_id/aoi_geojson + 灾前灾后窗口。
输出 pre_pool、post_pool、candidate_pairs、summary、warnings。
2. 水体提取列表补充源影像元数据。
/flood/scenes 与 /flood/water-extractions 现在返回 imaging_date、polarization、
imaging_mode、product_level、coverage_polygon、min/max lon/lat。
3. 套合分析接口保持并接入前端。
POST /flood/detections/{id}/overlay
GET /flood/detections/{id}/impact
前端：
1. 洪涝灾害分析 / 水体提取页：
- 复用 AOI 行政区索引。
- 支持按行政区筛选雷达源影像。
- 雷达结果行增加“覆盖”和“源影像”上图。
- 场景/水体结果行显示成像日期、极化方式、模式、产品级别。
2. 洪涝检测页：
- 从手工填写灾前/灾后日期，改为输入灾害名称、灾害发生日期、灾害位置。
- 自动根据窗口期生成灾前池和灾后池。
- 候选配对展示评分、AOI 覆盖率、两景重叠率、灾前/灾后时间差、极化方式。
3. 套合分析页：
- 可运行 overlay。
- 可刷新并展示 impact。
- 展示洪涝面积、命中灾害点、近洪涝风险点、关联 DInSAR 产品和 warnings。
12.2 当前保留的兼容点
1. GET/POST /water/* 暂未删除，旧页面仍可过渡使用。
2. 旧 POST /flood/pairs/search 保留为手工日期兼容接口，但新工作台默认使用 /flood/disaster-pairs/search。
3. 水体提取任务底层仍写 water_detections；water_extractions 新表和正式迁移已建模，但任务处理器尚未完全切换。
4. AOI 只先复用行政区查询；上传 SHP/GeoJSON 到洪涝工作台可作为下一步补充。
12.3 下一轮建议
1. 把水体提取 job handler 从 WaterDetectionORM 切到 WaterExtractionORM。
2. 给候选配对增加地图 footprint 预览按钮，辅助人工确认灾前/灾后覆盖。
3. 把 overlay 生成的 flood_vector_path 也作为地图矢量层显示。
4. 套合分析补行政区受影响面积统计。
5. 结果与任务页开始接 flood_products，而不是只列 flood_detections。