# IDL/ENVI 集成状态文档

> 最后更新: 2026-02-21

## 1. 架构概述

系统的 D-InSAR 生产完全依赖 ENVI 5.6 + IDL 8.8 + SARscape 5.6+。
当前采用 **envipyengine** 作为唯一执行引擎，通过 Python subprocess 调用 `taskengine.exe`。

### 执行链路

```
前端 (IDLAutomationPanel.jsx)
  → POST /api/idl/jobs/import 或 /api/idl/jobs/dinsar
  → job_handlers.py: subprocess 启动 envi_runner_cli.py
  → envi_service.py: 调用 envipyengine → taskengine.exe
  → ENVI Task 执行 (SARsImportLuTan1 / SARsMetataskInSARDisplacementGeneration)
```

### 核心文件

| 文件 | 职责 |
|------|------|
| `backend/app/services/envi_service.py` | 核心服务：工作流、预检查、状态、历史 |
| `backend/app/services/envi_runner_cli.py` | CLI 入口，subprocess 中执行工作流 |
| `backend/app/services/job_handlers.py` | 任务分发，启动 envi_runner_cli 子进程 |
| `backend/app/routers/idl.py` | API 端点 |
| `frontend/src/IDLAutomationPanel.jsx` | 前端面板 (Step 1/2 布局) |
| `frontend/src/api/idl.js` | 前端 API 客户端 |

## 2. 环境配置

### ENVI 安装路径

```
C:\Program Files\Harris\ENVI56\
├── IDL88\bin\bin.x86_64\idl.exe
├── IDL88\bin\bin.x86_64\idlde.exe
└── IDL88\bin\bin.x86_64\taskengine.exe
```

### .env 关键配置

```ini
IDL_EXECUTABLE=C:\Program Files\Harris\ENVI56\IDL88\bin\bin.x86_64\idl.exe
IDL_WORKBENCH_PATH=C:\Program Files\Harris\ENVI56\IDL88\bin\bin.x86_64\idlde.exe
IDL_WORKER_RUNTIME_DIR=...\backend\runtime\idl_worker
IDL_WORKER_DEFAULT_TIMEOUT_SECONDS=14400
IDL_WORKER_MAX_TIMEOUT_SECONDS=43200
IDL_DINSAR_DEM_BASE_FILE=D:\SRTM30m\SRTMDEM_RSP_SARscape
```

### envipyengine 配置

```python
# 已通过 envipyengine.config.set() 配置:
engine = r'C:\Program Files\Harris\ENVI56\IDL88\bin\bin.x86_64\taskengine.exe'
```

Python 环境: `C:\Users\16216\.conda\envs\InSAR\python.exe` (envipyengine v1.0.9)

## 3. 根因分析：历史集成失败

### 3.1 症状回顾

之前尝试了三种引擎均不稳定：
- `idl.exe -e` 直连：进程挂起、管道错误、idl_opserver 崩溃 (0x0000000000000001)
- `taskengine.exe` 直调：内存访问违规 (0xC0000005 / exit code 3221225477)
- `envipyengine`：单独测试通过，集成到项目后崩溃

### 3.2 根因定位

**`.env` 中 `IDL_PATH` 变量名与 IDL 内置环境变量冲突。**

- `IDL_PATH` 是 IDL 的保留环境变量，用于指定 `.pro` 文件搜索路径
- 项目 `.env` 曾使用 `IDL_PATH` 存储 `idl.exe` 的可执行文件路径
- `load_dotenv()` 将其注入 `os.environ`，子进程继承后 IDL 读到无效的搜索路径
- `taskengine.exe` 因此崩溃，退出码 `0xC0000005`

### 3.3 验证过程

三态测试确认因果关系：

| 状态 | IDL_PATH 值 | 结果 |
|------|-------------|------|
| 干净环境 | 未设置 | ✅ 成功 |
| 设置错误值 | `C:\...\idl.exe` | ❌ 崩溃 (0xC0000005) |
| 移除后恢复 | 未设置 | ✅ 成功 |

### 3.4 修复

将 `.env` 中 `IDL_PATH` 重命名为 `IDL_EXECUTABLE`，同步更新所有引用。

## 4. 当前架构设计

### 4.1 设计决策

1. **envipyengine 为唯一执行引擎** — 删除了 idl 直连和 taskengine 直调的全部代码
2. **Import → D-InSAR 固定流水线** — D-InSAR 自动检测未导入数据，先 Import 再处理（智能串联）
3. **D-InSAR 使用 metatask** — 精细参数 (filter_method 等) metatask 不支持，已移除
4. **DEM 路径为系统级配置** — 存储在 .env，不暴露到前端
5. **subprocess 执行模式** — envipyengine 在独立子进程中运行，隔离 FastAPI 主进程

### 4.2 ENVI Tasks

| Task | 用途 | 关键参数 |
|------|------|----------|
| `SARsImportLuTan1` | 导入 LuTan-1 原始数据 | `INPUT_FILE_LIST`, `ROOT_URI_FOR_OUTPUT` |
| `SARsMetataskInSARDisplacementGeneration` | D-InSAR 位移生成 | `REFERENCE_SARSCAPEDATA`, `SECONDARY_SARSCAPEDATA`, `DEM_SARSCAPEDATA`, `OUTPUT_FOLDER` |

### 4.3 智能串联逻辑 (D-InSAR 工作流)

```
对每个 Task_* 文件夹:
  1. 检查 master/slave 是否有 .sml
  2. 没有 → 查找 .meta.xml → 自动执行 Import
  3. Import 完成后验证 .sml 生成
  4. 执行 D-InSAR metatask
```

### 4.4 API 端点

```
GET  /api/idl/status              — 系统状态 (含 DEM 路径和可用性)
POST /api/idl/launch-workbench    — 启动 IDL Workbench
POST /api/idl/inspect/import      — Import 预检查
POST /api/idl/inspect/dinsar      — D-InSAR 预检查 (含 Import 状态检测)
POST /api/idl/jobs/import         — 提交 Import 任务
POST /api/idl/jobs/dinsar         — 提交 D-InSAR 任务
GET  /api/idl/jobs/recent         — 最近运行记录
```

### 4.5 目录结构要求

Import 支持两种布局：
```
# Task_* 结构 (推荐)
root_dir/
├── Task_001/
│   ├── master/  → *.meta.xml
│   └── slave/   → *.meta.xml
└── Task_002/
    ├── master/
    └── slave/

# 平铺结构
root_dir/
├── scene_001/  → *.meta.xml
└── scene_002/  → *.meta.xml
```

D-InSAR 仅支持 Task_* 结构。

## 5. 测试记录

### 5.1 envipyengine 验证 (2026-02-20)

修复 IDL_PATH 冲突后，envipyengine Import 连续测试：

| 次数 | 耗时 | 结果 |
|------|------|------|
| 1 | 100.5s | ✅ 成功 |
| 2 | 75.8s | ✅ 成功 |
| 3 | 71.8s | ✅ 成功 |
| 4 | 73.6s | ✅ 成功 |
| 5 | 81.7s | ✅ 成功 |

测试数据: `Z:\Test_data\Test_IDL_1`

### 5.2 集成测试 — Step 1: Import (2026-02-21)

重构后通过前端 → 后端 → envipyengine 完整链路测试。

- 状态: ✅ 通过
- 链路: 前端提交 → job_handlers subprocess → envi_runner_cli → envi_service → envipyengine

### 5.3 集成测试 — Step 2: D-InSAR (待测试)

- 状态: ⏳ 待测试
- 前置条件: DEM 文件 `D:\SRTM30m\SRTMDEM_RSP_SARscape` 需存在于测试机
- 智能串联 (自动 Import) 待验证

## 6. 已删除的遗留代码

重构中删除的文件 (2026-02-21)：

| 文件 | 行数 | 说明 |
|------|------|------|
| `backend/app/services/idl_worker_service.py` | 2249 | 三引擎架构的巨型服务 |
| `backend/app/services/idl_runner_cli.py` | 58 | 旧 CLI runner |
| `backend/app/services/envipyengine_runner.py` | 47 | 调试用独立 runner |

清理的 .env 配置：所有 `IDL_TASKENGINE_*`、`IDL_WORKER_ENGINE`、`IDL_JOB_RUNNER_MODE`、
`IDL_IDL_*`、`IDL_WORKER_PREFLIGHT_*`、D-InSAR 精细参数 (filter_method 等)。

## 7. 已知限制

1. **D-InSAR 精细参数不可调** — metatask 不支持 filter_method、unwrapping_coh_threshold 等参数
2. **DEM 路径固定** — 从 .env 读取，不支持前端动态指定
3. **单进程串行** — envipyengine 调用 taskengine.exe 是同步阻塞的，同一时间只能执行一个 ENVI Task
4. **仅支持 LuTan-1** — Import task 为 `SARsImportLuTan1`，其他卫星数据需要不同的 Task