Apply current workspace changes

2026-04-22 01:52:21 +08:00
parent cf34b9a8ed
commit cb518b431f
449 changed files with 92252 additions and 321 deletions
@@ -0,0 +1,601 @@
+# PyINT + Gamma 集成总体设计
+
+**日期**: 2026-04-18  
+**状态**: 总体设计  
+**范围**: D-InSAR 生产引擎接入、Gamma 精配对接入、配置管理、数据库策略、运维自检、前端入口
+
+## 1. 结论
+
+本次集成建议采用两条并行但相互衔接的路线：
+
+1. 将 `PyINT` 作为新的 D-InSAR 生产引擎接入现有多引擎框架，统一走现有任务队列、运行日志、结果登记与结果目录治理链路。
+2. 将 `Gamma` 配对能力接入现有“配对基础 -> 配对规划 -> 生产执行”链路，作为数据库粗配对结果之上的精化步骤，而不是替换当前配对基础缓存。
+
+核心判断如下：
+
+- `PyINT` 更适合作为“受控外部引擎”集成，而不是直接作为后端内部 Python 库深度嵌入。
+- `Gamma` 精配对是可集成的，但更适合针对“已经筛出的场景集合/网络运行”做二次优化，不适合直接取代当前全库候选对缓存。
+- 一期集成建议不强制修改数据库主结构；优先复用现有 `pairing_network_runs` / `pairing_network_edges` 的 JSON 承载精配对元数据。
+- 如果二期需要对 Gamma 精配对历史做独立检索、统计和运维闭环，再引入单独迁移文件，并通过现有数据库自维护机制自动落库。
+
+## 2. 现状与约束
+
+### 2.1 当前系统已有基础
+
+- 已有 D-InSAR 多引擎抽象：`backend/app/dinsar_engines/base.py`
+- 已有引擎注册表：`backend/app/dinsar_engines/registry.py`
+- 已有生产任务接口与队列：`backend/app/routers/dinsar_production.py`
+- 已有配对基础缓存、网络运行与边追踪：
+  - `backend/app/models/orm.py`
+  - `backend/app/services/pairing_cache_service.py`
+  - `backend/app/services/pairing_state_service.py`
+  - `backend/app/services/spatial_service.py`
+- 已有数据库自维护与 SQL 迁移自动执行：`backend/app/db_maintenance.py`
+- 已有运维自检面板与健康检查汇总：`backend/app/services/health_service.py`、`frontend/src/HealthCheckPanel.jsx`
+- 已有生产页与配对规划页：
+  - `frontend/src/DinsarProductionPanel.jsx`
+  - `frontend/src/panels/PairPlanningPanel.jsx`
+
+### 2.2 PyINT 项目特征
+
+从 `D:\Code\PyINT` 现状看，`PyINT` 不是干净的 SDK，而是以模板和脚本为中心的流程编排层：
+
+- 主入口为 `pyint/pyintApp.py`
+- 配对能力入口为 `pyint/select_pairs.py`
+- 严重依赖环境变量：
+  - `SCRATCHDIR`
+  - `TEMPLATEDIR`
+  - `DEMDIR`
+- 运行方式偏 Linux / WSL，广泛调用外部命令与 GAMMA CLI
+- 更适合作为“流程执行器”被调用，而不是被后端直接 import 后逐步复用内部函数
+
+### 2.3 明确约束
+
+- 本机只有一个 WSL 环境，不需要设计多 distro 调度系统。
+- 系统级 Windows Python 解释器已经在根 `.env` 中维护，可复用，不应再为 PyINT 额外复制一套 Windows Python 配置。
+- 管理员口令不应进入设计文档、代码或 `.env.example`。权限控制继续复用现有登录态与管理员角色校验。
+- 现有运维自检面板已经较重，PyINT/Gamma 的“操作入口”不应继续堆在健康检查页里。
+
+## 3. 总体集成架构
+
+### 3.1 总体原则
+
+- 不新建平行子系统，优先复用现有引擎、作业、配对、结果目录与目录扫描体系。
+- 不改变现有 `pairing_metric_cache.spatial_baseline_meters` 的语义。
+- 不把 Gamma 精配对结果直接覆盖数据库粗配对缓存。
+- 运维页只看状态，实际操作放在生产页与配对规划页。
+
+### 3.2 架构分层
+
+#### A. 生产引擎层
+
+新增 `pyint` 引擎，挂到现有 `registry` 中，与 `sarscape` / `isce2` / `landsar` 并列。
+
+#### B. WSL 执行适配层
+
+新增受控执行服务，负责：
+
+- 读取 `.env` 配置
+- 复用现有 WSL 命令执行与路径转换能力
+- 组装 `PyINT` 所需环境变量
+- 生成模板文件和运行目录
+- 执行 `PyINT` 包装脚本
+- 将输出归一化到系统现有结果结构
+
+#### C. 配对精化层
+
+保留现有数据库候选对缓存与网络运行。
+
+在此基础上新增“Gamma 精配对”步骤：
+
+1. 先由当前配对接口生成候选网络
+2. 再将该网络对应场景集送入 Gamma / PyINT 配对流程
+3. 生成新的精化网络结果
+4. 前端允许用户查看并选择使用精化后的网络结果
+
+#### D. 结果治理层
+
+PyINT/Gamma 原始工作目录不直接作为系统正式结果。
+
+必须经过适配层输出统一结果包，保证继续兼容：
+
+- 结果目录扫描
+- 结果目录发布
+- 结果目录桥接一致性
+- 预览图/缩略图生成
+- AI 诊断与 catalog 追踪
+
+## 4. PyINT 生产引擎设计
+
+### 4.1 目标
+
+目标不是把 `PyINT` 原封不动暴露给用户，而是把它包装成当前系统理解的“一个可选生产引擎”。
+
+### 4.2 推荐实现方式
+
+新增以下后端组件：
+
+- `backend/app/dinsar_engines/pyint_engine.py`
+- `backend/app/services/pyint_service.py`
+- `backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py`
+
+职责划分：
+
+- `pyint_engine.py`
+  - 实现 `DinsarEngine`
+  - 暴露 `engine_code=pyint`
+  - 提供可用性检查、处理 profile、参数 schema
+- `pyint_service.py`
+  - WSL 执行
+  - 路径转换
+  - 模板写入
+  - 环境变量组装
+  - 烟测检查
+- `run_lt1_pyint_pipeline.py`
+  - 作为受控包装脚本在 WSL 中运行
+  - 负责把系统已有 `Task_*` / 配对任务目录映射成 PyINT 项目工作区
+  - 调用 `pyintApp.py` 或更细粒度子脚本
+  - 收集输出并生成系统结果清单
+
+### 4.3 与当前生产链路的关系
+
+沿用现有生产链路：
+
+`前端生产页 -> /dinsar-production/run -> job queue -> pyint_engine.run() -> WSL -> PyINT -> 统一结果包 -> catalog/scan`
+
+这样做的收益：
+
+- 不需要新增独立任务中心
+- 不需要新增另一套运行日志
+- 不需要新增另一套前端生产入口
+- 与当前 `DinsarProductionPanel.jsx` 的多引擎 UI 完全兼容
+
+### 4.4 输入与工作区组织
+
+建议一期仍以当前系统已有的任务目录为输入，不要求用户先手工构造原生 PyINT 项目。
+
+推荐工作区结构：
+
+- 系统输入根目录：沿用当前生产面板 `root_dir`
+- PyINT 工作根目录：系统管理目录，例如 `backend/runtime/pyint_work`
+- 模板目录：系统管理目录，例如 `backend/runtime/pyint_templates`
+- 每次运行独立 `run_key`
+- 每个 pair/task 独立 workspace，避免相互污染
+
+### 4.5 结果输出策略
+
+PyINT 原始输出不能直接作为系统正式结果目录暴露。
+
+推荐新增“输出归一化”步骤，将 PyINT/Gamma 输出转为系统现有 bundle 约定，至少包含：
+
+- 结果主清单
+- 关键输出文件路径
+- 运行元数据
+- pair trace 信息
+- engine/profile 信息
+
+必须保证与现有结果目录扫描机制兼容。
+
+### 4.6 Profile 设计建议
+
+一期建议只开放一个稳定 profile：
+
+- `lt1_gamma_dinsar`
+
+不建议一开始把 `PyINT` 全部开关都暴露到前端。应只暴露对当前业务必要的参数，例如：
+
+- 是否强制重跑
+- 多视参数
+- 相干阈值
+- geocode 开关
+- unwrap 开关
+- 超时
+
+其余细节由模板生成器按系统默认值填充。
+
+## 5. Gamma 精配对设计
+
+### 5.1 目标定位
+
+Gamma 精配对不替代当前数据库候选对缓存，而是建立在现有候选网络之上的二次精化机制。
+
+推荐定位为：
+
+- 当前数据库配对：全库级、粗筛级、可快速响应
+- Gamma 精配对：项目级、网络级、精筛级、可生成更可靠的时空基线网络
+
+### 5.2 推荐流程
+
+1. 用户在现有配对规划页完成粗配对查询
+2. 后端返回 `network_run_id`
+3. 用户在“Gamma 精配对”区域发起精化
+4. 系统根据该网络运行对应的场景集合，构建 PyINT/Gamma 工作区
+5. 调用 `select_pairs.py` / `base_calc` 生成精配对网络
+6. 后端将结果落回系统网络结果表示
+7. 前端展示“粗配对结果”和“Gamma 精配对结果”的对比摘要
+8. 用户选择使用哪一版网络继续生产
+
+### 5.3 为什么不能直接覆盖当前 pairing cache
+
+当前 `pairing_metric_cache` 里的 `spatial_baseline_meters` 已经在系统内承担既有语义与下游用途。  
+Gamma 计算出的垂直基线/网络属性与当前字段不等价，直接覆盖会带来语义混乱和回归风险。
+
+因此必须坚持：
+
+- 现有缓存保留原语义
+- Gamma 精配对结果单独存储
+- 精配对结果仅作为网络选择依据，不回写粗配对主缓存
+
+### 5.4 一期存储策略
+
+一期推荐不新建强结构化表，优先复用：
+
+- `pairing_network_runs.request_params_json`
+- `pairing_network_edges.selection_meta_json`
+
+建议约定写入内容：
+
+- `refinement_engine: gamma_pyint`
+- `refinement_source_run_id`
+- `gamma_bperp_m`
+- `gamma_tbase_days`
+- `gamma_rank`
+- `gamma_ifgram_list_path`
+- `gamma_artifact_dir`
+- `gamma_selection_reason`
+
+同时新增一个新的 `network_run_id`，把“精配对结果”作为新的网络运行保存，而不是修改原粗配对运行。
+
+这样做的收益：
+
+- 一期可不改数据库结构
+- 保留粗配对和精配对双轨结果，便于审计与回退
+- 复用现有 network run / edge 追踪模型
+
+### 5.5 二期可选扩展
+
+如果后续有以下需求，再引入数据库迁移：
+
+- 精配对历史独立检索
+- 精配对任务状态长期统计
+- 精配对工作区清理与资产追踪
+- 精配对失败类型聚合运维
+
+二期建议新增表，例如：
+
+- `pairing_refinement_runs`
+- `pairing_refinement_artifacts`
+
+但这不是一期必须项。
+
+## 6. 配置与运行管理方案
+
+### 6.1 配置原则
+
+- Windows 侧解释器继续复用根 `.env` 中已有的 `PYTHON_PATH`
+- WSL 侧只维护 PyINT/Gamma 运行必须配置
+- 因为本机只有一个 WSL 环境，`PyINT` 与 `ISCE2` 默认共用 distro
+
+### 6.2 建议新增配置项
+
+建议在 `.env` / `.env.example` / `backend/app/config.py` 中新增：
+
+```ini
+PYINT_ENABLED=false
+PYINT_WSL_DISTRO=
+PYINT_WSL_PYTHON=
+PYINT_HOME=
+PYINT_APP_SCRIPT=
+PYINT_TEMPLATE_ROOT=
+PYINT_WORK_ROOT=
+PYINT_OUTPUT_ROOT=
+PYINT_DEM_ROOT=
+PYINT_GAMMA_ENV_SCRIPT=
+PYINT_DEFAULT_TIMEOUT_SECONDS=43200
+PYINT_SMOKE_TEST_ENABLED=false
+
+PAIRING_GAMMA_ENABLED=false
+PAIRING_GAMMA_WORK_ROOT=
+PAIRING_GAMMA_TEMPLATE_ROOT=
+PAIRING_GAMMA_TIMEOUT_SECONDS=7200
+```
+
+默认策略建议：
+
+- `PYINT_WSL_DISTRO` 为空时，默认取 `ISCE2_WSL_DISTRO`
+- `PYINT_WSL_PYTHON` 为空时，默认取 `ISCE2_PYTHON`
+- `PYINT_APP_SCRIPT` 指向 `pyintApp.py`
+- `PYINT_WORK_ROOT` / `PAIRING_GAMMA_WORK_ROOT` 使用系统托管目录，不直接让用户任意指定
+
+### 6.3 不建议写入设计或配置的内容
+
+- 管理员明文密码
+- ASF/GACOS 邮箱密码
+- WSL sudo 密码
+
+这些信息如确需使用，也应通过运行时安全注入或机器本地安全配置处理，不写入仓库文档。
+
+### 6.4 管理与治理策略
+
+建议增加以下治理规则：
+
+- 所有 PyINT/Gamma 工作目录按 `run_key` 或 `network_run_id` 分目录
+- 所有运行都必须写运行摘要 JSON
+- 所有正式产物必须进入统一结果发布目录
+- 中间工作区可按保留策略定期清理
+- 清理动作仅允许管理员执行
+
+## 7. 数据库与数据库自维护策略
+
+### 7.1 一期结论
+
+一期建议：
+
+- `PyINT` 生产引擎接入不强制改库
+- `Gamma` 精配对接入不强制改库
+- 优先复用现有 run/edge JSON 元数据承载扩展信息
+
+### 7.2 二期改库触发条件
+
+当满足以下任意条件时，再进入改库：
+
+- 需要独立查询 Gamma 精配对运行历史
+- 需要单独统计 Gamma 精配对失败率
+- 需要把精配对资产纳入长期运维对象
+- 需要做更细粒度的后台管理界面
+
+### 7.3 改库时的落地方式
+
+如果二期改库，必须沿用现有数据库自维护机制：
+
+1. 在 `backend/migrations/` 新增 SQL 迁移文件，例如 `007_pyint_gamma_integration.sql`
+2. 在 `backend/app/db_maintenance.py` 的 `MIGRATION_FILES` 中追加文件名
+3. 由 `ensure_database_ready()` 在启动时自动执行迁移
+
+约束：
+
+- 不修改既有字段语义
+- 不破坏现有 `pairing_metric_cache` / `pairing_network_*` 查询逻辑
+- 迁移必须支持重复执行幂等
+
+## 8. 运维自检与健康检查设计
+
+### 8.1 设计原则
+
+运维自检页继续只做“状态观察”，不做主操作入口。
+
+PyINT/Gamma 的正式操作入口放在：
+
+- 生产页
+- 配对规划页
+
+### 8.2 健康检查应新增的内容
+
+建议在引擎可用性检查中加入 PyINT 项：
+
+- `PYINT_ENABLED`
+- WSL distro 可访问
+- WSL Python 可执行
+- `PYINT_HOME` 存在
+- `pyintApp.py` 存在
+- `GAMMA_ENV_SCRIPT` 可 source
+- 关键命令如 `base_calc` 可执行
+- 模板目录可读
+- 工作目录可写
+- DEM 根目录可读
+
+### 8.3 健康页展示策略
+
+不建议在 `HealthCheckPanel.jsx` 再新增一大块复杂操作区。
+
+建议只保留两类展示：
+
+1. 在现有 `D-InSAR 引擎` 卡片中自然显示 `PyINT`
+2. 在健康详情或备注中显示 PyINT/Gamma 的简要检查摘要
+
+不建议：
+
+- 在健康页提供精配对执行按钮
+- 在健康页提供模板编辑入口
+- 在健康页堆叠大量结果目录说明
+
+### 8.4 运维修复入口位置
+
+- 引擎级问题：在生产页提示不可用原因
+- 配对级问题：在配对规划页处理
+- 只有“环境诊断/烟测”可以保留在运维页
+
+## 9. 后端接口设计
+
+### 9.1 生产接口
+
+现有 `/dinsar-production/engines` 和 `/dinsar-production/run` 可继续复用。
+
+需要做的只是：
+
+- 在引擎注册表中加入 `pyint`
+- `list_engines()` 自动返回 PyINT
+- `submit_run()` 允许 `engine_code=pyint`
+
+### 9.2 配对接口
+
+建议新增以下接口：
+
+- `POST /pairing/refine-gamma`
+  - 输入：`network_run_id` 或明确场景列表
+  - 输出：新的精配对 `network_run_id`、摘要、警告、产物位置
+- `GET /pairing/networks/{network_run_id}`
+  - 继续复用现有接口查看粗配对/精配对网络详情
+- 可选：`GET /pairing/refine-gamma/{network_run_id}/artifacts`
+  - 用于查看 artifact 摘要，不建议一期必做
+
+### 9.3 管理接口
+
+建议增加一个轻量管理接口用于 PyINT/Gamma 环境烟测，例如：
+
+- `POST /dinsar-production/engines/pyint/smoke-check`
+
+用途仅限管理员环境校验，不参与正式生产提交。
+
+## 10. 前端入口与交互布局
+
+### 10.1 生产页
+
+位置：`frontend/src/DinsarProductionPanel.jsx`
+
+建议改动：
+
+- 新增 `PyINT` 引擎卡片
+- 显示 PyINT 可用性状态
+- 根据 profile 展示少量必要参数
+- 保留当前“根目录 + 参数 + 提交任务”交互，不新造独立页面
+
+### 10.2 配对规划页
+
+位置：`frontend/src/panels/PairPlanningPanel.jsx`
+
+建议新增一个独立区域：
+
+- 标题：`Gamma 精配对`
+- 放置位置：`配对基础` 卡片下方，`结果与刷新` 卡片上方
+
+该区域建议包含：
+
+- 粗配对网络摘要
+- 发起 Gamma 精配对按钮
+- 精配对结果摘要
+- 粗配对 / 精配对差异提示
+- 选择采用哪一版网络继续生产
+
+不建议把精配对塞进现有健康检查页。
+
+### 10.3 健康检查页
+
+位置：`frontend/src/HealthCheckPanel.jsx`
+
+建议只做最小改动：
+
+- 让 `D-InSAR 引擎` 卡片中自动出现 `PyINT`
+- 如需要，增加一条 PyINT/Gamma 环境说明
+
+不增加复杂控制区，避免界面继续变重。
+
+## 11. 涉及改动位置
+
+### 11.1 后端
+
+- `backend/app/dinsar_engines/registry.py`
+- `backend/app/dinsar_engines/pyint_engine.py` 新增
+- `backend/app/services/pyint_service.py` 新增
+- `backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py` 新增
+- `backend/app/routers/dinsar_production.py`
+- `backend/app/routers/pairing.py`
+- `backend/app/services/health_service.py`
+- `backend/app/config.py`
+- `.env.example`
+
+### 11.2 前端
+
+- `frontend/src/DinsarProductionPanel.jsx`
+- `frontend/src/panels/PairPlanningPanel.jsx`
+- `frontend/src/HealthCheckPanel.jsx`
+- `frontend/src/api/dinsarProduction.js`
+- `frontend/src/api/pairing.js`
+
+### 11.3 数据库
+
+一期可不改。
+
+二期若改，涉及：
+
+- `backend/migrations/007_pyint_gamma_integration.sql` 新增
+- `backend/app/db_maintenance.py`
+
+## 12. 分阶段实施建议
+
+### Phase 1: PyINT 引擎接入
+
+- 新增 `pyint_engine`
+- 完成 WSL 可用性检查
+- 完成模板生成与工作目录治理
+- 完成生产页引擎选择
+- 完成结果归一化与目录扫描兼容
+
+### Phase 2: Gamma 精配对 MVP
+
+- 新增 `/pairing/refine-gamma`
+- 基于现有 `network_run_id` 做精化
+- 精配对结果复用现有 network run / edge 模型表达
+- 前端在配对规划页增加精配对区块
+
+### Phase 3: 运维与治理补齐
+
+- 增加烟测接口
+- 增加工作区清理策略
+- 增加 artifact 摘要与失败类型归档
+
+### Phase 4: 二期结构化增强
+
+- 若业务确认需要，再加数据库迁移
+- 把精配对历史与资产纳入更细粒度可检索对象
+
+## 13. 风险与规避
+
+### 13.1 PyINT 代码稳定性
+
+风险：
+
+- 模板字段和脚本依赖较多
+- 对目录命名和环境变量较敏感
+
+规避：
+
+- 不做深度 import 复用
+- 使用受控包装脚本
+- 限制一期只开放一个稳定 profile
+
+### 13.2 WSL 与路径问题
+
+风险：
+
+- Windows 路径和 WSL 路径混用
+- 工作区权限与可写性问题
+
+规避：
+
+- 所有路径统一通过适配层转换
+- 工作目录和模板目录由系统托管
+
+### 13.3 配对语义污染
+
+风险：
+
+- 把 Gamma 垂直基线直接混写进现有粗配对缓存字段
+
+规避：
+
+- 明确不覆盖 `pairing_metric_cache` 语义
+- 精配对结果单独落在网络运行元数据中
+
+### 13.4 前端继续膨胀
+
+风险：
+
+- 把运维、配对、生产操作继续堆到健康检查页
+
+规避：
+
+- 健康页只显示状态
+- 生产操作只放生产页
+- 配对操作只放配对规划页
+
+## 14. 最终建议
+
+建议按以下判断执行：
+
+- `PyINT` 生产引擎接入：必要，且应尽快按现有多引擎架构落地。
+- `Gamma` 精配对接入：可行，但应作为“粗配对之后的精化层”落地。
+- 数据库：一期不强制改库；二期若需更强管理能力，再走数据库自维护迁移。
+- 运维自检：只加状态，不加大块操作区。
+- 前端入口：生产页接 `PyINT`，配对规划页接 `Gamma 精配对`。
+