第02章 - 快速入门与环境配置

本章带你从零开始搭建 OpenGIS DAF 的运行环境，编译源码，运行内置的”新星市”演示，并亲手创建、校验、执行你的第一个数据处理方案。

2.1 环境要求

2.1.1 运行时与 SDK

OpenGIS DAF 基于 .NET 10（C# 14）构建，跨平台支持 Windows / Linux / macOS。

提示：框架通过 NuGet 包（GDAL/OGR 3.x、NetTopologySuite 2.6、Npgsql 10.0 等）管理原生依赖，无需手动安装 GDAL 到系统。首次运行会自动解压原生库。

2.1.2 验证 .NET 环境

dotnet --version
# 期望输出类似：10.0.x

若未安装，请到 dotnet.microsoft.com 下载 .NET 10 SDK。

2.2 获取源码

2.2.1 克隆仓库

OpenGIS DAF 使用 git submodule 引入底层工具库 opengis-utils-for-net，克隆时需一并拉取：

git clone --recurse-submodules https://github.com/znlgis/opengis-daf.git
cd opengis-daf

若已克隆但未带子模块，可补拉：

git submodule update --init --recursive

2.2.2 仓库结构速览

opengis-daf/
├── src/                    # 8 个源码工程
│   ├── OpenGisDAF.Adapters/       # 数据源/输出适配器层
│   ├── OpenGisDAF.Cli/            # 命令行入口
│   ├── OpenGisDAF.Core/           # 核心契约与模型
│   ├── OpenGisDAF.Execution/      # 执行引擎
│   ├── OpenGisDAF.Infrastructure/ # 基础设施（配置/日志/加密）
│   ├── OpenGisDAF.Operators/      # 内置算子池
│   ├── OpenGisDAF.PlanManagement/ # 方案管理
│   └── OpenGisDAF.Scheduling/     # DAG 调度引擎
├── tests/                  # 集成测试
├── demo/                   # 自包含学习演示（"新星市"）
├── docs/                   # 官方文档
├── extern/opengis-utils-for-net/ # git 子模块
├── OpenGisDAF.slnx         # 解决方案文件
├── global.json             # .NET 版本锁定
├── build.ps1 / build.sh    # 跨平台构建脚本
└── README.md

2.3 编译

2.3.1 一键构建

仓库提供跨平台构建脚本：

# Windows (PowerShell)
./build.ps1

# Linux / macOS
./build.sh

2.3.2 手动构建

dotnet build OpenGisDAF.slnx -c Release

构建产物位于各工程的 bin/Release/net10.0/ 目录。CLI 入口为 OpenGisDAF.Cli。

2.3.3 运行 CLI

# 查看帮助
dotnet run --project src/OpenGisDAF.Cli -- --help

# 或直接运行已构建的产物
dotnet src/OpenGisDAF.Cli/bin/Release/net10.0/OpenGisDAF.Cli.dll --help

提示：为方便后续命令，可将 CLI 产物路径加入 PATH，或使用 dotnet run --project src/OpenGisDAF.Cli -- <参数> 形式。下文统一用 daf 代指 CLI 可执行文件。

2.4 运行内置演示

仓库的 demo/ 目录是一个自包含的学习演示，虚构了一座”新星市”，包含学校、道路、地块、城市边界等合成数据（全部由 tools/generate_testdata.py 生成，纯 Python 标准库，无第三方依赖）。

2.4.1 一键运行全部演示

cd demo
./run-demo.ps1    # Windows
# 或
./run-demo.sh     # Linux / macOS

该脚本会依次运行全部演示方案，并对每一步的退出码做断言，帮助你确认环境正确。

2.4.2 手动运行单个方案

# 运行学校服务区分析（主线 6 步 DAG）
daf run --plan plans/01-school-service-area.json

# 运行数据质量检查（5 条质检规则）
daf run --plan plans/02-data-quality-check.json

运行产物写入 demo/output/ 目录。

2.5 创建并执行你的第一个方案

2.5.1 准备数据

OpenGIS DAF 支持 GeoJSON、Shapefile、PostGIS 等数据源。最简单的方式是直接使用 demo/data/ 下的合成数据，或准备一个 GeoJSON 文件。

2.5.2 编写方案 JSON

方案是一个纯 JSON 配置文件，描述”读什么 → 怎么处理 → 写到哪里”。下面是一个最小方案：读取学校点，做 800 米缓冲，输出为 GeoJSON。

{
  "id": "my-first-plan",
  "name": "我的第一个方案",
  "version": "1.0.0",
  "items": [
    {
      "id": "buffer-schools",
      "operatorId": "buffer",
      "inputs": {
        "source": {
          "type": "external",
          "sourceId": "data/schools.geojson"
        }
      },
      "parameters": {
        "distance": 800
      },
      "output": {
        "adapterType": "geojson",
        "targetPath": "output/my-first-plan/buffer.geojson"
      }
    }
  ]
}

2.5.3 校验方案

执行前先用 validate 检查方案是否合法（框架内置 21 条校验规则，会拦截参数缺失、类型错误、绑定不完整、DAG 环等问题）：

daf validate --plan my-first-plan.json

校验通过无输出即表示方案合法。

2.5.4 执行方案

daf run --plan my-first-plan.json

执行成功后，output/my-first-plan/buffer.geojson 即为缓冲结果。

2.6 常用 CLI 命令一览

退出码约定：0 表示成功；1 表示出错（参数错误、校验失败或执行失败）。只要有失败或跳过的项，CLI 即返回 1，便于在 CI 中判断。

2.7 本章小结

• OpenGIS DAF 基于 .NET 10，跨平台，通过 NuGet 管理 GDAL 原生依赖，无需手动安装。
• 克隆需带 --recurse-submodules 拉取 opengis-utils-for-net 子模块。
• demo/ 目录提供自包含的”新星市”学习演示，run-demo.ps1/run-demo.sh 可一键运行。
• 一个方案 = 一个 JSON 文件，描述数据源、算子链、输出目标。
• 推荐流程：validate 先校验 → run 执行 → 检查退出码。

下一章将深入讲解方案配置的完整结构。