第06章 - 数据质检实战

数据质检是 OpenGIS DAF 的核心能力之一。本章通过演示方案 02（02-data-quality-check.json）讲解如何用质检规则算子对数据进行几何与属性检查，并解读自动生成的质量评分报告。

6.1 质检模式（qcMode）

质检规则算子运行在 qcMode: true 下。当一个处理项设置了 qcMode: true，其输出不再是普通要素，而是质检问题清单（issues）。

{
  "executionPolicy": { "qcMode": true }
}

质检完成后，框架自动生成质量报告文件 {plan}.qc-report.json，包含每条规则的统计与完整问题清单。

6.2 演示方案 02 概览

演示方案 02 对”新星市”的 5 类数据执行 5 条质检规则，全部为 qcMode: true：

处理项	算子	检查对象	预期发现
`qc-roads-geometry`	`geometry_validity_checker`	道路线	r05 自相交（Warning）
`qc-landuse-geometry`	`geometry_validity_checker`	地块面	p05 蝴蝶结（Error）
`qc-schools-attributes`	`attribute_completeness_checker`	学校属性	2 缺失 + 1 空串
`qc-landuse-overlap`	`intersect_check`	地块两两重叠	p01 × p02 重叠
`qc-road-in-ecozone`	`containment_check`	道路越界	r06 位于生态保护区内

方案完整配置：

{
  "id": "demo-02-data-quality-check",
  "name": "数据质量检查（几何 / 属性 / 地块重叠 / 用地越界）",
  "version": "1.0.0",
  "group": "demo",
  "items": [
    {
      "id": "qc-roads-geometry",
      "operatorId": "geometry_validity_checker",
      "inputs": { "source": { "type": "external", "sourceId": "data/roads.geojson" } },
      "output": { "adapterType": "console" },
      "executionPolicy": { "qcMode": true }
    },
    {
      "id": "qc-landuse-geometry",
      "operatorId": "geometry_validity_checker",
      "inputs": { "source": { "type": "external", "sourceId": "data/landuse.geojson" } },
      "output": { "adapterType": "console" },
      "executionPolicy": { "qcMode": true }
    },
    {
      "id": "qc-schools-attributes",
      "operatorId": "attribute_completeness_checker",
      "inputs": { "source": { "type": "external", "sourceId": "data/schools.geojson" } },
      "parameters": { "required_fields": "school_name,principal,phone,capacity,built_year" },
      "output": { "adapterType": "console" },
      "executionPolicy": { "qcMode": true }
    },
    {
      "id": "qc-landuse-overlap",
      "operatorId": "intersect_check",
      "inputs": { "source": { "type": "external", "sourceId": "data/landuse.geojson" } },
      "parameters": { "use_second_input": false },
      "output": { "adapterType": "console" },
      "executionPolicy": { "qcMode": true }
    },
    {
      "id": "qc-road-in-ecozone",
      "operatorId": "containment_check",
      "inputs": {
        "source": { "type": "external", "sourceId": "data/roads.geojson" },
        "target": { "type": "external", "sourceId": "data/landuse.geojson" }
      },
      "parameters": { "relationship": "within" },
      "output": { "adapterType": "console" },
      "executionPolicy": { "qcMode": true }
    }
  ],
  "executionPolicy": { "failurePolicy": "stopOnAny" }
}

6.3 运行质检

daf run --plan plans/02-data-quality-check.json

运行结束后，框架自动生成质量报告 plans/02-data-quality-check.qc-report.json。

6.4 解读质量报告

质量报告的结构如下：

{
  "totalScore": 83.67,
  "ruleStats": {
    "qc-roads-geometry": { "ruleId": "geometry_validity_checker", "totalChecked": 6, "passed": 6, "failed": 0, "passRate": 1 },
    "qc-landuse-geometry": { "ruleId": "geometry_validity_checker", "totalChecked": 5, "passed": 4, "failed": 1, "passRate": 0.8 },
    "qc-schools-attributes": { "ruleId": "attribute_completeness_checker", "totalChecked": 8, "passed": 6, "failed": 2, "passRate": 0.75 },
    "qc-landuse-overlap": { "ruleId": "intersect_check", "totalChecked": 5, "passed": 4, "failed": 1, "passRate": 0.8 },
    "qc-road-in-ecozone": { "ruleId": "containment_check", "totalChecked": 6, "passed": 5, "failed": 1, "passRate": 0.8333 }
  },
  "issues": [],
  "metadata": {
    "planId": "demo-02-data-quality-check",
    "planVersion": "1.0.0",
    "operatorVersion": "1.0.0.0",
    "dataSourceVersions": {},
    "executionTime": "2026-09-09T07:31:35.2663909+00:00"
  }
}

6.4.1 汇总质量评分

totalScore 是整体质量评分（本数据集为 83.67/100）。评分按各规则的实际检查要素数加权计算。

6.4.2 规则统计（ruleStats）

ruleStats 以处理项 ID 为键，每项包含：

字段	说明
`ruleId`	规则算子 ID
`totalChecked`	实际检查的要素数
`passed`	通过的要素数
`failed`	失败的要素数
`passRate`	通过率（`passed / totalChecked`）

6.4.3 问题清单（issues）

issues 数组包含每个违规问题的详情。每个 issue 的结构：

字段	说明
`issueId`	问题唯一 ID（GUID）
`planId`	所属方案 ID
`executionId`	执行 ID（GUID）
`itemId`	产生问题的处理项 ID
`featureId`	违规要素 ID（string）
`issueType`	问题类型（如 `GEOM_INVALID`、`ATTR_MISSING`）
`severity`	严重级别（`error`/`warning`）
`description`	问题描述
`contextData`	上下文数据
`violationGeometry`	违规几何的 WKT（或 null）

问题示例：

道路自相交（Warning）：GEOM_NOT_SIMPLE，violationGeometry: LINESTRING (110.22 30.16, 110.26 30.2, 110.22 30.2, 110.26 30.16)
地块蝴蝶结（Error）：GEOM_INVALID，violationGeometry: POLYGON ((110.23 30.22, 110.27 30.22, 110.23 30.25, 110.27 30.25, 110.23 30.22))
学校属性缺失（Error）：ATTR_MISSING，principal 字段为 null
学校电话空串（Warning）：ATTR_EMPTY，phone 字段为空字符串
地块重叠（Error）：INTERSECT，要素 0 与要素 1 相交
道路越界（Error）：WITHIN，要素 5 位于要素 3 内部

6.5 质检工作流建议

先质检，后分析。演示方案 01（空间分析）与方案 02（质检）针对同一数据集。推荐的完整工作流是：

先运行方案 02 发现数据问题；
修复数据（如删除无效几何、补全属性）；
再运行方案 01 做空间分析。

这样可避免无效几何在空间运算中引发异常（如蝴蝶结多边形参与 clip 求交会抛 TopologyException，该要素被跳过并记录错误）。

6.6 关于 featureId 的说明

质检报告中的 featureId 是底层驱动分配的要素 FID。当前 GDAL 通常从 0 开始，但不保证跨驱动/版本稳定，因此不能当作业务主键使用。若需要稳定标识，请在数据中自带 id 字段（演示数据的 s01/p01/r01 即为此设计）。

6.7 本章小结

质检规则算子运行在 qcMode: true 下，输出问题清单；
框架自动生成 {plan}.qc-report.json 质量报告，含汇总评分、规则统计与完整问题清单；
问题按严重级别分为 error/warning，并携带违规几何的 WKT；
推荐”先质检修复，后空间分析”的工作流；
featureId 不能当业务主键，稳定标识需自带 id 字段。