# 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。