GF3_L1A_To_L2_pipeline/docs/data_management_upgrade_plan.md

GF3 数据管理升级方案

本文档记录 GF3 L1A 到 L2 管线升级为数据管理系统的设计方向。当前仓库已经包含两条处理路径：

• SARscape Go wrapper：面向 Windows、ENVI/IDL Runtime 和 SARscape 的生产处理路径。
• Python pipeline：基于 GDAL/Rasterio/NumPy 的纯 Python 处理路径。

后续业务不再只是单批次 L1A 处理。输入可能已经是 L2，也可能是 L1A；卫星平台可能是 GF3、GF3B、GF3C；数据需要被发现、登记、查询、调度、归档和复跑。因此建议把项目从“处理脚本”升级为“产品识别 + 数据库存档 + 处理任务编排 + 执行器”的结构。

目标

1. 统一识别 GF3、GF3B、GF3C 产品。
2. 同时管理 L1A 原始产品和 L2 成果产品。
3. 尽量从压缩包名或文件名中解析产品基本信息，包括中心经纬度。
4. 用数据库记录产品、任务、产物和失败原因，避免只依赖目录结构。
5. 保留现有 SARscape Go wrapper 作为生产执行器，避免一次性重写稳定处理链。
6. 为后续 Web 管理界面、地图查询、批处理调度、报表导出预留数据模型。

总体架构

输入目录 / NAS / 历史输出
        |
        v
产品发现与命名解析
        |
        v
产品库 SQLite
        |
        +--> L2 产品登记、索引、查询
        |
        +--> L1A 待处理任务生成
                 |
                 v
          执行器调度层
                 |
                 +--> SARscape Go wrapper
                 +--> Python pipeline
                 |
                 v
          L2 产物登记和任务状态更新

产品识别模型

建议新增统一产品模型，例如 ProductInfo：

字段	说明
product_id	产品唯一标识，优先使用产品号或完整场景名
scene_name	不含压缩包扩展名的场景名
satellite	GF3、GF3B、GF3C
level	L1A、L2，必要时扩展到其他级别
mode	成像模式，例如 FSI、FSII 等
polarizations	标准化后的极化列表，例如 HH,HV
acquisition_date	成像日期
center_lon	从文件名或元数据解析的中心经度
center_lat	从文件名或元数据解析的中心纬度
source_type	archive、metadata_xml、directory、sarscape_product
source_path	当前发现的源路径
metadata_path	元数据 XML 路径，未解压时可为空
archive_path	压缩包路径，非压缩产品可为空
size_bytes	文件或目录大小
mtime	源数据最后修改时间
checksum	可选，后续用于完整性校验
status	discovered、registered、processing、processed、failed、archived

产品识别应允许“文件名解析先行，元数据补全兜底”。压缩包尚未解压时，系统也应能建立基本索引；等需要处理或做精确校验时，再从 metadata XML 补充字段。

文件名解析

现有样例：

GF3_MH1_FSII_051377_E132.3_N48.2_20260514_L1A_HHHV_L10007356478.tar.gz

可解析为：

字段	值
satellite	GF3
mode	FSII
center_lon	132.3
center_lat	48.2
acquisition_date	2026-05-14
level	L1A
polarizations	HH,HV
product_id	L10007356478

解析规则建议：

1. 卫星字段匹配 GF3、GF3B、GF3C。
2. 经度匹配 E132.3 或 W132.3，转换为正负浮点数。
3. 纬度匹配 N48.2 或 S48.2，转换为正负浮点数。
4. 日期匹配连续 8 位数字，并转换为 YYYY-MM-DD。
5. 级别匹配 L1A、L2，后续可扩展。
6. 极化字段支持 HH、HV、VH、VV 及组合字段，例如 HHHV。
7. 解析失败不能阻止登记，应记录 parse_status 和 parse_message。

GF3B/GF3C 的命名如果与 GF3 不完全一致，应通过多个 parser 版本兼容，而不是把所有规则压进一个不可维护的正则。

数据库设计

第一阶段建议使用 SQLite。它部署简单、便于随仓库工具使用，也能支撑批量目录索引和本地管理。未来如果需要多用户并发或 Web 服务，可以迁移到 PostgreSQL/PostGIS。

products

记录发现到的 L1A、L2 和其他可识别产品。

字段	类型	说明
id	INTEGER PRIMARY KEY	内部 ID
product_id	TEXT	产品号或业务唯一标识
scene_name	TEXT	场景名
satellite	TEXT	GF3/GF3B/GF3C
level	TEXT	L1A/L2
mode	TEXT	成像模式
polarizations	TEXT	逗号分隔的极化
acquisition_date	TEXT	ISO 日期
center_lon	REAL	中心经度
center_lat	REAL	中心纬度
source_type	TEXT	archive/metadata_xml/directory/sarscape_product
source_path	TEXT UNIQUE	源路径
metadata_path	TEXT	元数据路径
archive_path	TEXT	压缩包路径
size_bytes	INTEGER	大小
mtime	TEXT	修改时间
checksum	TEXT	可选校验
parse_status	TEXT	ok/partial/failed
parse_message	TEXT	解析说明
created_at	TEXT	入库时间
updated_at	TEXT	更新时间

processing_tasks

记录 L1A 到 L2 的处理任务。

字段	类型	说明
id	INTEGER PRIMARY KEY	任务 ID
input_product_id	INTEGER	输入产品
output_product_id	INTEGER	输出产品，可为空
executor	TEXT	sarscape_go 或 python_gdal
status	TEXT	pending/running/succeeded/failed/skipped
requested_polarizations	TEXT	请求处理的极化
dem_path	TEXT	DEM 路径
output_dir	TEXT	输出目录
attempt_count	INTEGER	尝试次数
started_at	TEXT	开始时间
finished_at	TEXT	结束时间
error_message	TEXT	失败原因
config_json	TEXT	处理参数快照

artifacts

记录最终成果、中间成果、日志和快视图。

字段	类型	说明
id	INTEGER PRIMARY KEY	产物 ID
product_id	INTEGER	所属产品
task_id	INTEGER	所属任务
artifact_type	TEXT	geo/sml/hdr/quicklook/log/intermediate
polarization	TEXT	HH/HV/VH/VV
path	TEXT UNIQUE	文件路径
size_bytes	INTEGER	文件大小
mtime	TEXT	修改时间
is_final	INTEGER	是否最终交付成果

CLI 演进

建议在现有 gf3-l1a2l2 CLI 下新增 inventory 和 tasks 子命令：

gf3-l1a2l2 inventory init --db .\gf3_inventory.sqlite
gf3-l1a2l2 inventory scan --input D:\GF3 --db .\gf3_inventory.sqlite
gf3-l1a2l2 inventory list --level L1A --satellite GF3B --db .\gf3_inventory.sqlite
gf3-l1a2l2 inventory export --format geojson --output scenes.geojson --db .\gf3_inventory.sqlite

gf3-l1a2l2 tasks create-l2 --input-query "level=L1A,status=registered" --output E:\GF3\L2 --db .\gf3_inventory.sqlite
gf3-l1a2l2 tasks run --executor sarscape_go --db .\gf3_inventory.sqlite
gf3-l1a2l2 tasks retry --failed --db .\gf3_inventory.sqlite

Go wrapper 可以保留现在的命令行接口，同时后续增加一种任务配置输入：

gf3wrapper.exe -task task_123.json

这样数据库调度层负责生成标准任务文件，Go wrapper 只负责稳定执行 SARscape 处理。

L1A 与 L2 的处理策略

输入类型	策略
L1A 压缩包	登记产品；如缺 L2，则生成处理任务
L1A 解压目录	登记产品；可直接进入处理任务
L1A metadata XML	登记产品；以所在目录作为场景目录
L2 SARscape 输出	登记最终产物；不再重复处理
L2 压缩包或目录	登记为 L2 产品；解析中心点和时间后进入可查询状态
无法识别数据	记录为 parse_status=failed，留给人工处理

对于已经存在的 L2 数据，系统应优先入库并校验完整性，而不是重新从 L1A 处理。完整性校验可以沿用现有 Go wrapper 的思路：最终 *_geo.sml 和匹配主数据文件必须存在且非空。

执行器边界

SARscape Go wrapper

继续作为生产主执行器。后续增强重点：

1. 处理完成后校验请求极化的最终 *_geo.sml 和主数据文件。
2. 若 IDL/SARscape 只打印错误但进程返回 0，仍应根据产物校验判定失败。
3. -keep-extracted 需要真正控制 .gf3_extract 是否保留。
4. 输出任务结果 JSON，便于数据库层读取。

Python pipeline

继续作为可测试、可扩展的备用执行器。后续增强重点：

1. 增加 inventory 数据模型和扫描命令。
2. 解压失败应进入任务失败状态，而不只是写日志。
3. 明确 HH/HV/VH/VV 支持范围，与 SARscape 路径保持文档一致。
4. 补充发现、解压、命名解析、任务状态的单元测试。

分阶段实施计划

阶段 1：产品识别和解析

• 新增产品模型。
• 新增文件名 parser。
• 覆盖 GF3、GF3B、GF3C、L1A、L2、E/W/N/S 坐标测试。
• 新增 inventory scan 的只读扫描能力，不改变现有处理链。

阶段 2：SQLite 产品库

• 新增数据库初始化和 upsert。
• 扫描目录后写入 products。
• 支持按卫星、级别、日期、中心点范围查询。
• 支持 CSV/GeoJSON 导出。

阶段 3：任务管理

• 新增 processing_tasks 和 artifacts。
• 根据 L1A 产品和缺失 L2 的条件生成任务。
• 记录失败原因、重试次数和处理参数。
• 处理已有 L2 产品的入库和完整性校验。

阶段 4：执行器整合

• 数据库层调用 SARscape Go wrapper 或 Python pipeline。
• Go wrapper 输出结构化结果。
• 处理完成后自动登记 L2 产物和日志。
• 支持断点续跑和失败重试。

阶段 5：管理界面和报表

• 增加简单 Web UI 或桌面管理工具。
• 支持地图查看中心点。
• 支持按日期、卫星、级别、状态筛选。
• 支持导出批处理报告和归档清单。

当前仓库需要优先修正的点

1. Python 测试需要标准化运行方式。当前直接运行 python -m unittest discover -s tests 时，src/ 不在 import path 中。
2. Python 环境文件已有依赖，但当前系统 Python 未安装 pytest。应在 README 中强调使用 Conda 环境或 editable install。
3. Go wrapper 的 -keep-extracted 当前主要是配置字段，后续应补实际行为。
4. SARscape/IDL 脚本失败是否能反映到进程退出码需要验证，建议增加处理后产物完整性校验。
5. 现有未跟踪的目录报告 docs/20260514_directory_report.md 可以作为真实输出组织结构参考，确认后再决定是否纳入版本库。