Initial D-InSAR bundle restore tool

README.md

@@ -0,0 +1,243 @@
+# D-InSAR 去重源数据包恢复工具
+
+这个工具用于把“去重源数据包”恢复成传统 D-InSAR `Task_*` 目录结构。
+
+适合接收方在本地运行：选择一个 `BundleRoot` 输入目录，工具会按 `pairs.json` 中的配对关系，在输出目录中恢复每个 `Task_*`。
+
+## 产物
+
+当前提供两个 Windows 可执行文件：
+
+- `dinsar-restore.exe`：图形界面版，推荐普通用户双击使用。
+- `dinsar-restore-console.exe`：命令行版，适合脚本、批处理或自动化调用。
+
+Go 编译后的 exe 是单文件程序，不需要安装 Python，也不需要额外运行环境。
+
+## 输入目录格式
+
+输入目录应类似：
+
+```text
+BundleRoot/
+  data/
+    scene_<hash>_<source_name>/
+    ...
+  orbit/
+    orbit_<hash>_<orbit_name>.txt
+    ...
+  pairs.json
+  manifest.json
+```
+
+其中：
+
+- `pairs.json` 必须存在。
+- `data/` 必须存在。
+- `orbit/` 可以不存在；轨道文件缺失只会记录 warning，不会阻断恢复。
+
+## 输出目录格式
+
+恢复后输出目录类似：
+
+```text
+OutputRoot/
+  Task_YYYYMMDD_YYYYMMDD/
+    master/
+    slave/
+    orbit/
+    .dinsar_pair.json
+  restore_report.json
+  restore.log
+```
+
+Task 目录名优先使用：
+
+1. `task_alias`
+2. `task_name`
+3. `pair_id`
+
+## 图形界面用法
+
+双击运行：
+
+```text
+dinsar-restore.exe
+```
+
+操作流程：
+
+1. 点击输入目录的“选择...”按钮，选择 `BundleRoot`。
+2. 建议先点击“数据自检”。
+3. 点击输出目录的“选择...”按钮，选择 `OutputRoot`。
+4. 根据需要设置 `Dry run`、`覆盖已有 Task`、`Limit`。
+5. 点击“开始恢复”。
+6. 在运行日志区域查看进度、warning 和错误。
+
+### 数据自检
+
+“数据自检”只检查输入数据，不复制文件，也不会生成 `Task_*`。
+
+自检内容包括：
+
+- `pairs.json` 是否存在、是否能解析。
+- `data/` 是否存在。
+- 每个 pair 的 Task 目录名是否合法。
+- `master_data` 是否存在、是否为非空目录。
+- `slave_data` 是否存在、是否为非空目录。
+- 是否存在重复 Task 目录名。
+- `master_orbit` / `slave_orbit` 是否存在。
+
+注意：轨道文件缺失只记为 warning，不算失败。
+
+### 分批恢复
+
+如果数据量很大，可以用 `Limit` 分批执行。
+
+例如共有 1000 个 Task：
+
+1. 第一次设置 `Limit=200`，恢复 200 个。
+2. 第二次仍设置 `Limit=200`，工具会跳过已完成的 200 个，再恢复新的 200 个。
+3. 重复执行，直到全部完成。
+
+已完成 Task 的判断标准是：
+
+- `Task/master/` 存在且非空。
+- `Task/slave/` 存在且非空。
+
+已跳过的 Task 不会占用 `Limit` 数量。
+
+### 覆盖已有 Task
+
+默认情况下，已经完整恢复的 Task 会被跳过。
+
+如果勾选“覆盖已有 Task”，工具会删除并重建已有 Task 目录。这个选项适合重新生成结果，但使用前应确认输出目录中没有需要保留的手工文件。
+
+### Dry run
+
+勾选 `Dry run` 后，工具只打印计划，不复制文件。
+
+可以用它先确认将要恢复哪些 Task。
+
+## 命令行用法
+
+命令行版文件：
+
+```powershell
+.\dinsar-restore-console.exe
+```
+
+数据自检：
+
+```powershell
+.\dinsar-restore-console.exe --input D:\BundleRoot --check-only
+```
+
+正式恢复：
+
+```powershell
+.\dinsar-restore-console.exe --input D:\BundleRoot --output D:\OutputRoot
+```
+
+Dry run：
+
+```powershell
+.\dinsar-restore-console.exe --input D:\BundleRoot --output D:\OutputRoot --dry-run
+```
+
+覆盖已有 Task：
+
+```powershell
+.\dinsar-restore-console.exe --input D:\BundleRoot --output D:\OutputRoot --overwrite
+```
+
+分批恢复，每次最多恢复 200 个新 Task：
+
+```powershell
+.\dinsar-restore-console.exe --input D:\BundleRoot --output D:\OutputRoot --limit 200
+```
+
+## 参数说明
+
+| 参数 | 说明 |
+| --- | --- |
+| `--input` | 输入目录，即 `BundleRoot`。 |
+| `--output` | 输出目录，即 `OutputRoot`。`--check-only` 时可以不填。 |
+| `--check-only` | 只做数据自检，不恢复文件。 |
+| `--dry-run` | 只打印恢复计划，不复制文件。 |
+| `--limit N` | 本次最多恢复 N 个新 Task。已跳过的 Task 不计入数量。 |
+| `--overwrite` | 删除并重建已有 Task。 |
+| `--skip-existing` | 跳过已完成 Task，默认开启。通常不需要手动设置。 |
+
+`--overwrite` 和显式设置的 `--skip-existing` 不能同时使用。
+
+## 输出文件
+
+正式恢复后，输出目录会生成：
+
+- `restore.log`：人类可读日志。
+- `restore_report.json`：机器可读恢复报告。
+- 每个 `Task_*` 内的 `.dinsar_pair.json`：该 Task 对应的 pair 元信息。
+
+`restore_report.json` 示例：
+
+```json
+{
+  "started_at": "2026-05-11T00:00:00Z",
+  "finished_at": "2026-05-11T00:10:00Z",
+  "input_root": "D:\\BundleRoot",
+  "output_root": "D:\\OutputRoot",
+  "total_pairs": 1000,
+  "restored": 200,
+  "skipped": 0,
+  "failed": 0,
+  "warnings": []
+}
+```
+
+## 重新编译
+
+需要 Go 1.22 或更高版本。
+
+图形界面版：
+
+```powershell
+go build -ldflags "-H=windowsgui" -o dinsar-restore.exe .
+```
+
+命令行版：
+
+```powershell
+go build -o dinsar-restore-console.exe .
+```
+
+运行测试：
+
+```powershell
+go test ./...
+```
+
+## 发布建议
+
+建议 GitHub Release 附带以下文件：
+
+- `dinsar-restore.exe`
+- `dinsar-restore-console.exe`
+- `README.md`
+
+Release 标题示例：
+
+```text
+D-InSAR Restore Tool v0.1.0
+```
+
+Release 说明可写：
+
+```text
+Initial release.
+
+- Add Windows GUI restore tool.
+- Add console restore tool.
+- Add data self-check before restore.
+- Support batch continuation with Limit.
+- Generate restore_report.json and restore.log.
+```