第六章：条件执行、重试与错误策略

GeoPipeAgent 提供了强大的流程控制能力，包括条件执行（when）、自动重试（retry）和错误跳过（skip）。本章详细介绍这些机制的工作原理和最佳实践。

6.1 错误策略：`on_error`

on_error 字段控制步骤失败时的行为，可取三个值：fail（默认）、skip、retry。

6.1.1 `on_error: fail`（默认）

步骤失败时立即终止整个流水线，抛出 StepExecutionError。JSON 报告的 status 为 "error"。

- id: critical-step
  use: vector.clip
  params:
    input: "$load-data"
    clip: "$load-boundary"
  on_error: fail    # 裁剪失败则终止，不产生错误数据

适用场景：关键处理步骤，失败后继续执行会产生无意义的结果。

6.1.2 `on_error: skip`

步骤失败时跳过该步骤，步骤状态标记为 "skipped"，输出设为空 StepResult()，流水线继续执行后续步骤。

- id: optional-simplify
  use: vector.simplify
  params:
    input: "$load-data"
    tolerance: 0.001
    preserve_topology: true
  on_error: skip    # 简化失败时跳过，使用原始几何继续

注意：跳过步骤后，其输出为空 StepResult()。后续步骤若引用该步骤，需通过 when 条件判断，避免将空值传给下一个步骤。

适用场景：

可选的优化步骤（简化、平滑等）
某些数据可能不需要的处理步骤
非关键的输出步骤（如保存中间结果）

6.1.3 `on_error: retry`

步骤失败时自动重试，最多 3 次，每次重试前等待递增时间（0.5s、1s、1.5s）。若 3 次都失败，抛出 StepExecutionError。

- id: geocode-address
  use: network.geocode
  params:
    address: "北京市海淀区清华大学"
  on_error: retry   # 网络请求超时时自动重试

重试日志示例：

WARNING: Step 'geocode-address' attempt 1/3 failed: Connection timeout — retrying...
WARNING: Step 'geocode-address' attempt 2/3 failed: Connection timeout — retrying...
INFO: Step 'geocode-address' (network.geocode) completed in 2.341s

适用场景：

网络请求步骤（地理编码、API 调用）
可能因资源争用而偶发失败的步骤
外部服务不稳定时的容错处理

6.2 条件执行：`when`

when 字段接受一个条件表达式字符串。当表达式求值为 True 时，步骤正常执行；为 False 时，步骤状态标记为 "skipped"。

6.2.1 基本语法

- id: fix-geometry
  use: qc.geometry_validity
  params:
    input: "$load-data"
    auto_fix: true
  when: "$check-geometry.issues_count > 0"

6.2.2 支持的表达式

when 表达式通过 safe_eval.py 中的 AST 白名单安全求值，支持以下语法：

比较运算符：

when: "$step.issues_count > 0"
when: "$step.feature_count >= 100"
when: "$step.issues_count == 0"
when: "$step.crs != 'EPSG:4326'"

逻辑运算符：

when: "$check.issues_count > 0 and ${auto_fix} == true"
when: "$check.issues_count > 0 or ${force_fix} == true"
when: "not ${skip_qc}"

真值检查（步骤输出非空）：

when: "${enable_analysis}"     # 变量为 true 时执行
when: "${enable_analysis} == true"  # 等价写法

6.2.3 引用变量和步骤属性

在 when 中同样支持 ${var} 和 $step.attr：

pipeline:
  variables:
    enable_qc: true
    min_features: 10

  steps:
    - id: load-data
      use: io.read_vector
      params: { path: "data.shp" }

    # 基于变量的条件
    - id: check-geometry
      use: qc.geometry_validity
      params: { input: "$load-data" }
      when: "${enable_qc} == true"

    # 基于步骤 stats 的条件
    - id: report-small-dataset
      use: io.write_vector
      params:
        input: "$load-data"
        path: "warnings/small_dataset.geojson"
      when: "$load-data.feature_count < ${min_features}"

6.2.4 `when` 求值失败时的行为

若 when 表达式因解析错误或引用不存在的属性而无法求值，框架记录警告日志并将结果视为 False（步骤跳过）：

WARNING: Cannot evaluate when='$check.nonexistent > 0' (resolved='None > 0'), treating as False

这种”安全失败”策略避免了因条件表达式错误而中断流水线。

6.3 错误报告结构

当步骤失败时，JSON 报告会包含详细的错误信息：

{
  "error": "StepExecutionError",
  "step_id": "buffer-roads",
  "message": "CRS mismatch: input uses geographic CRS (EPSG:4326), but distance in meters requires a projected CRS.",
  "suggestion": "Add a vector.reproject step before this step to convert to a projected CRS.",
  "cause": "Operation `buffer` is not supported for geographic coordinates..."
}

框架内置了智能错误建议（_suggest_fix 函数），针对常见错误自动提供修复建议：

错误模式	自动建议
CRS 不匹配 / 地理坐标缓冲	在此步骤前添加 `vector.reproject` 转换为投影坐标系
CRS 为 None	设置 CRS 或确保源文件有 CRS 元数据
文件未找到	检查输入文件路径
权限错误	检查输入/输出路径的文件权限
不支持的格式	检查文件格式，支持 GeoJSON、Shapefile、GPKG
无效几何	在此步骤前添加 `qc.geometry_validity` 步骤
空几何	用 `vector.query` 过滤掉空几何要素
字段不存在	检查字段名是否正确，用 `io.read_vector` stats 查看可用字段

6.4 综合实战：QC 驱动的条件修复流水线

下面是一个综合运用 when、on_error: skip、on_error: retry 的完整示例：

pipeline:
  name: "数据入库前质检与修复"
  description: "对输入矢量数据进行质检，有问题则自动修复，最终校验并入库"

  variables:
    input_path: "data/buildings.shp"
    output_path: "output/buildings_clean.geojson"
    auto_fix: true

  steps:
    # 步骤1：读取数据
    - id: load-data
      use: io.read_vector
      params:
        path: "${input_path}"

    # 步骤2：坐标系检查（失败时跳过，不中断流程）
    - id: check-crs
      use: qc.crs_check
      params:
        input: "$load-data"
        expected_crs: "EPSG:4326"
      on_error: skip

    # 步骤3：几何有效性检查
    - id: check-geometry
      use: qc.geometry_validity
      params:
        input: "$load-data"
        auto_fix: false
        severity: "error"

    # 步骤4：仅在有几何问题时执行修复
    - id: fix-geometry
      use: qc.geometry_validity
      params:
        input: "$load-data"
        auto_fix: true
      when: "$check-geometry.issues_count > 0"
      on_error: skip     # 修复失败时跳过，用原始数据继续

    # 步骤5：拓扑检查（失败时跳过）
    - id: check-topology
      use: qc.topology
      params:
        input: "$load-data"
        rules: ["no_overlaps", "no_gaps"]
      on_error: skip

    # 步骤6：属性完整性检查（失败时跳过）
    - id: check-attrs
      use: qc.attribute_completeness
      params:
        input: "$load-data"
        required_fields: ["name", "height", "type"]
        severity: "warning"
      on_error: skip

    # 步骤7：保存质检问题报告（仅有问题时）
    - id: save-issue-report
      use: io.write_vector
      params:
        input: "$check-geometry.issues_gdf"
        path: "output/geometry_issues.geojson"
        format: "GeoJSON"
      when: "$check-geometry.issues_count > 0"
      on_error: skip

    # 步骤8：保存最终结果（优先使用修复后数据）
    - id: save-result
      use: io.write_vector
      params:
        input: "$fix-geometry"     # fix-geometry 若被跳过则为空，改用 load-data
        path: "${output_path}"
        format: "GeoJSON"

    # 步骤9：地理编码示例（网络失败时重试）
    - id: geocode-center
      use: network.geocode
      params:
        address: "北京市中心"
      on_error: retry

  outputs:
    result: "$save-result"
    geometry_issues: "$check-geometry.issues_count"
    topology_issues: "$check-topology.issues_count"
    attr_issues: "$check-attrs.issues_count"

6.5 `when` 与 `on_error` 的协同使用

when 和 on_error 是两个独立的机制，可以组合使用：

# 场景：可选的优化步骤，仅在开启优化选项时执行，执行失败时跳过
- id: optimize-topology
  use: vector.dissolve
  params:
    input: "$load-data"
    by: "type"
  when: "${enable_optimize} == true"   # 满足条件才尝试执行
  on_error: skip                       # 执行失败时跳过

执行逻辑：

若 when 为 False → 步骤状态 skipped，不执行（也不会触发 on_error）
若 when 为 True → 执行步骤：
- 成功 → 状态 success
- 失败 + on_error: skip → 状态 skipped，继续
- 失败 + on_error: retry → 重试 3 次，仍失败则终止
- 失败 + on_error: fail → 终止流水线

6.6 步骤被跳过后的引用处理

当步骤被跳过（status: skipped）时，其输出为空 StepResult()，即 output=None、stats={}。后续引用该步骤时需注意：

steps:
  - id: optional-fix
    use: qc.geometry_validity
    params: { input: "$load-data", auto_fix: true }
    when: "${apply_fix} == true"   # 可能被跳过

  # 危险：如果 optional-fix 被跳过，$optional-fix 为 None
  - id: buffer
    use: vector.buffer
    params:
      input: "$optional-fix"       # ⚠️ 若 optional-fix 被跳过，此处传入 None 会失败
      distance: 100

推荐处理模式：使用两个步骤，分别对应修复后数据和原始数据：

  # 使用修复后数据（若修复步骤被跳过则该分支也跳过）
  - id: buffer-fixed
    use: vector.buffer
    params:
      input: "$optional-fix"
      distance: 100
    when: "${apply_fix} == true"

  # 使用原始数据（当不需要修复时）
  - id: buffer-original
    use: vector.buffer
    params:
      input: "$load-data"
      distance: 100
    when: "${apply_fix} != true"

6.7 本章小结

本章全面介绍了 GeoPipeAgent 的流程控制机制：

on_error: fail（默认）：关键步骤失败时终止流水线
on_error: skip：可选步骤失败时跳过，继续执行
on_error: retry：网络/外部服务步骤失败时自动重试（最多 3 次）
when 条件：基于前置步骤输出或变量值，有选择地执行步骤
错误建议：框架内置智能错误建议，帮助快速定位和修复问题
协同使用：when 和 on_error 组合使用，构建健壮的自适应流水线

下一章将深入介绍 IO 步骤的使用方法，覆盖矢量和栅格数据的读写。

导航：← 第五章：变量与步骤引用｜第七章：IO 步骤详解 →

第六章：条件执行、重试与错误策略

6.1 错误策略：on_error

6.1.1 on_error: fail（默认）

6.1.2 on_error: skip

6.1.3 on_error: retry

6.2 条件执行：when