# InSAR 自动化管理与智能评估系统 - 部署与使用说明

本文件为本项目主中文文档，整合了产品说明、技术架构、业务流程、部署与启动、数据库与授权等内容。  
补充专题文档见：`docs/TODO.md`、`docs/RADAR_PREVIEW_SCHEME_B.md`。

---

## 1. 产品概述
本系统是一套深度集成 **IDL/ENVI SARscape** 的专业级 InSAR 数据管理与智能分析平台，聚焦地质灾害监测领域，解决大规模雷达影像处理流程繁琐、数据关联困难、结果解译依赖人工等问题。

通过“Web 化管理 + 自动化引擎 + AI 智能诊断”的三位一体架构，实现从原始 SAR 影像入库到生成形变诊断报告的全生命周期自动化管理。

---

## 2. 核心优势
- **核心流程自动化**：覆盖数据监控、精轨关联、干涉配对、自动化处理引导与结果发布（当前扫描调度默认手动触发）。
- **高精度空间引擎**：凸包算法 + 仿射变换，支持亚像素级 Footprint 提取与空间关联。
- **AI 辅助决策**：集成随机森林质量评估模型与 VLM 视觉大模型，给出专家级解译建议。
- **工业级稳定性**：针对 Windows Server 环境优化，支持 GB 级超大影像处理。

---

## 3. 技术架构
- **管理层 (Web Interface)**：React + Vite + Leaflet（支持离线多级细节加载）
- **逻辑层 (Service Layer)**：FastAPI 异步框架，集成 PostgreSQL + PostGIS
- **空间引擎 (Spatial Engine)**：PostGIS 原生计算 + GeoAlchemy2 + Rasterio
- **AI 引擎 (Intelligence)**：Scikit-learn + 本地 Ollama VLM
- **计算引擎 (Compute)**：IDL 8.8 / ENVI 5.6（SARscape 5.6+）

---

## 4. 业务流程指南

### 4.1 数据资产监控
当前系统默认采用 **Manual-only（手动触发）** 扫描模式，不启用后台定时守护任务。  
可通过前端“立即扫描”或接口 `POST /api/monitor/run-now` 触发扫描；扫描内部仍采用增量策略以降低系统负载。

**D-InSAR 结果扫描说明（重要）：**  
当前 D-InSAR 结果扫描为**全量遍历 + 仅新增入库**。  
即：每次扫描都会遍历所有 `.hdr` 文件，但数据库只写入“新发现”的结果记录，以保证准确性和稳定性。

扫描任务的进度条基于**实际遍历数量与处理数量**计算，前端显示为真实进度。

数据列表已支持“影像信息”按钮，可查看影像基础元数据（卫星/日期/模式/极化/精轨等）。
影像元数据解析已扩展：优先从 XML 获取成像模式/极化/轨道方向，并补充卫星模式、接收站代号、圈号、景中心经纬度、采集时间、产品类型/级别、唯一标识等字段用于展示。
源数据预览缓存接口：`GET /api/radar-data/{data_id}/thumb`（首次请求若无缓存会自动生成）。

**源影像预览（Scheme B：后端预纠正缓存）**  
系统已接入双层缓存：
- `backend/image_cache/radar_geo/`：地理纠正后的主缓存（前端优先使用）
- `backend/image_cache/radar_raw/`：原图 WebP 回退缓存

**D-InSAR 结果缓存（标准目录）**
- `backend/image_cache/dinsar/`：D-InSAR 结果可视化缓存目录
- 文件命名：`ID_{id}_{name}.webp`
- 清单文件：`backend/image_cache/dinsar/cache_manifest.json`

**一致性检测（统计面板）**
- `GET /api/statistics` 已新增一致性字段，用于校验“数据库记录 vs 实际缓存文件 vs XML 读取结果”。
- 重点包含：
  - D-InSAR：`db_cached_but_file_missing_count`、`db_uncached_but_file_exists_count`、`manifest_missing_file_count`
  - 源影像预览：`db_ready_but_cache_missing_count`、`preview_missing_count`
  - XML：`xml_detected_but_unparsed_count`、`xml_missing_count`
- 前端「数据统计仪表盘」会直接显示异常数量并高亮提示，便于运维快速定位问题。

新增接口：
- `GET /api/radar-data/{id}/preview-status`：查询单条源影像预览缓存状态
- `POST /api/radar-data/{id}/rebuild-preview-cache`：管理员强制重建该影像预览缓存
- `GET /api/radar-data?limit=500&offset=0`：分页获取源数据列表（单次最多 2000 条）
- `POST /api/radar-data/search`：源数据分页检索（支持详情字段筛选 + 行政区/上传SHP空间筛选）
- `GET /api/radar-data/search/options`：获取源数据检索下拉选项（来自数据库去重值）
- `GET /api/dinsar-results?limit=500&offset=0`：分页获取 D-InSAR 结果列表（单次最多 2000 条）
- `GET /api/radar-data/imaging-dates`：获取所有可用成像日期（用于配对起始日期下拉框）
- `GET /api/statistics`：默认返回缓存快照；管理员可用 `GET /api/statistics?fresh=true` 强制重算

`/api/radar-data/search` 说明：
- 权限：管理员与只读账号均可调用（只读安全查询接口）。
- 筛选字段：可按卫星、成像时间范围、模式/极化/产品元数据等详情字段检索。
- 空间筛选：支持 `region_tree_id`（复用行政区）或上传 AOI 文件（`.shp`/GeoJSON）。
- 分页性能：首次 AOI 查询会返回 `aoi_token`，后续翻页可仅携带 token，无需重复上传文件。
- 前端交互：检索字段采用“全下拉可选”，避免手工输入导致的筛选误差。

分页接口响应结构（`/api/radar-data` 与 `/api/dinsar-results` 一致）：
```json
{
  "items": [],
  "total": 12345,
  "limit": 200,
  "offset": 0,
  "has_more": true
}
```

前端分页说明：
- 「数据列表」与「D-InSAR 结果」均支持上一页/下一页、每页条数切换（50/100/200/500）与页码跳转。
- 前端默认每页 200 条，避免一次性加载全量数据导致页面和地图卡顿。
- 「数据列表」改为“先检索后展示”：系统启动后不自动加载源数据，需点击“搜索”或“搜索全部源数据”后才显示列表与分页结果。
- 当检索条件变更并再次执行搜索时，前端会先清空旧结果再渲染新结果，避免“旧页数据残留”造成误判。
- 异常/堆栈文本默认不参与界面翻译（e.g. `NoneType object is not callable`、`Traceback`），保持原始语言以避免日志或异常信息被误替换。

新增环境变量（可选）：
```env
RADAR_GEO_CACHE_WORKERS=2
RADAR_GEO_CACHE_VERSION=b1
RADAR_GEO_CACHE_QUALITY=84
RADAR_PREVIEW_BUILD_ON_DEMAND=true
```

说明：
- `thumb` 接口优先返回 `radar_geo`，失败时自动回退 `radar_raw`。
- 扫描任务会增量构建 `radar_geo`，并维护 `radar_raw` 作为兜底。
- 如纠正逻辑升级，提升 `RADAR_GEO_CACHE_VERSION` 可触发重建。
- 纠正方向判定优先使用 XML 的 `sceneCornerCoord/refRow/refColumn` 建立“像素角 ↔ 地理角”映射，可显著减少左右/上下方向错误。

### 4.2 任务分发与处理
系统生成处理清单对接 IDL 自动化脚本，用户可在 Web 端一键启动本地 IDL 工作站，实现“云端规划，本地计算”。

### 4.3 智能诊断报告
AI 模块结合影像范围内的已知灾害点生成 Markdown 报告，涵盖：活动性评估、隐患搜寻、风险评级与处置建议。

---

## 5. 核心算法与机制概览
为保持文档完整性，以下为算法专题的简要说明（不再拆分子文档）：
- **智能任务规划与贪心优化**：多维约束模型、覆盖多样性惩罚与任务筛选策略。
- **空间几何与极速 Footprint**：降采样探测 + 凸包生成，结合拓扑简化提升效率。
- **AI 诊断与图像处理**：百分比截断拉伸、质量评估特征与自动裁剪策略。

---

## 6. 环境与依赖
- **OS**：Windows Server 2019+（推荐）
- **数据库**：PostgreSQL 14+ + PostGIS
- **Python**：推荐 Conda 环境（本项目 environment.yml 已固定为 Python 3.10）
- **Nginx**：用于前端静态资源与反向代理（推荐）
- **Node.js**：仅构建前端时需要
- **IDL/ENVI**：仅启用 IDL 自动化时需要

---

## 7. 离线 Python 环境（推荐：conda-pack）

### 7.1 开发机（有外网）
```powershell
conda env create -f environment.yml
conda activate InSAR
```

如需授权功能，请确保安装 cryptography：
```powershell
pip install cryptography
```

如需打包授权 GUI：
```powershell
pip install pyinstaller
```

打包环境：
```powershell
conda install -n base conda-pack
conda pack -n InSAR -o insar_env.tar.gz
```

将 `insar_env.tar.gz` 拷贝到服务器。

### 7.2 服务器（离线）
解压到目标目录（示例：`C:\envs\InSAR`）：
```powershell
mkdir C:\envs\InSAR
tar -xzf insar_env.tar.gz -C C:\envs\InSAR
C:\envs\InSAR\Scripts\conda-unpack.exe
```

如果没有 `tar`，可使用 7-Zip 解压。

在 `.env` 中配置：
```
PYTHON_PATH=C:\envs\InSAR\python.exe
```
`PYTHON_PATH` 也支持命令名（如 `python`），`scripts/start_app.ps1` 会通过 `Get-Command` 解析真实可执行文件路径。  
若使用 Conda，建议先激活 `InSAR` 环境后再启动，或直接填入该环境的 `python.exe` 绝对路径。

也可使用 Conda 原生模式（推荐）：
```
CONDA_EXE=D:\anaconda3\Scripts\conda.exe
CONDA_ENV_NAME=InSAR
```
当 `CONDA_ENV_NAME` 非空时，`scripts/start_app.ps1` 会优先使用  
`CONDA_EXE` 定位目标环境并解析其 `python.exe`，随后使用该解释器执行数据库检查、初始化、后端与 Worker 启动流程（避免并发 `conda run` 稳定性问题）。

**不建议直接复制 venv**，二进制依赖容易失效。

---

## 8. 数据库准备

### 8.1 创建数据库
```powershell
psql -U postgres -h localhost -p 5432
CREATE DATABASE insar_management;
\q
```

### 8.2 启用 PostGIS
```powershell
psql -U postgres -h localhost -p 5432 -d insar_management
CREATE EXTENSION IF NOT EXISTS postgis;
\q
```

### 8.3 配置连接并检测
在 `.env` 中设置：
```
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/insar_management
```

手动检查连接：
```powershell
D:\anaconda3\Scripts\conda.exe run -n InSAR python scripts/check_db_connection.py
```

---

## 9. 授权（离线）

启动授权管理工具：
```powershell
D:\anaconda3\Scripts\conda.exe run -n InSAR python scripts/license_manager_gui.py
```

使用流程：
1) 选择 `.env` 路径
2) 输入到期时间（UTC，格式：`YYYY-MM-DD HH:MM:SS`，留空默认 1 年）
3) 点击“生成/续期授权”
4) 自动写入 `.env` 中的 `LICENSE_SECRET` / `LICENSE_PUBLIC_KEY`
5) 生成 `backend\license\license.lic` 与 `license_private_key.txt`

说明：
- `license_private_key.txt` 请妥善保存（用于续期）。
- 服务器只需要公钥与授权文件，不要部署私钥。
- 建议仅在离线管理机保存私钥文件，避免在业务服务器落盘或备份私钥。
- 离线授权属于本地合规校验机制：可显著提高误用门槛，但不等同于“对拥有服务器管理员权限场景”的绝对防篡改。

授权相关接口：
```
/api/license/status
/api/license/upload   （仅管理员可调用）
/api/license/refresh  （仅管理员可调用）
```

返回约束（安全脱敏）：
- `GET /api/license/status` 默认仅返回 `ok`、`reason`、`expires_at`。
- 当请求携带管理员会话时，`GET /api/license/status` 会额外返回调试字段（如 `fingerprint`、`license_path`）。

---

## 10. 关键配置（.env）
常用参数示例：
```
# 服务显示地址（用于启动日志与前端展示）
SERVER_HOST=192.168.1.100

# 后端端口（示例使用 18000，避免与常见本机服务冲突）
PORT=18000

# 前端开发模式代理目标（仅 npm run dev 使用）
VITE_BACKEND_TARGET=http://localhost:18000

# Python / Nginx 路径
PYTHON_PATH=C:\envs\InSAR\python.exe
CONDA_EXE=D:\anaconda3\Scripts\conda.exe
CONDA_ENV_NAME=InSAR
NGINX_PATH=C:\nginx-1.29.4\nginx.exe

# IDL / ENVI 路径与 worker 管理目录
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_SCRIPT_SOURCE_DIR=<项目根目录>\IDL\origin
IDL_WORKER_SCRIPT_DIR=<项目根目录>\IDL\worker_managed
IDL_WORKER_RUNTIME_DIR=<项目根目录>\backend\runtime\idl_worker
IDL_WORKER_DEFAULT_TIMEOUT_SECONDS=14400
IDL_WORKER_MAX_TIMEOUT_SECONDS=43200
IDL_WORKER_TEMP_DIRECTORY=D:\Sarscape_IDL_Area

# IDL worker 默认任务参数（可被 API 请求体覆盖）
IDL_IMPORT_ROOT_DIR=
IDL_IMPORT_NUM_TO_PROCESS=0
IDL_DINSAR_ROOT_DIR=
IDL_DINSAR_DEM_BASE_FILE=
IDL_DINSAR_NUM_TO_PROCESS=0
IDL_DINSAR_TARGET_GROUND_RESOLUTION_M=10.0
IDL_DINSAR_FILTER_METHOD=GOLDSTEIN
IDL_DINSAR_UNWRAP_COH_THRESHOLD=0.05
IDL_DINSAR_GCP_COH_THRESHOLD=0.7
IDL_DINSAR_GCP_NUMBER=100
IDL_DINSAR_GEOCODING_COH_THRESHOLD=0.0
IDL_DINSAR_GEOCODING_PIXEL_SIZE_M=10.0

# 授权
LICENSE_SECRET=...
LICENSE_PUBLIC_KEY=...
LICENSE_PATH=...\backend\license\license.lic
LICENSE_STATE_PATH=...\backend\license\license_state.json
MAX_LICENSE_UPLOAD_BYTES=1048576

# 鉴权（Session + Cookie）
INIT_ADMIN_USERNAME=admin
INIT_ADMIN_PASSWORD=<REQUIRED_STRONG_PASSWORD>
INIT_ADMIN_RESET_PASSWORD=false
SESSION_TTL_HOURS=12
AUTH_SESSION_COOKIE_NAME=ims_session
AUTH_COOKIE_SAMESITE=Lax
AUTH_COOKIE_SECURE=false
AUTH_LOGIN_MAX_FAILURES=5
AUTH_LOGIN_WINDOW_SECONDS=900
AUTH_LOGIN_LOCK_SECONDS=900
AUTH_LOGIN_CLEANUP_INTERVAL_SECONDS=300

# AOI 上传限流
AOI_UPLOAD_MAX_FILES=10
AOI_UPLOAD_MAX_SINGLE_FILE_BYTES=20971520
AOI_UPLOAD_MAX_TOTAL_BYTES=104857600

# 扫描请求边界
MAX_SCAN_DIRECTORY_COUNT=64
MAX_SCAN_PATH_LENGTH=2048

# 高频列表查询边界与超时
LIST_QUERY_MAX_LIMIT=2000
LIST_QUERY_MAX_OFFSET=200000
LIST_QUERY_MAX_WINDOW=202000
LIST_QUERY_TIMEOUT_MS=20000
RADAR_SEARCH_OPTIONS_MAX_VALUES=5000
RADAR_IMAGING_DATES_MAX_VALUES=5000

# 队列入队边界（防止异常大 payload 冲击数据库）
JOB_QUEUE_MAX_PAYLOAD_BYTES=524288
JOB_QUEUE_MAX_ATTEMPTS=10
JOB_QUEUE_MAX_PRIORITY_ABS=1000
JOB_QUEUE_MAX_ID_LENGTH=128
JOB_QUEUE_MAX_TYPE_LENGTH=64

# 任务/日志查询边界（防止单次查询放大）
TASK_ACTIVE_DEFAULT_LIMIT=100
TASK_ACTIVE_MAX_LIMIT=500
TASK_LOG_DEFAULT_LIMIT=100
TASK_LOG_MAX_LIMIT=1000
TASK_QUERY_MAX_OFFSET=500000
MONITOR_LOG_DEFAULT_LIMIT=50
MONITOR_LOG_MAX_LIMIT=200
MONITOR_LOG_MAX_OFFSET=500000

# 批次与复制请求边界
TASK_BATCH_MAX_ITEMS=5000
TASK_BATCH_TEXT_MAX_LENGTH=256
TASK_BATCH_REMARK_MAX_LENGTH=2000
TASK_BATCH_LIST_DEFAULT_LIMIT=200
TASK_BATCH_LIST_MAX_LIMIT=1000
TASK_BATCH_LIST_MAX_OFFSET=500000
COPY_BATCH_TEXT_MAX_LENGTH=2048
COPY_BATCH_MAX_STATUS_COUNT=8

# 工作流请求边界
WORKFLOW_MAX_STEPS=200
WORKFLOW_MAX_DEPENDS=32
WORKFLOW_TEXT_MAX_LENGTH=128

# AI 地图分析请求边界
AI_ANALYZE_MAP_MAX_IMAGES=4
AI_ANALYZE_MAP_MAX_IMAGE_BASE64_CHARS=12582912
AI_ANALYZE_MAP_PROMPT_MAX_CHARS=8000

# 生产环境请使用白名单，不建议 *
CORS_ORIGINS=http://192.168.1.100
CORS_ALLOW_CREDENTIALS=true
CORS_STRICT_MODE=false

# 统计缓存（秒）
STATS_CACHE_TTL_SECONDS=120

# 预览缓存（可选）
RADAR_THUMBNAIL_MAX_SIZE=1600
RADAR_CACHE_WORKERS=2

# 灾害点数据源
HAZARD_POINTS_DIR=Z:\Code\Insar_management_system_v2\backend\Point
HAZARD_POINTS_FILENAME=Point.shp
```

鉴权说明：
- 系统不提供公开注册入口。
- 首次启动或重置管理员密码时，`INIT_ADMIN_PASSWORD` 为必填项（不再提供默认密码回退）。
- `scripts/init_db.py` 会检查管理员账号；若不存在则按 `INIT_ADMIN_*` 自动创建。
- 如需强制重置管理员密码：将 `INIT_ADMIN_RESET_PASSWORD=true`（仅重置当次生效，完成后建议改回 `false`）。
- 内网 HTTP 部署请保持 `AUTH_COOKIE_SECURE=false`；若启用 HTTPS，请改为 `true`。
- 登录防爆破参数：`AUTH_LOGIN_MAX_FAILURES`（窗口内失败阈值）、`AUTH_LOGIN_WINDOW_SECONDS`（失败统计窗口）、`AUTH_LOGIN_LOCK_SECONDS`（触发后锁定时长）、`AUTH_LOGIN_CLEANUP_INTERVAL_SECONDS`（限流状态表后台清理间隔，秒）。
- AOI 上传限流参数：`AOI_UPLOAD_MAX_FILES`（上传文件数量上限）、`AOI_UPLOAD_MAX_SINGLE_FILE_BYTES`（单文件字节上限）、`AOI_UPLOAD_MAX_TOTAL_BYTES`（同次请求总字节上限）。超限时接口返回 `HTTP 400`。
- 扫描请求边界参数：`MAX_SCAN_DIRECTORY_COUNT`（单次扫描请求目录数量上限）、`MAX_SCAN_PATH_LENGTH`（单路径字符串长度上限）。
- 高频列表查询边界参数：`LIST_QUERY_MAX_LIMIT`（单页最大返回条数）、`LIST_QUERY_MAX_OFFSET`（最大偏移）、`LIST_QUERY_MAX_WINDOW`（`limit+offset` 窗口上限），`LIST_QUERY_TIMEOUT_MS`（PostgreSQL 列表查询超时，毫秒）；`RADAR_SEARCH_OPTIONS_MAX_VALUES` / `RADAR_IMAGING_DATES_MAX_VALUES` 用于限制雷达检索选项和成像日期去重结果规模。
- 队列入队边界参数：`JOB_QUEUE_MAX_PAYLOAD_BYTES`（单任务 payload 字节上限）、`JOB_QUEUE_MAX_ATTEMPTS`（重试次数上限）、`JOB_QUEUE_MAX_PRIORITY_ABS`（优先级绝对值上限）、`JOB_QUEUE_MAX_ID_LENGTH`（关联 ID 字符上限）、`JOB_QUEUE_MAX_TYPE_LENGTH`（任务类型字符串上限）。
- 任务/日志查询边界参数：`TASK_ACTIVE_DEFAULT_LIMIT`、`TASK_ACTIVE_MAX_LIMIT`（`GET /api/tasks/active` 分页上限），`TASK_LOG_DEFAULT_LIMIT`、`TASK_LOG_MAX_LIMIT`、`TASK_QUERY_MAX_OFFSET`（任务日志分页上限），`MONITOR_LOG_DEFAULT_LIMIT`、`MONITOR_LOG_MAX_LIMIT`、`MONITOR_LOG_MAX_OFFSET`（`GET /api/monitor/logs` 分页与偏移上限）。
- 批次与复制请求边界参数：`TASK_BATCH_MAX_ITEMS`（单批次条目数上限）、`TASK_BATCH_TEXT_MAX_LENGTH`（批次名称/方向长度上限）、`TASK_BATCH_REMARK_MAX_LENGTH`（条目备注长度上限）、`TASK_BATCH_LIST_DEFAULT_LIMIT` / `TASK_BATCH_LIST_MAX_LIMIT` / `TASK_BATCH_LIST_MAX_OFFSET`（批次列表与明细分页上限）、`COPY_BATCH_TEXT_MAX_LENGTH`（复制接口 `batch_id`/`dest_dir` 长度上限）、`COPY_BATCH_MAX_STATUS_COUNT`（复制状态列表数量上限）。
- 工作流请求边界参数：`WORKFLOW_MAX_STEPS`（单工作流步骤上限）、`WORKFLOW_MAX_DEPENDS`（单步骤依赖数上限）、`WORKFLOW_TEXT_MAX_LENGTH`（工作流文本字段长度上限）。
- AI 地图分析请求边界参数：`AI_ANALYZE_MAP_MAX_IMAGES`（单次请求图片数上限）、`AI_ANALYZE_MAP_MAX_IMAGE_BASE64_CHARS`（单图 Base64 长度上限）、`AI_ANALYZE_MAP_PROMPT_MAX_CHARS`（prompt 长度上限）。
- 授权上传默认采用“先校验后替换”的原子更新流程；无效授权不会覆盖当前在用授权文件。
- `MAX_LICENSE_UPLOAD_BYTES` 用于限制授权上传文件大小（默认 1MB）。
- `CORS_ORIGINS` 建议配置为明确白名单；生产环境不建议使用 `*`。
- 当 `CORS_STRICT_MODE=true` 时，若 `CORS_ORIGINS` 包含 `*` 且 `CORS_ALLOW_CREDENTIALS=true`，服务将拒绝启动。
- 严禁将包含真实 `DATABASE_URL`、`LICENSE_SECRET` 的 `.env` 提交到代码仓库或共享目录。
- 管理员可通过 `GET /api/auth/audit-logs?limit=200` 查看最近审计日志（仅 admin 可访问）。
- 许可文件上传与刷新接口（`POST /api/license/upload`、`POST /api/license/refresh`）仅允许管理员会话访问。
- 前端入口：左侧「运行维护」分组下新增「用户管理」「审计日志」两个管理员面板。

源影像缓存说明：
- 系统在扫描雷达源数据时，会尝试在每个场景目录中查找预览图（jpg/jpeg/png/webp/bmp/tif/tiff）并生成 WebP 缓存。
- 雷达缓存目录：`backend/image_cache/radar_geo/`（主）与 `backend/image_cache/radar_raw/`（回退）。
- D-InSAR 缓存目录：`backend/image_cache/dinsar/`（统一使用 `ID_{id}_{name}.webp`）。
- 前端「数据列表」支持源影像单条显示/隐藏与“一键显示/一键隐藏”。
- 长期稳定方案（后端预纠正缓存，B 方案）设计见：`docs/RADAR_PREVIEW_SCHEME_B.md`。

---

## 11. 启动方式

### 11.1 一键启动（推荐）
双击：
```
start_system.bat
```

或命令行：
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start_app.ps1
```

说明：
- 启动链路保持不变：`start_system.bat` -> `scripts/start_app.ps1` -> `check_db_connection.py` -> `init_db.py`。
- `scripts/start_app.ps1` 中 `PYTHON_PATH` 支持“绝对路径”或“命令名”（例如 `python`）；脚本会先解析为可执行文件再调用。
- `init_db.py` 会在“建库/校验修复”后执行鉴权初始化（自动补齐管理员账号）。
- 扫描调度默认 Manual-only，不会后台定时自动触发；需通过前端或 `/api/monitor/run-now` 手动触发扫描。
- 默认不执行破坏性重建；若确需重建，请显式设置 `DB_SCHEMA_RESET_ON_MISMATCH=true`。

### 11.2 仅启动后端（无 Nginx）
```powershell
D:\anaconda3\Scripts\conda.exe run -n InSAR python run_backend.py
```

说明：后端默认绑定 `127.0.0.1`，仅本机访问。

### 11.3 后台队列 Worker（必需）
系统后台任务已改为“入队执行”，必须启动 Worker 才会真正执行扫描、AI、解包、复制等任务。

启动方式：
```powershell
D:\anaconda3\Scripts\conda.exe run -n InSAR python run_worker.py
```

说明：
- `start_system.bat` 已包含 Worker 启动。
- 若只运行 `run_backend.py`，请手动启动 `run_worker.py`。
- 数据分发/复制任务仅从“批次”读取，不再支持 Excel。
- `POST /api/monitor/run-now` 的 `target` 仅支持：`radar`、`orbit`、`dinsar`（留空表示全部）。

Worker 可选环境变量：
```
JOB_WORKER_POLL_INTERVAL=1.0   # 轮询间隔（秒）
JOB_WORKER_CONCURRENCY=1       # 并发执行数
JOB_WORKER_JOB_HEARTBEAT_INTERVAL=5   # 运行中作业心跳上报间隔（秒）
JOB_WORKER_STALE_RECOVER_INTERVAL=15  # 僵尸 RUNNING 作业回收检查间隔（秒）
JOB_WORKER_STALE_RUNNING_SECONDS=300  # 判定作业僵尸的超时阈值（秒）
IDL_JOB_MAX_ATTEMPTS=6                # IDL 队列任务最大重试次数
```

ENVI/SARscape 集成（envipyengine）：
- 执行引擎：`envipyengine`（pip 包）→ `taskengine.exe` 子进程
- 工作流在独立 Python 子进程中执行，隔离 FastAPI 主进程
- D-InSAR 工作流自动检测未导入数据，先执行 Import 再处理 D-InSAR（智能串联）
- DEM 路径为系统级配置，存储在 `.env` 的 `IDL_DINSAR_DEM_BASE_FILE`
- 运行日志目录：`backend/runtime/idl_worker/`

ENVI 关键环境变量：
```
IDL_EXECUTABLE=...                       # IDL 可执行路径
IDL_WORKBENCH_PATH=...                   # IDL Workbench 路径
IDL_WORKER_RUNTIME_DIR=...               # 运行日志目录
IDL_WORKER_DEFAULT_TIMEOUT_SECONDS=14400 # 单任务执行超时（秒）
IDL_WORKER_MAX_TIMEOUT_SECONDS=43200     # 单任务允许最大超时（秒）
IDL_DINSAR_DEM_BASE_FILE=...             # DEM 路径（D-InSAR 必需）
```

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         — 最近运行记录
```

提交任务请求体示例：
```json
{
  "root_dir": "Z:/Test_data/Test_IDL_1",
  "num_to_process": 0,
  "timeout_seconds": 14400
}
```

说明：
- 提交后会创建系统任务并入队，由 `run_worker.py` 消费执行。
- D-InSAR 工作流自动检测未导入数据，先执行 Import 再处理（智能串联）。
- DEM 路径从 `.env` 读取，不需要在请求中传递。
- Worker 在执行时会周期性更新作业心跳；若进程崩溃导致作业长期停留 `RUNNING`，会自动回收。
- 运行日志保存在 `IDL_WORKER_RUNTIME_DIR/` 下。

### 11.4 前端构建（仅构建时需要）
```powershell
cd frontend
npm install
npm run build
```

说明：
- 前端日期控件已统一为 `flatpickr`（原生实例接入），无需浏览器原生 `input[type=date]`。
- 若采用“本地构建后上传 `frontend/dist`”部署方式，服务器端无需额外安装前端依赖包。

### 11.5 离线切片底图切换
前端从 `frontend/public/tiles/` 读取离线切片，当前支持三套（统一 `webp`）：
- `tiles/google_image/{z}/{x}/{y}.webp`
- `tiles/gaode_image/{z}/{x}/{y}.webp`
- `tiles/gaode_shp/{z}/{x}/{y}.webp`

地图右上角「底图」按钮可在三套底图间切换（默认 `gaode_shp`，便于仅下载高德矢量时直接可用）。

缩放级别已放开到 0-16；如需调整默认底图或级别，请修改 `frontend/src/App.jsx` 中的 `TILE_LAYER_DEFAULT_KEY` 与 `TILE_LAYER_OPTIONS`。

行政区边界叠加图层（地图参考边界）默认读取：
- `frontend/public/geojson/全国行政区.geojson`

建议使用 UTF-8 无 BOM 编码，且文件体积较大时优先通过 `public/` 静态加载（不要直接放入 `frontend/src` 参与打包）。

地图左上角新增「区域定位」按钮（可折叠），复用行政区二级级联（省/市）：
- 可只选择到省级或市级进行定位。
- 定位时会调用后端 `/api/aoi/regions/{tree_id}/geometry` 获取边界并自动缩放到该区域。
- 定位成功后，面板会显示“当前定位”行政区名称，方便与当前视角对照。
- 面板支持「清除定位高亮」，可一键移除地图上的定位边界高亮。
- 依赖 `backend/geojson/层级映射.json` 与 `backend/geojson/全国行政区.geojson` 的行政区数据。

---

## 12. 访问与验证
- **前端**：`http://SERVER_HOST`
- **后端（内部）**：`http://127.0.0.1:8000`
- **接口文档（内部）**：`http://127.0.0.1:8000/docs`

前端语言切换：
- 顶部状态栏新增 `中文 / EN` 切换按钮。
- 切换结果会保存在浏览器本地（`localStorage`），刷新页面后保持上次语言选择。
- 站内文案翻译映射位于 `frontend/src/i18n/translations.js`，新增界面文案时需同步补充映射，避免中英文混杂。
- 第二轮已补齐高频业务模块（批次/分发、运维自检、用户管理、审计日志、IDL 自动化、统计面板）常用文案映射。
- 第三轮已支持运行日志双语展示：右侧日志栏、数据监控日志、数据分发任务日志会随语言切换进行前端翻译。
- 当前词典已覆盖常见后端运行日志模板（扫描、拷贝、解包、任务生命周期）；若新增日志模板，建议同步补充词典条目。
- 收口说明：当前前端可见业务文案已基本完成双语覆盖，剩余英文主要为样式类名/技术标识（不面向客户显示）。

---

## 13. 常用脚本说明
- `start_system.bat`：一键启动入口（调用 PowerShell 启动脚本）
- `scripts/start_app.ps1`：启动后端 + Nginx，并执行数据库检查
- `run_backend.py`：仅启动后端服务
- `run_worker.py`：后台任务 Worker（队列执行）
- `scripts/check_db_connection.py`：数据库连接检查
- `scripts/init_db.py`：数据库结构检查与初始化
- `scripts/license_manager_gui.py`：授权文件生成与续期
- `scripts/get_fingerprint.py`：机器指纹获取
- `scripts/unpack_archives.py`：解包与数据整理（支持 tar.gz）
- `scripts/pack_environment.bat`：打包 Conda 环境（如使用）
- `scripts/auth_smoke_check.py`：鉴权冒烟检查（401/403/200 核心链路）

---

## 14. 常见问题

1) **Python executable not found**  
检查 `.env` 中 `PYTHON_PATH` 是否正确；可使用绝对路径，或在已激活 Conda 环境后填写 `python`。  
如启用 Conda 原生模式，还需确认 `CONDA_EXE` 与 `CONDA_ENV_NAME` 配置正确。

2) **数据库连接失败**  
确认 PostgreSQL 服务已启动、`DATABASE_URL` 正确，并运行 `scripts/check_db_connection.py` 测试。

3) **授权无效/过期**  
使用授权工具续期，检查系统时间是否回退过多。

4) **前端打不开但后端正常**  
确认 Nginx 已启动、`NGINX_PATH` 正确、前端已构建。  
若启动时报 `no "events" section in configuration`，请检查 `nginx/nginx.conf` 是否为空或损坏，需恢复包含 `events {}` 与 `http {}` 的完整配置。

5) **后端端口被占用（Address already in use / Access denied）**  
`scripts/start_app.ps1` 启动前会检查 `PORT` 对应监听占用；若被占用会直接报错并终止。  
请停止占用该端口的进程，或在 `.env` 中修改 `PORT` 后重试。  
脚本会在启动时自动把 `nginx/nginx.conf` 中的 `proxy_pass` 同步到该 `PORT`，无需手动改 Nginx 反向代理端口。

6) **后端或 Worker 启动后立即退出**  
`scripts/start_app.ps1` 会在拉起后端与 Worker 后做快速存活检查；若进程秒退，脚本会立即报错并退出。  
请优先检查终端输出与后端日志，常见原因包括端口冲突、依赖缺失、环境变量配置错误。

最小可用 `nginx.conf` 模板（按需替换路径，`proxy_pass` 端口需与 `.env` 的 `PORT` 一致）：
```nginx
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  localhost;

        root   "G:/Code/Insar_management_system_v2/frontend/dist";
        index  index.html;

        location / {
            try_files $uri $uri/ /index.html;
        }

        location /api/ {
            proxy_pass http://127.0.0.1:18000;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location /image_cache/ {
            alias  "G:/Code/Insar_management_system_v2/backend/image_cache/";
        }
    }
}
```

### 14.1 鉴权与登录排查

- **`GET /api/auth/me` 返回 `401`**：未登录状态下这是正常现象，前端应显示登录页。  
- **`POST /api/auth/login` 返回 `401`**：用户名或密码错误，先核对 `.env` 中 `INIT_ADMIN_USERNAME/INIT_ADMIN_PASSWORD`；若为首次启动且 `INIT_ADMIN_PASSWORD` 为空，初始化会直接报错。  
- **`POST /api/auth/login` 返回 `429`**：触发登录限流/锁定，等待 `Retry-After` 秒后重试，或调整 `AUTH_LOGIN_MAX_FAILURES / AUTH_LOGIN_WINDOW_SECONDS / AUTH_LOGIN_LOCK_SECONDS`。  
- **登录后接口仍持续 `401`**：检查浏览器是否携带 Cookie（请求需 `withCredentials=true`），并确认反向代理没有丢弃 `Set-Cookie` 头。  
- **需要重置管理员密码**：设置 `INIT_ADMIN_RESET_PASSWORD=true`，重启一次系统完成重置后再改回 `false`。  
- **Cookie 在内网 HTTP 不生效**：确认 `AUTH_COOKIE_SECURE=false`；只有 HTTPS 场景才应设置为 `true`。  
- **需要核查谁触发了高风险写操作**：使用 `GET /api/auth/audit-logs?limit=200`（管理员会话）。  
- **需要快速回归鉴权链路**：后端启动后运行 `D:\anaconda3\Scripts\conda.exe run -n InSAR python scripts/auth_smoke_check.py --base-url http://127.0.0.1:8000`。  

5) **任务一直处于“执行中”**  
确认 `run_worker.py` 已启动（或使用 `start_system.bat` 一键启动）。
- 若期望系统自动周期扫描：当前默认是手动模式（Manual-only），请使用前端“立即扫描”或调用 `POST /api/monitor/run-now`。

6) **配对结果异常或为空**  
- 影像日期需为 `YYYYMMDD` 格式（系统从文件夹名解析）。  
- AOI 支持 **SHP 上传** 与 **GeoJSON 传参**（`aoi_geojson`）两种模式。  
- AOI Shapefile 建议使用 EPSG:4326（WGS84），否则需先进行投影转换。  
- 若使用“行政区选择”，请准备标准 GeoJSON（见 17.7），并确保 `features[*].properties.treeID` 与 `backend/geojson/层级映射.json` 对应。

7) **灾害点导入为 0 条**  
请确保 Shapefile 中存在唯一标识字段（优先 `TYBH`），并具备经纬度或点几何：  
- 必填：`TYBH`（唯一编号）  
- 推荐：`hazard_type` / `hazard_name` / `city` / `county` / `township`  
- 坐标：点几何优先；若无几何，则读取经度/纬度字段  
数据源路径：`.env` 中 `HAZARD_POINTS_DIR` + `HAZARD_POINTS_FILENAME`（默认 `backend/Point/Point.shp`）。

8) **Excel 功能找不到了**  
Excel 导入/导出已移除，请使用“任务批次 + 数据分发”流程完成复制与人工状态管理。

9) **日志出现 “got Future attached to a different loop”**  
该错误通常由**子线程内创建事件循环并复用 asyncpg 连接**引起，多发生在自建 `asyncio.run(...)` 的耗时任务里。  
处理方式：  
- 确保所有耗时任务由 Worker 执行（统一事件循环），避免在线程内自行 `asyncio.run`。  
- 重启后端与 Worker 以释放异常连接。  
- 如仍复现，请检查是否有自定义脚本在子线程内直接调用数据库。  
  
  ---

## 15. 数据库结构自动对齐（重要）
系统每次启动会进行数据库结构检查：
- 首次启动：自动创建表结构。
- 后续启动：校验表/列/类型/可空性。
- 不一致（默认）：不做破坏性重建，仅补齐缺失结构并输出告警。
- 不一致（显式开启）：仅当 `DB_SCHEMA_RESET_ON_MISMATCH=true` 时执行 drop/recreate 重建。

推荐在生产/内网环境保持如下默认值（保留历史数据）：
```
DB_SCHEMA_RESET_ON_MISMATCH=false
```

### 15.1 SQL 函数更新说明
若修改了 `backend/migrations/002_spatial_functions.sql`（例如配对函数 `find_dinsar_pairs`），需要执行一次：
- 重新启动系统（`start_system.bat` 会自动调用 `scripts/init_db.py`）
- 或手动运行 `D:\anaconda3\Scripts\conda.exe run -n InSAR python scripts/init_db.py`

### 15.2 空间函数迁移（必需）
启动时会自动执行以下迁移文件（用于空间函数、视图与日志表）：
- `backend/migrations/001_st_intersection_agg.sql`
- `backend/migrations/002_spatial_functions.sql`

如需手工修改，请保证 SQL 语法正确且使用 UTF-8 编码。

---

## 16. 工作流与任务队列（新增）
后台任务已改为队列执行（DB Job Queue）：
- 复制、解包、扫描、AI 训练/预测/诊断等任务都会入队。
- Worker 执行任务并更新状态，前端可查看任务进度。
- 所有耗时任务在 Worker 的事件循环中执行，避免跨事件循环导致的 asyncpg 连接异常。

工作流 API：
- `POST /api/workflow/runs` 创建工作流实例
- `GET /api/workflow/runs/{run_id}` 查询运行状态与步骤

任务查询 API（新增分页参数）：
- `GET /api/tasks/active?limit=100&offset=0`
- `GET /api/tasks/{task_id}`
- `GET /api/tasks/{task_id}/logs?limit=100&offset=0`
- `GET /api/monitor/logs?limit=50&offset=0`

---

## 17. 任务批次管理（替代 Excel）
为适配 IDL 线下生产流程，D-InSAR 与 PS-InSAR 任务改为“批次”形式存储在数据库：
- 前端创建批次（不再使用 Excel 导入/导出）。
- 可按批次查看明细、手动标记完成、添加备注。
- 数据分发从批次中读取任务条目并复制到目标目录。
- Excel 导入/导出接口已移除。

相关 API：
- `POST /api/task-batches/dinsar`
- `GET /api/task-batches/dinsar?limit=200&offset=0`
- `GET /api/task-batches/dinsar/{batch_id}/items?limit=200&offset=0`
- `PATCH /api/task-batches/dinsar/{batch_id}/complete-all`
- `PATCH /api/task-batches/dinsar/items/{item_id}`
- `POST /api/task-batches/ps`
- `GET /api/task-batches/ps?limit=200&offset=0`
- `GET /api/task-batches/ps/{batch_id}/items?limit=200&offset=0`
- `PATCH /api/task-batches/ps/{batch_id}/complete-all`
- `PATCH /api/task-batches/ps/items/{item_id}`

数据分发 API：
- `POST /api/tools/copy-ps-stack` (body: `batch_id`, `dest_dir`, `copy_statuses?`)
- `POST /api/tools/copy-dinsar-pairs` (body: `batch_id`, `dest_dir`, `copy_statuses?`)
- `GET /api/tools/copy-status/{task_id}?limit=100&offset=0`

### 17.1 前端操作流程（推荐）
1) **生成候选列表**  
   - D-InSAR：左侧“干涉对配对”生成 pairs。  
   - PS-InSAR：左侧“PS 时序栈”生成 stack。  

2) **保存为批次**  
   - 点击“保存批次”，系统将当前列表写入数据库。  
   - 批次会自动生成 `batch_id`，支持自定义名称。  
   - 保存成功后前端会自动切换到“任务批次”并定位到新建批次。  

3) **批次管理与人工标注**  
   - 在右侧“任务批次”面板选择 D-InSAR 或 PS。  
   - 进入某批次后：  
      - 修改每条任务状态（PENDING / IN_PROGRESS / COMPLETED / FAILED）  
      - 接口仅接受上述四种状态值（大小写不敏感，非法值会返回 `400`）  
      - 为每条任务添加备注（如：文件损坏、未完成原因）  
      - 支持“一键全部完成”  

4) **数据分发（复制）**  
   - 进入“数据分发”面板选择批次与目标目录后启动复制。  
   - 可按任务状态筛选复制（默认仅复制 `COMPLETED`）。  
   - 复制任务由 Worker 执行，进度可在前端日志中查看。  
   - 若出现部分文件复制失败，任务最终会标记为 `FAILED`（不再误报成功）。  

### 17.2 批次数据结构（数据库）
系统会创建以下表：
- `dinsar_task_batches` / `dinsar_task_items`  
- `ps_task_batches` / `ps_task_items`  

每条 item 包含：
- `status`（人工状态）
- `remark`（备注）
- 任务路径与元数据（用于复制与后续追踪）

### 17.3 数据分发复制规则
**PS-InSAR：**  
- 复制源优先使用 `{original_path}_envi_import`（若存在）  
- 否则使用原始路径  

**D-InSAR：**  
- 为每个任务创建子目录：  
  - `<dest>/<task_name>/master`  
  - `<dest>/<task_name>/slave`  
- 若源目录内存在 `envi_import` 且非空，优先复制 `envi_import`  

### 17.4 Excel 迁移说明
历史流程若依赖 Excel：  
- 现在请在系统中生成批次并使用“数据分发”复制。  
- 复制任务仅接收 `batch_id`，不再接收 Excel 文件。  

### 17.5 API 示例（简化）
创建 D-InSAR 批次：
```json
POST /api/task-batches/dinsar
{
  "name": "DINSAR_20260208",
  "pairs": [
    {
      "task_name": "T001",
      "master": {"file_path": "D:/data/master1", "...": "..."},
      "slave": {"file_path": "D:/data/slave1", "...": "..."},
      "time_baseline_days": 12,
      "spatial_baseline_meters": 1234.5
    }
  ]
}
```

复制 D-InSAR 批次：
```json
POST /api/tools/copy-dinsar-pairs
{
  "batch_id": "xxxx-xxxx-xxxx",
  "dest_dir": "D:/IDL/tasks/dinsar",
  "copy_statuses": ["COMPLETED"]
}
```

### 17.6 配对参数说明（新增）
`/api/find-pairs` 支持以下可选参数（表单提交）：
- `require_same_imaging_mode`：是否要求主/辅影像成像模式一致（默认 `true`，空值视为不匹配）
- `require_same_polarization`：是否要求主/辅影像极化一致（默认 `true`，空值视为不匹配）
- `aoi_overlap_threshold`：AOI 覆盖比例阈值，计算方式为 `Area(image ∩ AOI) / Area(AOI)`，需主/辅影像同时满足
- `aoi_geojson`：可选，标准 GeoJSON 字符串（与 `files` 二选一或都不传）

系统会在候选配对数超过 3000 时返回提示信息。若数据库配对函数不可用，仅在影像数量 ≤1500 时允许回退计算，并返回强提醒。

前端已提供“成像模式一致 / 极化一致 / AOI 覆盖率阈值”的开关与输入框，默认关闭/0（不额外限制）。

### 17.7 行政区选择（SHP/行政区二选一）
生产规划弹窗中，AOI 来源支持：
- 上传 `SHP`（兼容旧流程）
- 行政区选择（省/市二级联动）

后端新增接口：
- `GET /api/aoi/regions/children?parent_tree_id=1`
- `GET /api/aoi/regions/{tree_id}/geometry`

相关环境变量（后端 `.env`）：
```
AOI_REGION_INDEX_FILE=backend/geojson/层级映射.json
AOI_REGION_GEOJSON_FILE=backend/geojson/全国行政区.geojson
```

### 17.8 行政区 GeoJSON 数据规范（需提前准备）
建议提供一个标准 `FeatureCollection` 文件（UTF-8），示例：
```json
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "treeID": "1-23-4",
        "name": "示例地市",
        "level": "city"
      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [[[ [116.0, 39.0], [116.2, 39.0], [116.2, 39.2], [116.0, 39.2], [116.0, 39.0] ]]]
      }
    }
  ]
}
```

字段要求：
- 必填：`properties.treeID`（与 `层级映射.json` 一致）
- 可选：`properties.name`、`properties.level`
- `geometry` 建议使用 EPSG:4326（经纬度）

说明：
- 当前前端行政区选择为省/市二级，不提供区县单独选择入口。
- 若仅提供区县级数据，系统会在省/市选择时自动合并其下级边界。
- 若仅提供到市级数据，前端可直接按市级选择，后端会在必要时回退到最近可用上级边界（市→省）。
- 若 `treeID` 不匹配或缺失，行政区选择将无法返回 AOI 边界。

---

## 18. 运维自检（新增）
系统提供运维自检接口与前端面板，用于快速判断关键服务状态。

后端接口：
```
GET /api/health
```

返回约束（安全脱敏）：
- 未登录或只读会话：返回最小健康摘要（`ok/timestamp` + 各子系统布尔状态与基础计数）。
- 管理员会话：返回完整诊断信息（包含错误详情、Worker 列表、外部服务状态细节）。

检查内容：
- 数据库连接 / PostGIS 扩展 / 关键表结构
  - 关键表覆盖包含：任务与队列（`system_tasks/task_logs/system_jobs/scan_states`）、工作流（`workflow_defs/workflow_runs/workflow_steps/workflow_artifacts`）、鉴权（`auth_users/auth_sessions/auth_audit_logs/auth_rate_limits`）等核心表
- Worker 心跳
- IDL/ENVI 状态
- Ollama 连通性
- Nginx 连通性
- 一致性异常汇总（来自 `GET /api/statistics`）：
  - D-InSAR 缓存：数据库标记与实际缓存文件是否一致
  - 源影像预览缓存：`READY` 状态与 `radar_geo/radar_raw` 文件是否一致
  - XML 读取：是否检测到 XML 以及关键字段是否成功入库

相关环境变量：
```
JOB_WORKER_HEARTBEAT_INTERVAL=5   # Worker 心跳上报间隔（秒）
JOB_WORKER_HEALTH_TIMEOUT=60      # 运维自检判定 Worker 离线的阈值（秒）
```

前端入口：
- 左侧「系统工具」->「运维自检」
- 顶部状态栏可一键刷新自检状态
- 运维自检面板新增「一致性检测」卡片，显示异常总数、严重/一般异常，并列出具体异常项

---

## 19. 一致性统计接口（新增）
用于检查“数据库记录、缓存文件、XML读取结果”是否一致。

后端接口：
```
GET /api/statistics
```

新增返回字段（关键）：
- `dinsar_cache_consistency`
  - `db_cached_but_file_missing_count`：数据库标记已缓存，但缓存文件不存在
  - `db_uncached_but_file_exists_count`：数据库标记未缓存，但缓存文件已存在
  - `manifest_missing_file_count`：`cache_manifest.json` 记录的缓存文件缺失
- `source_preview_consistency`
  - `preview_missing_count`：源影像预览缓存缺失（`radar_geo` 和 `radar_raw` 均不存在）
  - `db_ready_but_cache_missing_count`：数据库 `READY`，但预览缓存实际缺失
- `source_xml_consistency`
  - `xml_missing_count`：未检测到 XML
  - `xml_detected_but_unparsed_count`：检测到 XML 但关键字段未成功入库

前端展示位置：
- 「数据统计仪表盘」：新增一致性图表与异常高亮
- 「运维自检」：新增一致性异常汇总卡片（总数 / 严重 / 一般）

建议运维动作：
- 出现 `db_cached_but_file_missing_count` 或 `db_ready_but_cache_missing_count`：执行一次重扫重建缓存
- 出现 `xml_detected_but_unparsed_count`：检查对应场景 XML 格式与解析字段
- 出现 `xml_missing_count`：检查场景目录是否包含 XML 元数据文件

---

*© 2026 InSAR Management System - 致力于更高效、更智能的雷达遥感监测*