chore: sync production runtime and docs

2026-04-25 15:02:40 +08:00
parent cb518b431f
commit 1e44101eb2
50 changed files with 8575 additions and 2177 deletions
@@ -0,0 +1,445 @@
+# ISCE2 生产可靠性加固设计 2026-04-24
+
+## 1. 背景
+
+当前 ISCE2 生产链路已经具备：
+
+- 统一的 WSL runtime 入口
+- 共享 conda 环境 `insar_wsl_v1`
+- 结果发布到 `D:\production_results`
+- 统一 catalog / 自检 / 运维面板
+
+但这条链路仍存在一个核心问题：
+
+系统现在更像是“子进程执行器”，还不是“结果可靠性交付器”。
+
+也就是说，当前成功判定主要依赖：
+
+- WSL runner 返回码是否为 `0`
+- 输出目录是否存在
+- 自动发布阶段是否“尝试过”
+
+这会导致几类假成功：
+
+1. ISCE2 子进程返回 `0`，但没有形成可发布的主产物，任务仍显示完成。
+2. 历史运行只留下目录和 `.dinsar_run.json`，但主产物已损坏或缺失，“只跑未完成” 仍会跳过。
+3. 运维自检用的是一套路径规则，真实运行用的是另一套路径规则，面板和实际行为可能不一致。
+
+本设计的目标不是重写 ISCE2 算法链，而是把 ISCE2 生产从“命令执行成功”收紧到“结果可验收、可发布、可重跑、可运维”。
+
+## 2. 本轮范围
+
+本轮只做可靠性加固，不做算法重写。
+
+### 纳入本轮
+
+- ISCE2 原生产结果的验收契约
+- “只跑未完成” 判定收紧
+- 自动发布阶段收紧
+- 健康检查与真实运行入口对齐
+- 文档、自检、日志字段同步
+
+### 暂不纳入本轮
+
+- stripmap/SNAPHU/PICKLE 恢复链的算法级改写
+- 与 ENVI/IDL 流水线逐步逐项数值对比
+- Gamma 生产实现细节
+- MintPy / 时序生产链的算法可靠性评估
+
+## 3. 当前问题拆解
+
+### 3.1 成功判定过宽
+
+当前 `backend/app/dinsar_engines/isce2_engine.py` 中，单对任务成功主要由 `rc == 0` 决定。
+
+现状后果：
+
+- 只要 runner 没报错，就写入 `.dinsar_run.json`
+- 只要 `output_dir` 被加入 `output_dirs`，后续任务层就进入自动发布
+- 自动发布即使 `processed == 0`，任务最终仍可标记为 `COMPLETED`
+
+这不符合“生产完成”的系统定义。
+
+### 3.2 未完成重跑判定过宽
+
+当前 `_has_completed_task_result()` 只看：
+
+- 历史 `run_dir`
+- `.dinsar_run.json`
+- `output_dir` 目录存在
+
+它不看：
+
+- 主产物是否存在
+- 主产物是否可读
+- 该结果是否满足发布器识别规则
+
+因此历史半成品会被误判为“已完成”。
+
+### 3.3 健康检查与真实运行入口不一致
+
+当前存在两套 stripmapApp 路径逻辑：
+
+- 健康检查依赖 `ISCE2_STRIPMAP_APP`
+- 真正运行时在 WSL 内通过 `import isce` 动态定位
+
+这会导致：
+
+- 面板报错但实际能跑
+- 面板通过但实际解释器/包位置已经漂移
+
+### 3.4 手工恢复链缺少显式边界
+
+当前 `run_lt1_dinsar_pipeline.py` 通过复制 `PICKLE` 中文件并改写 XML 来衔接：
+
+- `filter -> filter_high_band`
+- `unwrap -> ionosphere`
+
+这条链路短期可用，但它对 ISCE2 内部文件结构有隐含依赖。
+
+本轮不重写它，但必须把它从“隐式成功”改成“显式验收”。
+
+## 4. 目标状态
+
+ISCE2 生产链路调整后，系统对“完成”的定义变为：
+
+1. WSL runner 执行完成。
+2. 原生产物通过本地验收。
+3. 验收通过的产物可被统一发布器识别。
+4. 自动发布成功写入标准包。
+5. 自检面板能看到 runtime、native output、publish package 三层状态一致。
+
+换句话说：
+
+- `rc == 0` 只表示“执行成功”
+- “任务完成” 必须是“执行成功 + 产物验收成功 + 发布链成功”
+
+## 5. 具体改造方案
+
+### 5.1 新增 ISCE2 原生产物验收层
+
+新增一个独立验收模块，建议位置：
+
+- `backend/app/services/isce2_result_validator.py`
+
+职责：
+
+- 不参与计算
+- 不参与数据库写入
+- 只负责判断一个 `output_dir` 是否是“可发布、可交付”的 ISCE2 原生结果
+
+#### 输入
+
+- `output_dir`
+- `task_alias`
+- `engine_code`
+- `profile_code`
+- `run_key`
+
+#### 核心检查项
+
+必选检查：
+
+- `output_dir` 目录存在
+- 至少存在一个符合发布规则的主位移产物
+- 主产物文件大小大于 0
+- 主产物能被 GDAL 打开
+- 若存在配对的相干产品，则记录为辅助资产
+
+建议主产物识别规则直接复用发布器当前的规则，避免两套规则分叉：
+
+- `*_disp.tif`
+- 可选 `*_coh.tif`
+
+#### 输出结构
+
+返回统一 `acceptance_result`：
+
+```json
+{
+  "accepted": true,
+  "primary_file": "D:/.../Task_xxx_disp.tif",
+  "asset_files": [
+    "D:/.../Task_xxx_disp.tif",
+    "D:/.../Task_xxx_coh.tif"
+  ],
+  "issues": [],
+  "metrics": {
+    "primary_exists": true,
+    "primary_readable": true,
+    "asset_count": 2
+  }
+}
+```
+
+#### 运行时行为
+
+`isce2_engine.run()` 中：
+
+- `rc != 0` 直接失败
+- `rc == 0` 后必须执行验收
+- 只有 `accepted == true` 才计入 `pairs_processed`
+- 只有验收通过的 `output_dir` 才进入 `output_dirs`
+
+这样“runner 成功但没产物”的情况会被收口为失败。
+
+### 5.2 收紧 `.dinsar_run.json` 语义
+
+当前 `.dinsar_run.json` 只是运行元数据，需要补成“运行 + 验收”的统一侧写。
+
+本轮不改数据库表结构，先改 sidecar 内容。
+
+新增字段建议：
+
+```json
+{
+  "run_key": "run_xxx",
+  "engine_code": "isce2",
+  "profile_code": "lt1_stripmap",
+  "runtime_id": "isce2_runtime_v1",
+  "output_dir": "D:/.../native",
+  "acceptance": {
+    "accepted": true,
+    "accepted_at": "2026-04-24T15:00:00Z",
+    "primary_file": "D:/.../Task_xxx_disp.tif",
+    "asset_files": [
+      "D:/.../Task_xxx_disp.tif",
+      "D:/.../Task_xxx_coh.tif"
+    ],
+    "issues": [],
+    "metrics": {
+      "primary_exists": true,
+      "primary_readable": true,
+      "asset_count": 2
+    }
+  }
+}
+```
+
+原则：
+
+- `.dinsar_run.json` 不再只表示“跑过”
+- 它要能表达“验收通过 / 未通过”
+
+### 5.3 重写“只跑未完成”判定
+
+将 `_has_completed_task_result()` 调整为 `_has_accepted_task_result()`。
+
+新的跳过条件：
+
+1. 历史 run 的 `.dinsar_run.json` 存在
+2. `engine_code / profile_code` 匹配当前请求
+3. `acceptance.accepted == true`
+4. `acceptance.primary_file` 存在且可读
+
+只有满足以上条件，才视为“已完成”。
+
+#### 不再采用的旧判断
+
+- 仅凭 `output_dir` 存在
+- 仅凭 `.dinsar_run.json` 存在
+
+#### 这样做的效果
+
+- 目录空壳不会再被跳过
+- 历史损坏结果会重新进入生产
+- “只跑未完成” 的含义变成“只跳过已验收成功的对”
+
+### 5.4 自动发布阶段从“尽力而为”改为“交付闭环”
+
+当前自动发布逻辑即使 `processed == 0` 也只记日志。
+
+本轮改为：
+
+- 引擎层只把“已验收通过”的 `output_dir` 交给发布器
+- 任务层以“验收通过数量”作为发布期望值
+- 发布结果必须满足：
+  - `processed == accepted_output_count`
+  - `failed == 0`
+
+若不满足，则任务整体失败。
+
+#### 原则
+
+- 自动发布不再是可有可无的附属步骤
+- 对托管生产来说，发布成功是交付定义的一部分
+
+#### 失败语义
+
+若 native output 已验收通过，但标准包发布失败：
+
+- 任务状态标记为 `FAILED`
+- 保留 native output 目录
+- 日志明确写出：
+  - accepted count
+  - processed count
+  - failed count
+
+这样后续可以修发布器或手动重建 catalog，但不会再出现“任务完成却没有结果”的误导状态。
+
+### 5.5 健康检查与真实运行入口统一
+
+目标：只保留一套 runtime 事实来源。
+
+#### 调整方向
+
+`ISCE2_STRIPMAP_APP` 不再作为运行事实来源，只保留为兼容字段。
+
+健康检查改成：
+
+1. 从 `wsl_runtime_registry` 读取共享 Python
+2. 在对应 Python 中执行：
+
+```python
+import isce
+from pathlib import Path
+print(Path(isce.__file__).resolve().parent / "applications" / "stripmapApp.py")
+```
+
+3. 检查该路径是否存在
+4. 将解析出的真实路径回显到自检面板
+
+#### 自检项调整
+
+保留：
+
+- WSL 可用
+- 共享 Python 可执行
+- `import isce` 成功
+- stripmapApp 动态解析成功
+- runner 脚本存在
+
+弱化：
+
+- 直接检查 `.env` 中的 `ISCE2_STRIPMAP_APP`
+
+#### 自检返回建议新增字段
+
+- `resolved_stripmap_app`
+- `resolved_isce_package_path`
+- `python_matches_shared`
+- `runtime_id`
+
+### 5.6 数据库与自维护策略
+
+本轮尽量不动数据库 schema。
+
+原因：
+
+- 当前问题核心在文件系统验收语义，不在表结构
+- 用户已经明确要求兼容数据库自维护与自检
+- 现阶段没有必要为了可靠性问题引入一轮 schema 变更风险
+
+#### 本轮原则
+
+- 不新增非必要列
+- 先把验收信息写入 `.dinsar_run.json`
+- 数据库继续通过现有 `result_products / result_assets / result_issues` 表表达发布结果
+
+#### 若后续必须加列
+
+只允许：
+
+- nullable
+- 可由 `_add_missing_columns()` 自动补齐
+- 不要求清库
+
+但这不属于本轮必须项。
+
+### 5.7 运维自检扩展
+
+为避免“native 有结果但 publish 不一致”的灰区，本轮建议在健康面板新增两个聚合视角。
+
+#### 1. runtime 视角
+
+- 共享 distro / Python / stripmapApp 动态解析是否一致
+
+#### 2. product 视角
+
+- 已入库产品是否存在 `native_output_dir`
+- `native_output_dir` 是否仍存在
+- `manifest_path` 是否存在
+
+#### 3. 新增建议计数项
+
+- `missing_native_output_count`
+- `missing_manifest_count`
+- `missing_runtime_count`
+
+其中前两项已有基础，重点是让 ISCE2 runtime 检查结果和产品检查结果在面板里串起来。
+
+## 6. 文件落点
+
+### 核心代码
+
+- `backend/app/dinsar_engines/isce2_engine.py`
+- `backend/app/services/job_handlers.py`
+- `backend/app/services/result_catalog_service.py`
+- `backend/app/services/health_service.py`
+- `backend/app/services/wsl_service.py`
+
+### 新增模块
+
+- `backend/app/services/isce2_result_validator.py`
+
+### 文档与运维
+
+- `docs/ISCE2_PRODUCTION_RELIABILITY_HARDENING_DESIGN_20260424.md`
+
+## 7. 分阶段实施
+
+### Phase 1: 成功判定收口
+
+- 新增 `isce2_result_validator`
+- `rc == 0` 后执行验收
+- 未验收通过不写成功结果
+- `.dinsar_run.json` 补 `acceptance`
+
+### Phase 2: 重跑语义收口
+
+- `_has_completed_task_result()` 改为验收驱动
+- “只跑未完成” 只跳过已验收成功的结果
+
+### Phase 3: 发布闭环收口
+
+- 自动发布必须与验收通过数量对齐
+- `processed == 0` 不再仅告警，改为任务失败
+
+### Phase 4: 自检对齐
+
+- stripmapApp 改为动态解析检查
+- 面板展示 runtime 实际解析结果
+
+### Phase 5: 后续科学性加固
+
+不在本轮立即落地，但建议保留后续专题：
+
+- PIKCLE 恢复链版本敏感性评估
+- bbox / geoPosting 的科学性收紧
+- 与 ENVI/IDL 基线链的阶段性对比
+
+## 8. 验收标准
+
+改造完成后，至少满足以下场景：
+
+1. WSL runner 返回 `0`，但没有 `*_disp.tif`。
+   - 结果：任务失败，不得显示完成。
+
+2. 历史 run 目录仍在，但 `*_disp.tif` 已被删掉。
+   - 结果：`只跑未完成` 不应跳过，应重新生产。
+
+3. 健康面板显示 stripmapApp 路径。
+   - 结果：必须来自共享 Python 动态解析，不再依赖旧硬编码。
+
+4. native output 验收通过，但发布器没识别到包。
+   - 结果：任务失败，日志明确指出 publish mismatch。
+
+5. 自检面板与实际 runtime 使用的 Python / runner / runtime_id 一致。
+
+## 9. 本轮结论
+
+本轮实现不应该再把 ISCE2 生产理解为“跑完脚本”，而应理解为：
+
+“执行成功 -> 原生结果验收通过 -> 标准包发布成功 -> 系统完成交付”。
+
+先把这个闭环收紧，再谈后续算法科学性优化，顺序才是健康的。