391 lines
12 KiB
Markdown
391 lines
12 KiB
Markdown
# PyINT + Gamma 实施清单
|
||
|
||
更新日期：2026-04-18
|
||
|
||
关联设计文档：
|
||
|
||
- [PYINT_GAMMA_INTEGRATION_DESIGN_20260418.md](PYINT_GAMMA_INTEGRATION_DESIGN_20260418.md)
|
||
|
||
## 当前落地进度
|
||
|
||
- [x] 已完成第一批 `PyINT` 生产引擎接入：配置、引擎注册、任务队列、WSL 包装脚本、生产面板入口。
|
||
- [x] 已完成 `PyINT` 运行目录规范化输出：生成 `.dinsar_run.json` 与 `pyint_run_summary.json`。
|
||
- [x] 已完成 `PyINT` 基础环境检查：WSL、Python、`PYINT_HOME`、`pyintApp.py`、Gamma 命令可达性。
|
||
- [x] 已将 `PyINT` 代码收编到仓库内 `third_party/PyINT`，不再依赖默认外部绝对路径。
|
||
- [ ] 尚未完成 `PyINT` 结果目录自动发布兼容。当前原生输出已保存，但现有结果 catalog 仍主要面向 ENVI / ISCE2 栅格产物。
|
||
- [ ] 尚未开始 `Gamma` 精配对后端与前端集成。
|
||
|
||
## 1. 文档定位
|
||
|
||
这份清单用于把 `PyINT` 生产引擎接入和 `Gamma` 精配对接入拆成可执行任务，作为后续实施顺序、联调顺序和验收顺序的统一依据。
|
||
|
||
本清单按以下原则编排：
|
||
|
||
- 一期优先打通 `PyINT` 生产引擎
|
||
- 二期再做 `Gamma` 精配对 MVP
|
||
- 一期不强制改数据库主结构
|
||
- 运维自检只加状态，不把主要操作堆回健康页
|
||
|
||
## 2. 实施总顺序
|
||
|
||
推荐顺序：
|
||
|
||
1. 先确认环境基线和配置项
|
||
2. 先打通 `PyINT` 后端引擎与任务执行
|
||
3. 再补结果归一化与目录扫描兼容
|
||
4. 再补前端生产入口
|
||
5. 然后做 `Gamma` 精配对 MVP
|
||
6. 最后补健康检查、烟测和治理
|
||
|
||
不建议顺序：
|
||
|
||
- 先改数据库再写主流程
|
||
- 先做健康页大改
|
||
- 先把 `PyINT` 全部高级参数暴露到前端
|
||
|
||
## 3. Phase 0：环境基线确认
|
||
|
||
目标：
|
||
|
||
- 确认当前机器上的 `PyINT + Gamma + WSL` 具备最小可执行条件
|
||
- 把配置字段定清楚，但不把敏感信息写入仓库文档
|
||
|
||
### 任务
|
||
|
||
- [ ] 确认 `D:\Code\PyINT` 的实际可执行入口路径
|
||
- [ ] 确认当前唯一 WSL distro 名称，默认与 `ISCE2_WSL_DISTRO` 对齐
|
||
- [ ] 确认 WSL 中 `PyINT` 可用 Python 路径
|
||
- [ ] 确认 `GAMMA_ENV_SCRIPT` 的实际路径
|
||
- [ ] 确认 `base_calc` 在 WSL 中可执行
|
||
- [ ] 确认 `pyintApp.py` 在 WSL 中可执行
|
||
- [ ] 确认 `SCRATCHDIR` / `TEMPLATEDIR` / `DEMDIR` 对应的系统托管目录方案
|
||
- [ ] 确认 PyINT 一期只支持的业务范围，建议锁定 `LT-1 + Gamma D-InSAR`
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `backend/app/config.py`
|
||
- [ ] `.env.example`
|
||
- [ ] 根 `.env` 本机配置对照，不入库敏感值
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 可以给出完整的 PyINT 运行必需配置字段列表
|
||
- [ ] 可以在 WSL 内成功跑通最小烟测命令
|
||
- [ ] 不需要把管理员密码、邮箱密码、sudo 密码写入代码或文档
|
||
|
||
## 4. Phase 1：PyINT 后端引擎接入
|
||
|
||
目标：
|
||
|
||
- 把 `PyINT` 作为新的 D-InSAR 引擎正式接入现有多引擎体系
|
||
|
||
### 4.1 配置层
|
||
|
||
- [ ] 在 `backend/app/config.py` 新增 `PYINT_*` 配置
|
||
- [ ] 增加默认继承逻辑：`PYINT_WSL_DISTRO` 默认跟随 `ISCE2_WSL_DISTRO`
|
||
- [ ] 增加默认继承逻辑：`PYINT_WSL_PYTHON` 默认跟随 `ISCE2_PYTHON`
|
||
- [ ] 增加系统托管目录默认值：
|
||
- [ ] `PYINT_TEMPLATE_ROOT`
|
||
- [ ] `PYINT_WORK_ROOT`
|
||
- [ ] `PYINT_OUTPUT_ROOT`
|
||
- [ ] 在 `validate_runtime_config()` 中加入 PyINT 基础校验
|
||
- [ ] 在 `.env.example` 中补齐非敏感 PyINT 配置示例
|
||
|
||
### 4.2 服务层
|
||
|
||
- [ ] 新增 `backend/app/services/pyint_service.py`
|
||
- [ ] 封装 WSL 执行逻辑，复用现有 `wsl_service.py`
|
||
- [ ] 实现 Windows 路径到 WSL 路径转换
|
||
- [ ] 实现 PyINT 工作区目录初始化
|
||
- [ ] 实现模板文件生成
|
||
- [ ] 实现运行参数到模板字段的映射
|
||
- [ ] 实现运行摘要 JSON 输出
|
||
- [ ] 实现 PyINT 烟测函数
|
||
|
||
### 4.3 引擎层
|
||
|
||
- [ ] 新增 `backend/app/dinsar_engines/pyint_engine.py`
|
||
- [ ] 实现 `DinsarEngine` 接口
|
||
- [ ] 定义 `engine_code=pyint`
|
||
- [ ] 定义一期唯一 profile，建议为 `lt1_gamma_dinsar`
|
||
- [ ] 定义最小参数 schema，避免一开始暴露过多 PyINT 原生参数
|
||
- [ ] 实现 `check_available()`
|
||
- [ ] 实现 `run()`
|
||
|
||
### 4.4 注册与任务调度
|
||
|
||
- [ ] 在 `backend/app/dinsar_engines/registry.py` 注册 `PyINT`
|
||
- [ ] 在 `backend/app/services/job_handlers.py` 增加 `JOB_TYPE_PYINT_RUN`
|
||
- [ ] 新增对应 handler
|
||
- [ ] 在 `backend/app/routers/dinsar_production.py` 允许 `engine_code=pyint`
|
||
- [ ] 让生产提交逻辑按 `pyint` 分派到新 job type
|
||
|
||
### 4.5 WSL 包装脚本
|
||
|
||
- [ ] 新增 `backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py`
|
||
- [ ] 负责把系统任务目录映射为 PyINT 项目目录
|
||
- [ ] 负责设置 `SCRATCHDIR` / `TEMPLATEDIR` / `DEMDIR`
|
||
- [ ] 负责调用 `pyintApp.py` 或必要的细粒度 PyINT 脚本
|
||
- [ ] 负责收集输出路径和运行摘要
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `backend/app/config.py`
|
||
- [ ] `backend/app/dinsar_engines/registry.py`
|
||
- [ ] `backend/app/dinsar_engines/pyint_engine.py`
|
||
- [ ] `backend/app/services/pyint_service.py`
|
||
- [ ] `backend/app/services/job_handlers.py`
|
||
- [ ] `backend/app/routers/dinsar_production.py`
|
||
- [ ] `backend/app/pyint_pipeline/run_lt1_pyint_pipeline.py`
|
||
- [ ] `.env.example`
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] `/dinsar-production/engines` 能返回 `pyint`
|
||
- [ ] `PyINT` 引擎可在后端被识别为可用/不可用
|
||
- [ ] 可以成功提交一个 `pyint` 生产任务到队列
|
||
- [ ] 任务日志、任务状态、错误信息可通过现有任务体系查看
|
||
|
||
## 5. Phase 2：PyINT 结果归一化与结果治理兼容
|
||
|
||
目标：
|
||
|
||
- 保证 `PyINT` 输出能进入现有结果扫描、发布和 catalog 体系
|
||
|
||
### 任务
|
||
|
||
- [ ] 定义 PyINT 结果工作区与正式输出区的边界
|
||
- [ ] 统一输出 bundle 元数据格式
|
||
- [ ] 输出 engine/profile/run_key/task_name/pair trace 元数据
|
||
- [ ] 补齐 pair 相关元数据：
|
||
- [ ] `pair_uid`
|
||
- [ ] `network_run_id`
|
||
- [ ] `network_edge_id`
|
||
- [ ] `policy_version`
|
||
- [ ] 让现有 `dinsar_scan_service` 可以识别 PyINT 结果
|
||
- [ ] 验证现有 `result_catalog_service` 可处理 PyINT 产物
|
||
- [ ] 验证桥接一致性逻辑不会把 PyINT 结果识别坏
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `backend/app/services/pyint_service.py`
|
||
- [ ] `backend/app/services/dinsar_scan_service.py`
|
||
- [ ] `backend/app/services/result_catalog_service.py`
|
||
- [ ] 可能涉及现有结果元数据写入辅助模块
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 跑完 PyINT 后可被系统扫描到
|
||
- [ ] 可进入结果目录索引
|
||
- [ ] 不影响现有 SARscape/ISCE2 结果扫描
|
||
|
||
## 6. Phase 3：前端生产页接入 PyINT
|
||
|
||
目标：
|
||
|
||
- 在现有生产页中把 `PyINT` 作为正式引擎展示和提交
|
||
|
||
### 任务
|
||
|
||
- [ ] 在 `frontend/src/DinsarProductionPanel.jsx` 中显示 `PyINT` 引擎卡片
|
||
- [ ] 补充 `ENGINE_LABEL` / `TASK_TYPE_LABEL`
|
||
- [ ] 根据 `PyINT` profile 渲染参数输入项
|
||
- [ ] 对不可用状态显示明确原因
|
||
- [ ] 提交成功后沿用现有任务监控
|
||
- [ ] 验证运行列表中能正确显示 `pyint`
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `frontend/src/DinsarProductionPanel.jsx`
|
||
- [ ] `frontend/src/api/dinsarProduction.js`
|
||
- [ ] `frontend/src/utils/dinsarEngines.js` 如需要
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 前端可看到 `PyINT`
|
||
- [ ] 可提交 `PyINT` 任务
|
||
- [ ] 可看到任务状态和日志
|
||
- [ ] 不影响现有 SARscape/ISCE2 提交
|
||
|
||
## 7. Phase 4：Gamma 精配对 MVP
|
||
|
||
目标：
|
||
|
||
- 在现有配对规划体系上实现一版可用的 `Gamma` 精配对
|
||
|
||
### 7.1 后端能力
|
||
|
||
- [ ] 新增 `backend/app/services/pairing_refinement_service.py`
|
||
- [ ] 新增 `backend/app/services/gamma_pairing_service.py` 或同等职责模块
|
||
- [ ] 实现基于现有 `network_run_id` 的场景集提取
|
||
- [ ] 实现 PyINT/Gamma 配对工作区构建
|
||
- [ ] 调用 `select_pairs.py` / `base_calc`
|
||
- [ ] 解析 `ifgram_list.txt` / baseline 输出
|
||
- [ ] 生成新的 refined `network_run_id`
|
||
- [ ] 将精配对结果写入：
|
||
- [ ] `pairing_network_runs`
|
||
- [ ] `pairing_network_edges`
|
||
- [ ] `selection_meta_json`
|
||
|
||
### 7.2 接口层
|
||
|
||
- [ ] 在 `backend/app/routers/pairing.py` 增加 `POST /pairing/refine-gamma`
|
||
- [ ] 设计请求体和响应体
|
||
- [ ] 设计运行告警返回字段
|
||
- [ ] 如需要，增加 refined artifacts 查询接口
|
||
|
||
### 7.3 存储策略
|
||
|
||
- [ ] 明确一期不改 `pairing_metric_cache` 语义
|
||
- [ ] 明确只在 run/edge JSON 中落精配对元数据
|
||
- [ ] 保留粗配对网络和精配对网络双轨并存
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `backend/app/routers/pairing.py`
|
||
- [ ] `backend/app/services/spatial_service.py` 如需复用
|
||
- [ ] `backend/app/services/pairing_refinement_service.py`
|
||
- [ ] `backend/app/services/gamma_pairing_service.py`
|
||
- [ ] `backend/app/models/schemas.py`
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 可基于一个已有 `network_run_id` 发起精配对
|
||
- [ ] 返回新的 refined `network_run_id`
|
||
- [ ] 精配对结果可通过现有 network 查询接口查看
|
||
- [ ] 不破坏原粗配对结果
|
||
|
||
## 8. Phase 5：前端配对规划页接入 Gamma 精配对
|
||
|
||
目标：
|
||
|
||
- 在配对规划页提供精配对入口和结果摘要
|
||
|
||
### 任务
|
||
|
||
- [ ] 在 `frontend/src/panels/PairPlanningPanel.jsx` 新增 `Gamma 精配对` 区块
|
||
- [ ] 展示当前粗配对网络摘要
|
||
- [ ] 增加发起精配对按钮
|
||
- [ ] 展示精配对结果摘要
|
||
- [ ] 展示粗配对与精配对差异提示
|
||
- [ ] 增加“采用哪一版网络继续生产”的状态表达
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `frontend/src/panels/PairPlanningPanel.jsx`
|
||
- [ ] `frontend/src/api/pairing.js`
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 管理员可在配对规划页发起精配对
|
||
- [ ] 能看到 refined 结果摘要
|
||
- [ ] 不需要进入健康检查页做配对操作
|
||
|
||
## 9. Phase 6：运维自检与烟测补齐
|
||
|
||
目标：
|
||
|
||
- 让 PyINT/Gamma 的环境状态可被健康检查观察
|
||
|
||
### 任务
|
||
|
||
- [ ] 在 `backend/app/services/health_service.py` 中纳入 PyINT 检查
|
||
- [ ] 检查项至少包括：
|
||
- [ ] `PYINT_ENABLED`
|
||
- [ ] distro 可访问
|
||
- [ ] WSL Python 可执行
|
||
- [ ] `pyintApp.py` 存在
|
||
- [ ] `GAMMA_ENV_SCRIPT` 存在
|
||
- [ ] `base_calc` 可执行
|
||
- [ ] 模板目录可读
|
||
- [ ] 工作目录可写
|
||
- [ ] 增加管理员烟测接口
|
||
- [ ] 前端健康页只展示状态摘要，不加复杂操作区
|
||
|
||
### 涉及文件
|
||
|
||
- [ ] `backend/app/services/health_service.py`
|
||
- [ ] `backend/app/routers/dinsar_production.py`
|
||
- [ ] `frontend/src/HealthCheckPanel.jsx`
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 健康页可看到 PyINT 状态
|
||
- [ ] 可区分“引擎不可用”和“系统整体故障”
|
||
- [ ] 不把精配对主操作入口放回健康页
|
||
|
||
## 10. Phase 7：可选数据库结构化增强
|
||
|
||
目标：
|
||
|
||
- 只有在业务确认需要更强的历史与运维管理时才进入本阶段
|
||
|
||
### 进入条件
|
||
|
||
- [ ] 需要独立查询精配对历史
|
||
- [ ] 需要统计精配对失败率
|
||
- [ ] 需要管理精配对 artifacts 生命周期
|
||
- [ ] 需要构建更完整的后台管理页
|
||
|
||
### 任务
|
||
|
||
- [ ] 设计 `pairing_refinement_runs` 等新表
|
||
- [ ] 新增迁移文件，例如 `007_pyint_gamma_integration.sql`
|
||
- [ ] 在 `backend/app/db_maintenance.py` 中加入迁移列表
|
||
- [ ] 验证 `ensure_database_ready()` 启动自动迁移
|
||
- [ ] 验证幂等执行
|
||
|
||
### 阶段验收
|
||
|
||
- [ ] 新表结构不破坏现有 pairing 逻辑
|
||
- [ ] 启动时可自动应用迁移
|
||
- [ ] 老数据和老接口保持兼容
|
||
|
||
## 11. 联调与验收矩阵
|
||
|
||
### 后端
|
||
|
||
- [ ] `py_compile` 或等价语法检查通过
|
||
- [ ] 新增路由可正常注册
|
||
- [ ] 新增引擎可正常列出
|
||
- [ ] 任务队列能执行 `PyINT`
|
||
- [ ] 精配对接口能生成 refined network
|
||
|
||
### 前端
|
||
|
||
- [ ] `npm run build` 通过
|
||
- [ ] 生产页能显示 `PyINT`
|
||
- [ ] 配对规划页能显示 `Gamma 精配对`
|
||
- [ ] 健康页能显示 PyINT 状态
|
||
|
||
### 集成
|
||
|
||
- [ ] `PyINT` 单任务最小链路跑通
|
||
- [ ] 结果能被系统扫描
|
||
- [ ] 精配对 MVP 跑通
|
||
- [ ] 现有 SARscape/ISCE2 不回归
|
||
|
||
## 12. 当前明确不做
|
||
|
||
- [ ] 一期不把 PyINT 的全部模板参数开放到前端
|
||
- [ ] 一期不接入 GACOS 自动邮箱下载链路
|
||
- [ ] 一期不接入 POT、phase bias、完整时序 MintPy 流程
|
||
- [ ] 一期不改写现有 `pairing_metric_cache` 字段语义
|
||
- [ ] 一期不在健康检查页增加主操作面板
|
||
- [ ] 一期不做多 WSL distro 管理
|
||
|
||
## 13. 当前建议的首批落地包
|
||
|
||
建议第一轮直接落以下内容：
|
||
|
||
- [ ] `config.py` + `.env.example` 的 `PYINT_*` 配置
|
||
- [ ] `pyint_service.py`
|
||
- [ ] `pyint_engine.py`
|
||
- [ ] `registry.py` 注册
|
||
- [ ] `job_handlers.py` 的 `JOB_TYPE_PYINT_RUN`
|
||
- [ ] `dinsar_production.py` 的 `pyint` 提交分派
|
||
- [ ] `run_lt1_pyint_pipeline.py`
|
||
- [ ] `DinsarProductionPanel.jsx` 的 `PyINT` 引擎展示与提交
|
||
|
||
这批完成后，再进入 `Gamma` 精配对 MVP。
|