Opengis Daf

项目地址： https://github.com/znlgis/opengis-daf

版本： 仓库主线（截至 2026-10，无 Release tag、无 NuGet 包；以 global.json 的 .NET SDK 10.0.301 为准）

许可证： MIT License

文档： https://github.com/znlgis/opengis-daf/tree/main/docs（快速入门、方案配置指南、算子参考、CLI 参考）

底层依赖： GDAL/OGR 3.x、NetTopologySuite 2.6.0、Npgsql 10.0.3、Serilog 4.4.0（实测各 *.csproj）

概述

OpenGIS Data Analysis Framework（简称 OpenGisDAF / daf）是一个方案驱动、纯配置定义的 GIS 数据分析与数据质检框架：用一个 JSON 方案（AnalysisPlan）描述"输入数据 → 算子处理 → 输出目标"的完整流程，可复用、可版本化。核心能力：

• 方案驱动：纯 JSON 定义分析流程，内置 21 条方案校验规则（参数存在性/类型/范围、绑定完整性、DAG 环检测）
• 空间分析：缓冲区、裁剪、相交检查、包含检查、坐标系转换（CRS 全链路传播，Z 值保留）
• 属性操作：字段计算器（表达式 + 算术解析器）、空值填充
• 数据质检：几何有效性、属性完整性检查，QC 模式自动生成质量评分报告
• DAG 调度：Kahn 拓扑排序，upstream 绑定串联算子，超时/重试/失败策略控制
• 多数据源/多输出：IFeatureSource（GeoJSON、Shapefile、PostGIS、内存）× IFeatureSink（控制台、GeoJSON、Shapefile、PostGIS）
• 插件扩展：AssemblyLoadContext 动态加载算子 DLL，插件算子与内置算子在同一 DAG 中无区别
• 方案管理：list/create/copy/export、版本回退、跨版本 Diff、原子写入

环境要求： .NET SDK 10.0（仓库 global.json 已锁定版本）、Git（克隆时需 --recurse-submodules，子模块 opengis-utils-for-net 提供 GDAL 绑定）。Windows x64 / Linux x64 / macOS。

环境准备与快速上手

bashCopy code
# 克隆（必须带子模块）
git clone --recurse-submodules https://github.com/znlgis/opengis-daf.git
cd opengis-daf
dotnet build            # 或 .\build.ps1 / ./build.sh

# 验证安装
dotnet run --project src/OpenGisDAF.Cli -- help

# 校验方案（不执行）
daf validate --plan plans/my-analysis.json
# 执行分析/质检
daf run --plan plans/my-analysis.json

测试须分两步（.NET 10 SDK + xunit.v3 工具链下 dotnet test 同命令构建会报"运行了零个测试"并退出码 5）：

bashCopy code
dotnet build OpenGisDAF.slnx --configuration Release
dotnet test OpenGisDAF.slnx --configuration Release --no-build

仓库自带完全自包含的学习 Demo（demo/，虚构"新星市"合成数据，一键脚本 demo/run-demo.ps1 / run-demo.sh 依次执行构建 → 算子清单 → 校验 → 4 个方案 → 插件演示，并对退出码断言）。

方案配置（核心）

顶层结构

分析项（items[]）

每个 item 一次算子调用：id（方案内唯一）、operatorId、inputs（绑定名 → InputBinding）、parameters（算子参数）、output（OutputBinding）、可选 executionPolicy（item 级：qcMode、maxRetries、retryInterval 默认 "00:00:05"、timeout 默认 "00:30:00"、exponentialBackoff）。

InputBinding：

jsonCopy code
{ "type": "external", "sourceId": "data/roads.shp" }
{ "type": "upstream", "sourceId": "step-clip", "outputKey": "output" }

type 取 external（文件路径）或 upstream（引用上游 item 的输出，outputKey 默认 "output"）。

OutputBinding：

jsonCopy code
{ "adapterType": "geojson", "targetPath": "output/result.geojson", "isIntermediate": false }

adapterType 推荐短名 console / geojson / shapefile / postgis（也接受枚举名 ConsoleWriter 等，大小写不敏感）；isIntermediate: true 标记中间结果可被缓存复用；PostGIS 需另加 connectionConfig。

最小示例（两步串联：裁剪 → 字段计算）

jsonCopy code
{
  "id": "serial-demo", "name": "串联分析", "version": "1.0.0",
  "items": [
    { "id": "step-clip", "operatorId": "clip",
      "inputs": { "source": { "type": "external", "sourceId": "data/polygons.geojson" },
                  "clip":   { "type": "external", "sourceId": "data/boundary.geojson" } },
      "output": { "adapterType": "geojson", "targetPath": "output/clipped.geojson" } },
    { "id": "step-field", "operatorId": "field_calculator",
      "inputs": { "source": { "type": "upstream", "sourceId": "step-clip" } },
      "parameters": { "target_field": "area_sqkm", "expression": "area * 0.000001", "field_type": "Double" },
      "output": { "adapterType": "geojson", "targetPath": "output/final.geojson" } }
  ],
  "executionPolicy": { "failurePolicy": "stopOnAny" }
}

内置算子（9 个）

field_type 取值：String / Integer / Double / Boolean / DateTime。

数据源与输出适配器

CLI 命令

退出码：0 成功；1 任何错误（参数错误、校验失败、执行失败）——只要有失败或跳过即返回 1，便于 CI 判断。

插件算子开发

插件只引用 OpenGisDAF.Core 的公共契约（IOperator / IFeature / IFeatureSource），通过 AssemblyLoadContext 动态加载。三个关键点：

1. 最小依赖面：自带 PluginFeature / PluginFeatureSource 简单实现，不引用任何实现层程序集。
2. 不要复制宿主程序集（最常见的坑）：csproj 中 ProjectReference 必须 Private="false" ExcludeAssets="runtime"——若把 OpenGisDAF.Core.dll 复制进插件目录，插件的 IOperator 与宿主不是同一 Type，算子被静默跳过（日志 "No IOperator implementations found"）。
3. schema 可选：输出源不实现 IFeatureSchemaProvider 也能工作，框架写输出时自动推断字段并集、几何类型与 CRS。

CLI 的 operator import 只在当前进程生效，daf run 是新进程——要让插件参与方案执行需同进程编程宿主（参考 demo/plugin/OpenGisDAF.PluginHostDemo）：

bashCopy code
dotnet build demo/plugin/OpenGisDAF.SamplePlugin/OpenGisDAF.SamplePlugin.csproj -c Release
dotnet build demo/plugin/OpenGisDAF.PluginHostDemo/OpenGisDAF.PluginHostDemo.csproj -c Release
dotnet demo/plugin/OpenGisDAF.PluginHostDemo/bin/Release/net10.0/OpenGisDAF.PluginHostDemo.dll \
    --plugin demo/plugin/OpenGisDAF.SamplePlugin/bin/Release/net10.0/OpenGisDAF.SamplePlugin.dll \
    --plan   demo/plugin/plans/road-length.json

典型工作流

先质检、后分析（推荐）

无效几何（蝴蝶结多边形等）参与 clip 求交会抛 TopologyException、该要素被跳过。正确顺序：

1. 跑质检方案（各 QC 算子 executionPolicy.qcMode: true），生成 {plan}.qc-report.json——含每条规则 totalChecked/failed/passed/passRate、汇总质量评分、完整 issue 清单（含 WKT 违规几何）；
2. 按 issue 修复数据；
3. 再跑分析方案。

容错策略

failurePolicy: "continueIndependent" 下：失败项的下游跳过、与其无依赖的项照常执行（demo 方案 04）。默认 stopOnAny 遇错即停。注意 maxRetries 仅对执行期运行时错误（ERR_RT_*，如超时）生效；输入文件不存在这类调度层错误（SCH_*）直接失败、不重试。

PostGIS 输出

output.adapterType: "postgis" + connectionConfig。encryptedPassword 必须是当前用户上下文生成的 DPAPI（Windows）/ AES-256-GCM（Linux/macOS，密钥文件权限 0600）密文，不能填明文；密文无效立即失败且错误信息不回显密文。

最佳实践

1. 先质检、后分析：无效几何（蝴蝶结多边形等）参与 clip 求交会抛 TopologyException 且要素被跳过；先跑 qcMode: true 的质检方案拿到 {plan}.qc-report.json，修完数据再跑分析方案
2. 失败策略按依赖关系选：默认 stopOnAny 遇错即停；无依赖的独立项用 continueIndependent 让失败项的下游跳过、其余照跑
3. 重试范围要清楚：maxRetries/retryInterval/exponentialBackoff 只对执行期运行时错误（ERR_RT_*，如超时）生效；调度层错误（如输入文件不存在）直接失败不重试
4. 凭据只放密文：PostGIS 输出的 encryptedPassword 必须是当前用户上下文生成的密文（Windows DPAPI / Linux、macOS AES-256-GCM 且密钥文件 0600），明文会被拒绝且错误信息不回显
5. 方案可复现：id/version 语义化并纳入版本管理，isIntermediate 标清楚中间产物，便于重跑与比对

常见问题

AI 使用建议

• 执行环境：先 dotnet --version，必须是 10.0（仓库 global.json 锁定），Windows 用 PowerShell；克隆必须 git clone --recurse-submodules，漏了子模块 opengis-utils-for-net 会在编译期报 GDAL 绑定类型缺失。
• 源码构建（无 NuGet 包）：dotnet build 或 ./build.sh，再 dotnet run --project src/OpenGisDAF.Cli -- help 确认 CLI 可用；这是自有项目，不要写 dotnet add package OpenGisDAF。
• 测试两步走：dotnet build OpenGisDAF.slnx -c Release 后 dotnet test OpenGisDAF.slnx -c Release --no-build——同一条 dotnet test 在 xunit.v3 工具链下会报“运行了零个测试”并以退出码 5 失败。
• 验证产物：先 daf validate --plan plans/my.json（只校验 21 条规则）再 daf run --plan plans/my.json；退出码 0 才是成功（失败或跳过都返回 1），随后重开输出 GeoJSON 核对 crs 与要素数，并查看 {plan}.qc-report.json 的 totalChecked/failed/passRate（仅 qcMode: true 才生成）。
• 典型误操：buffer 的 distance 单位随数据坐标系（EPSG:4326 下 800 就是 800 度），先 coordinate_transform 转米制；daf operator import 只对当前进程有效，要让插件参与 daf run 必须用同进程宿主（demo/plugin/OpenGisDAF.PluginHostDemo）。
• 插件坑：插件工程引用 OpenGisDAF.Core 时必须 Private="false" ExcludeAssets="runtime"，把 OpenGisDAF.Core.dll 复制进插件目录会让 IOperator 类型不同源，算子被静默跳过。
• 安全与权限：PostGIS 输出的 encryptedPassword 只接受当前用户上下文生成的密文（DPAPI / AES-256-GCM），明文或跨用户密文会失败；daf plan 写入 %APPDATA%\opengis-daf\plans，覆盖已有方案或输出文件前先确认路径。

相关技能

• nettopologysuite — .NET 几何计算核心：../nettopologysuite/SKILL.md
• opengis-utils-for-net — 底层 GDAL C# 绑定工具库（Git 子模块）：../opengis-utils-for-net/SKILL.md
• geopipe-agent — YAML 驱动的 AI 原生流水线（同类分析/质检框架）：../geopipe-agent/SKILL.md
• qgis-process — QGIS 命令行批处理（分析算子备选）：../qgis-process/SKILL.md

参考资源

• 仓库与文档：https://github.com/znlgis/opengis-daf（docs/quickstart.md、docs/plan-config-guide.md、docs/operator-reference.md、docs/cli-reference.md）
• 自包含教程 Demo：https://github.com/znlgis/opengis-daf/tree/main/demo（"新星市"规划分析：6 步 DAG 主线、QC 评分、SHP 闭环、失败策略、插件开发）
• 底层几何库：本仓库 NetTopologySuite SKILL、GDAL 元技能
• 配套工具库：https://github.com/znlgis/opengis-utils-for-net（Git 子模块，GDAL C# 绑定）
• 中文教程（znlgis）：https://znlgis.github.io/gis/tutorial/opengis-daf/