第十二章：数据质检（QC）步骤详解

数据质检步骤（qc.*）是 GeoPipeAgent 中最丰富的步骤类别，共 10 个，覆盖矢量几何检查、属性检查和栅格质量检查。

12.1 QC 步骤的核心机制

"检查并透传"模式

所有 QC 步骤都遵循同一个模式：

输入数据 → 检查逻辑 → 输出 = 原始数据（透传）
                   ↓
              issues 问题列表
              issues_gdf 问题要素 GeoDataFrame

• output：等于输入数据（透传，或 auto_fix=true 时为修复后数据）
• issues：QcIssue 对象列表（通过 StepResult.issues 访问）
• stats.issues_count：问题数量（可在 when 条件中引用）
• metadata.issues_gdf：问题要素的 GeoDataFrame（通过 $step.issues_gdf 引用）

这种设计允许多个 QC 步骤串联，每步检查不同规则，最后汇总所有问题。

QcIssue 数据结构

@dataclass
class QcIssue:
    rule_id: str          # 规则 ID（如 "geometry_validity"）
    severity: str         # 严重级别："error" / "warning" / "info"
    feature_index: int    # 问题要素的行索引（None 表示数据集级问题）
    message: str          # 问题描述（如 "Feature 42: Self-intersection at (120.5, 31.2)"）
    geometry: Any         # 问题位置几何（可选，用于可视化）
    details: dict         # 规则特定的详细信息

12.2 步骤总览

12.3 矢量 QC 步骤详解

qc.geometry_validity：几何有效性检查

检测的问题类型：自相交（Self-intersection）、空几何（Empty geometry）、NULL 几何（Null geometry）、环方向错误。

- id: check-geo
  use: qc.geometry_validity
  params:
    input: "$load-data"
    auto_fix: false
    severity: "error"

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

qc.crs_check：坐标参考系检查

检测：CRS 为空（无坐标系信息）、与 expected_crs 不一致。

- id: check-crs
  use: qc.crs_check
  params:
    input: "$load-data"
    expected_crs: "EPSG:4326"
  on_error: skip   # CRS 问题不阻断流程，但会记录

- id: reproject-if-needed
  use: vector.reproject
  params:
    input: "$load-data"
    target_crs: "EPSG:4326"
  when: "$check-crs.issues_count > 0"

qc.topology：拓扑关系检查

支持的规则：

- id: check-topo
  use: qc.topology
  params:
    input: "$load-parcels"
    rules: ["no_overlaps", "no_gaps"]
    tolerance: 0.001

qc.attribute_completeness：属性完整性检查

检测：字段不存在、字段值为 NULL/空字符串/空列表。

- id: check-completeness
  use: qc.attribute_completeness
  params:
    input: "$load-buildings"
    required_fields: ["name", "height", "use_type", "build_year"]
    severity: "warning"

qc.attribute_domain：属性值域检查

# 枚举值检查
- id: check-type
  use: qc.attribute_domain
  params:
    input: "$load-buildings"
    field: "use_type"
    allowed_values: ["residential", "commercial", "industrial", "public", "mixed"]

# 正则模式检查（邮政编码格式）
- id: check-postcode
  use: qc.attribute_domain
  params:
    input: "$load-addresses"
    field: "postcode"
    pattern: "^\\d{6}$"     # 6 位数字
    severity: "warning"

qc.value_range：数值范围检查

- id: check-height
  use: qc.value_range
  params:
    input: "$load-buildings"
    field: "height"
    min: 0
    max: 600      # 上海中心大厦约 632 米，超过 600 可能是异常值
    severity: "warning"

qc.duplicate_check：重复要素检查

- id: check-dup
  use: qc.duplicate_check
  params:
    input: "$load-poi"
    check_geometry: true           # 检查几何完全相同的要素
    check_fields: ["name", "type"] # 同时检查名称+类型完全相同的要素

12.4 栅格 QC 步骤详解

qc.raster_nodata：NoData 一致性检查

- id: check-nodata
  use: qc.raster_nodata
  params:
    input: "$load-dem"
    expected_nodata: -9999
    max_nodata_ratio: 0.2    # NoData 比例不超过 20%

qc.raster_resolution：分辨率一致性检查

- id: check-resolution
  use: qc.raster_resolution
  params:
    input: "$load-satellite"
    expected_x_res: 30     # Landsat 30 米分辨率
    expected_y_res: 30
    tolerance: 0.05        # 允许 5% 误差

qc.raster_value_range：栅格值域检查

- id: check-ndvi-range
  use: qc.raster_value_range
  params:
    input: "$calc-ndvi"
    min: -1.0
    max: 1.0
    severity: "warning"    # NDVI 理论范围 -1 到 1

12.5 完整矢量数据质检流水线

pipeline:
  name: "建筑物数据入库前全量质检"
  description: "对建筑物矢量数据进行完整质检：几何、坐标系、拓扑、属性"

  variables:
    input_path: "data/buildings.shp"
    expected_crs: "EPSG:4326"

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

    - id: check-crs
      use: qc.crs_check
      params:
        input: "$load-data"
        expected_crs: "${expected_crs}"
      on_error: skip

    - id: check-geometry
      use: qc.geometry_validity
      params:
        input: "$load-data"
        severity: "error"

    - id: check-topology
      use: qc.topology
      params:
        input: "$load-data"
        rules: ["no_overlaps", "no_gaps"]
        tolerance: 0.0001
      on_error: skip

    - id: check-completeness
      use: qc.attribute_completeness
      params:
        input: "$load-data"
        required_fields: ["name", "height", "build_year", "use_type"]
        severity: "warning"
      on_error: skip

    - id: check-type-domain
      use: qc.attribute_domain
      params:
        input: "$load-data"
        field: "use_type"
        allowed_values: ["R", "C", "I", "P"]   # 住宅/商业/工业/公共
        severity: "warning"
      on_error: skip

    - id: check-height-range
      use: qc.value_range
      params:
        input: "$load-data"
        field: "height"
        min: 0
        max: 700
        severity: "warning"
      on_error: skip

    - id: check-duplicates
      use: qc.duplicate_check
      params:
        input: "$load-data"
        check_geometry: true
        check_fields: ["name"]
      on_error: skip

    # 保存几何问题要素
    - id: save-geo-issues
      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

  outputs:
    crs_issues: "$check-crs.issues_count"
    geometry_issues: "$check-geometry.issues_count"
    topology_issues: "$check-topology.issues_count"
    completeness_issues: "$check-completeness.issues_count"
    domain_issues: "$check-type-domain.issues_count"
    range_issues: "$check-height-range.issues_count"
    duplicate_issues: "$check-duplicates.issues_count"

12.6 本章小结

本章详细介绍了 10 个 QC 步骤：

矢量 QC（7个）：

1. qc.geometry_validity：几何有效性，支持 auto_fix
2. qc.crs_check：坐标系验证
3. qc.topology：拓扑关系（重叠、缝隙、悬挂线）
4. qc.attribute_completeness：必填字段完整性
5. qc.attribute_domain：枚举值/正则模式检查
6. qc.value_range：数值范围检查
7. qc.duplicate_check：重复要素检查

栅格 QC（3个）：
8. qc.raster_nodata：NoData 设置与比例
9. qc.raster_resolution：分辨率一致性
10. qc.raster_value_range：像素值域检查

关键模式：$step.issues_count 用于条件判断，$step.issues_gdf 保存问题要素。

导航：← 第十一章：网络分析步骤 ｜ 第十三章：流水线引擎 →