chore: initialize insar management system v2

docs/archive/IDL_INTEGRATION_STATUS.md

@@ -0,0 +1,201 @@
+# 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