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
parent 5a0623fd9b
commit d108b33f80
26 changed files with 487 additions and 27 deletions
@@ -0,0 +1,393 @@
+# WSL2 + ISCE2 + MintPy SBAS 集成方案
+
+Updated: 2026-04-12
+
+## 1. 背景
+
+当前仓库已经具备 SBAS/PS-InSAR 的部分系统骨架：
+
+- 已有 `ps_timeseries_runs` 业务表与基础 API
+- 已有 `prepare -> stack_prep_initial -> materialize -> stack_prep_refresh` 四步 workflow
+- 已有 `psinsar.publish.v1` manifest 解析与 `psinsar` catalog
+- 已有 `ps_production`、`ps_products`、`psinsar_results` 前端入口
+
+同时，实验层已经验证：
+
+- LT-1 stack 可以在 WSL2 `Ubuntu-24.04` 下跑通到 `run_08_igram`
+- MintPy SBAS 可以产出 `timeseries.h5`、`velocity.h5`
+- geocode/export 可以产出 `psinsar.publish.v1` publish bundle
+- 统一环境 `isce2_mintpy_v1` 可以同时导入 `isce` 与 `mintpy`
+
+因此当前最合理的工作不是重写处理算法，而是把已经验证过的 WSL2 运行链稳定接入现有系统。
+
+## 2. 本机环境核对
+
+本方案基于 2026-04-12 的本机实际核对结果。
+
+### 2.1 WSL2 发行版
+
+- 可见发行版：
+  - `Ubuntu`
+  - `Ubuntu-24.04`
+- SBAS 集成目标发行版：
+  - `Ubuntu-24.04`
+
+### 2.2 已确认 conda 环境
+
+- `isce2`
+  - Python:
+    - `/home/administrator/miniconda3/envs/isce2/bin/python`
+  - 可导入：
+    - `isce`
+- `mintpy`
+  - Python:
+    - `/home/administrator/miniconda3/envs/mintpy/bin/python`
+  - 可导入：
+    - `mintpy`
+- `isce2_mintpy_v1`
+  - Python:
+    - `/home/administrator/miniconda3/envs/isce2_mintpy_v1/bin/python`
+  - 可导入：
+    - `isce`
+    - `mintpy`
+
+### 2.3 当前判断
+
+- `isce2_mintpy_v1` 已满足“单环境跑 stack + MintPy”的基础条件
+- 现有 `isce2` 环境仍应保留给当前 D-InSAR 生产链
+- 运行时不应依赖交互式 `sudo`
+  - 所有系统依赖、conda 环境、脚本权限应在部署阶段一次性准备完成
+
+## 3. 设计结论
+
+### 3.1 主方案
+
+SBAS 系统集成默认采用：
+
+- WSL distro:
+  - `Ubuntu-24.04`
+- runtime env:
+  - `isce2_mintpy_v1`
+
+### 3.2 备用方案
+
+保留实验期的双环境桥接链路作为 fallback：
+
+- `isce2`
+  - 负责 ISCE2 stack
+- `mintpy`
+  - 负责 MintPy SBAS
+
+但 fallback 不应作为系统默认路径，只在统一环境故障时使用。
+
+### 3.3 产品边界
+
+系统正式接入边界固定为 publish bundle：
+
+- `manifest.json`
+- `assets/`
+- `preview/`
+- `metadata/`
+
+系统不直接把以下目录视为正式产品：
+
+- `stack_work/`
+- `mintpy_sbas_*`
+- `Igrams/`
+- 其他中间目录
+
+## 4. 现状与缺口
+
+### 4.1 已完成
+
+- 运行记录模型：
+  - `ps_timeseries_runs`
+- 基础生产 API：
+  - `timeseries-production`
+- 基础产品 API：
+  - `ps-products`
+- `psinsar` catalog 解析与重建
+- 前端生产页、产品页、结果页入口
+
+### 4.2 未完成
+
+当前系统还没有把下面四步接入正式 workflow：
+
+1. `run_isce2_stack`
+2. `run_mintpy_sbas`
+3. `export_publish_bundle`
+4. `register_psinsar_product`
+
+这意味着当前系统是“桥接层已接入”，但还不是“完整自动生产闭环”。
+
+## 5. 目标架构
+
+```text
+Windows FastAPI / Worker
+  -> submit run / record metadata / monitor progress
+  -> dispatch WSL jobs
+  -> register publish bundle into psinsar catalog
+  -> serve API to frontend
+
+WSL2 Ubuntu-24.04
+  -> ISCE2 stripmapStack execution
+  -> MintPy SBAS inversion
+  -> geocode / export / preview generation
+  -> build manifest.json
+
+Formal Product Boundary
+  -> PSINSAR_PRODUCT_DIR/<product_id>/
+     manifest.json
+     assets/
+     preview/
+     metadata/
+```
+
+设计原则：
+
+- 系统负责编排，不负责重计算
+- WSL2 负责执行，不负责业务登记
+- 正式产品只认 publish bundle
+- D-InSAR 与 SBAS 运行时保持隔离
+
+## 6. 推荐 workflow
+
+### 6.1 Phase 1 已有步骤
+
+1. `prepare_stack_input`
+2. `build_stack_prep_initial`
+3. `materialize_stack_scenes`
+4. `refresh_stack_ready`
+
+### 6.2 需要新增的正式步骤
+
+5. `run_isce2_stack`
+   - 在 `Ubuntu-24.04` 中执行生成的 `run_01` 至 `run_08_igram`
+   - 产出 `Igrams/`、`geom_reference/`、`baselines/`
+
+6. `run_mintpy_sbas`
+   - 在 `isce2_mintpy_v1` 中执行 MintPy SBAS
+   - 产出：
+     - `timeseries.h5`
+     - `velocity.h5`
+     - `temporalCoherence.h5`
+     - `maskTempCoh.h5`
+
+7. `export_publish_bundle`
+   - geocode
+   - GeoTIFF 导出
+   - 生成预览图
+   - 生成 `manifest.json`
+
+8. `register_psinsar_product`
+   - 将 publish bundle 复制或落到正式 `PSINSAR_PRODUCT_DIR`
+   - 增量登记到 `psinsar` catalog
+
+## 7. 后端设计
+
+### 7.1 配置项
+
+建议显式配置以下参数，不再依赖默认继承：
+
+```dotenv
+TIMESERIES_ENABLED=true
+TIMESERIES_WSL_DISTRO=Ubuntu-24.04
+TIMESERIES_ENV_NAME=isce2_mintpy_v1
+TIMESERIES_PYTHON=/home/administrator/miniconda3/envs/isce2_mintpy_v1/bin/python
+TIMESERIES_WORK_ROOT=<windows path>
+TIMESERIES_DEM_PATH=<windows path>
+TIMESERIES_ORBIT_POOL_ISCE2=<windows path>
+TIMESERIES_EXPERIMENT_ROOT=<repo>/experiments/isce2_sbas_timeseries
+TIMESERIES_STACK_PREP_SCRIPT=<repo>/experiments/isce2_sbas_timeseries/scripts/build_lt1_stack_prep.py
+TIMESERIES_MATERIALIZE_SCRIPT=<repo>/experiments/isce2_sbas_timeseries/scripts/materialize_lt1_stack_scenes.py
+PSINSAR_PRODUCT_DIR=<formal publish root>
+```
+
+关键要求：
+
+- `TIMESERIES_ENV_NAME` 与 `TIMESERIES_PYTHON` 必须指向同一环境
+- 不再让 `TIMESERIES_PYTHON` 默认继承 `ISCE2_PYTHON`
+
+### 7.2 模块拆分
+
+建议新增或补强以下模块：
+
+- `timeseries_paths.py`
+  - 统一维护 Windows/WSL 路径转换
+  - 统一生成 work/publish/logs 路径
+
+- `timeseries_runtime_service.py`
+  - 统一执行 WSL 命令
+  - 统一处理 timeout、stdout/stderr、返回码
+
+- `isce2_stack_runtime_service.py`
+  - 封装 `run_01` 至 `run_08_igram` 执行
+
+- `mintpy_runtime_service.py`
+  - 封装 MintPy SBAS 运行
+  - 封装统一环境 runner
+
+- `psinsar_publish_service.py`
+  - 封装 export/publish bundle 生成
+  - 封装产品落库前的目录检查
+
+### 7.3 建议新增 job types
+
+- `TIMESERIES_ISCE2_STACK_RUN`
+- `TIMESERIES_MINTPY_SBAS_RUN`
+- `TIMESERIES_EXPORT_PUBLISH`
+- `TIMESERIES_REGISTER_PRODUCT`
+
+当前已有：
+
+- `TIMESERIES_PREPARE`
+- `TIMESERIES_STACK_PREP`
+- `TIMESERIES_MATERIALIZE`
+
+### 7.4 运行记录要求
+
+`ps_timeseries_runs` 至少应稳定记录：
+
+- `wsl_distro`
+- `env_name`
+- `python_path`
+- `work_root`
+- `publish_dir`
+- `manifest_path`
+- `reference_date`
+- `stack_dates`
+- `dem_path`
+- `orbit_pool`
+- `water_mask_mode`
+- `step logs`
+- `quality summary`
+- `command snapshots`
+
+目标不是“只知道跑过”，而是“知道当时用什么环境、什么 DEM、什么 orbit、怎么跑出来的”。
+
+## 8. 结果目录与 catalog 策略
+
+### 8.1 正式产品目录
+
+正式产品目录统一使用：
+
+- `PSINSAR_PRODUCT_DIR`
+
+实验目录：
+
+- `experiments/.../publish/...`
+
+只作为验证来源，不应继续充当正式产品根目录。
+
+### 8.2 推荐策略
+
+第一阶段先支持两种接入方式：
+
+1. `import_experiment_bundle`
+   - 将已有实验成功 bundle 导入正式产品目录
+   - 用于快速验证 catalog 和前端显示
+
+2. `publish_from_workflow`
+   - 由 workflow 自动生成 bundle 并注册
+   - 作为正式闭环目标
+
+### 8.3 catalog 设计要求
+
+`psinsar_catalog_service` 建议补充：
+
+- 单 manifest 增量注册
+- 单产品刷新
+- publish 目录健康检查
+- run_id 到 product_id 的稳定关联
+
+## 9. 前端设计
+
+### 9.1 `ps_production`
+
+第一阶段重点不是分析，而是运维可用：
+
+- 显示 WSL/环境状态
+- 显示 workflow 步骤状态
+- 显示 stdout/stderr 日志位置
+- 失败后支持步骤级重试
+- 成功后跳转到产品详情
+
+### 9.2 `ps_products`
+
+第一阶段重点：
+
+- list/filter
+- 查看 manifest
+- 查看 preview
+- 手动 rebuild catalog
+- 从 run 跳到 product
+
+### 9.3 `psinsar_results`
+
+第一阶段继续复用 catalog 只读视图即可。
+
+### 9.4 `psinsar_analysis`
+
+继续预留，不在当前阶段展开。
+
+## 10. 稳定性约束
+
+必须遵守以下边界：
+
+- 不修改当前 D-InSAR 的默认 `ISCE2_PYTHON`
+- 不把当前 D-InSAR 脚本改指向 `isce2_mintpy_v1`
+- 不让业务层代码直接拼 `/mnt/z`
+- 不把 `MintPy` 工作目录直接暴露为正式产品
+- 不依赖交互式 `sudo`
+
+## 11. 推荐实施顺序
+
+### Phase A
+
+先做“实验成果纳入系统”：
+
+- 支持导入已有 experiment publish bundle
+- 落到正式 `PSINSAR_PRODUCT_DIR`
+- 让 catalog 和前端先可见
+
+### Phase B
+
+再做“完整 WSL2 自动执行闭环”：
+
+- 接入 `run_isce2_stack`
+- 接入 `run_mintpy_sbas`
+- 接入 `export_publish_bundle`
+- 接入 `register_psinsar_product`
+
+### Phase C
+
+最后做“生产级稳定化”：
+
+- 失败重试
+- 恢复执行
+- 健康检查
+- 环境快照
+- provenance 补齐
+
+## 12. 验收标准
+
+达到以下条件后，才算 SBAS 正式接入完成：
+
+1. 系统可从一个已有 `PS stack batch` 发起 SBAS 运行。
+2. Worker 可在 `Ubuntu-24.04` 中自动驱动 ISCE2 stack。
+3. Worker 可在 `isce2_mintpy_v1` 中自动驱动 MintPy。
+4. 系统可自动生成 publish bundle。
+5. bundle 可自动注册到 `psinsar` catalog。
+6. 前端可查看运行状态、产品列表、preview 和 manifest。
+7. 失败步骤可重试，且不会污染现有 D-InSAR 生产链。
+
+## 13. 当前推荐
+
+当前最稳的方向是：
+
+- 继续以 `isce2_mintpy_v1` 作为 SBAS 主运行时
+- 保留 `isce2` 与 `mintpy` 双环境桥接链路作为 fallback
+- 先把 experiment publish bundle 纳入正式系统
+- 再补自动执行后四步
+
+这条路线最符合当前仓库状态，也最符合“稳定优先、不破坏现有 D-InSAR”的约束。