第10章 - 方案管理与最佳实践

前九章覆盖了从框架概念到插件扩展的完整技术栈。本章聚焦”工程化”层面：如何管理方案资产、如何把 OpenGIS DAF 接入真实生产流程，以及沉淀下来的最佳实践。

10.1 方案管理

10.1.1 用户数据目录

方案管理命令（plan list / plan create / plan copy / plan export）操作的是用户数据目录：

• Windows：%APPDATA%\opengis-daf\plans
• Linux/macOS：~/.config/opengis-daf/plans（或平台对应目录）

这与 daf run --plan <path> 直接执行文件路径不同——管理命令把方案作为可版本化的资产存入用户目录。

10.1.2 常用管理命令

10.1.3 方案版本与分组

方案顶层结构包含 version（推荐语义化版本号）与 group（可选分组）字段。合理的分组与版本管理，能让方案资产像代码一样被组织、复用与演进。

10.2 方案校验：把错误挡在执行前

框架内置 21 条方案校验规则，覆盖参数存在性/类型/范围、输入绑定完整性、DAG 环检测等。daf validate 与 daf run 都会在执行前拦截非法方案。

演示仓库的 invalid-missing-distance.json 故意构造了一个缺少必需参数的方案：

{
  "id": "demo-invalid-missing-distance",
  "name": "故意构造的非法方案（buffer 缺少必需参数 distance）",
  "group": "demo",
  "version": "1.0.0",
  "items": [
    {
      "id": "buffer-without-distance",
      "operatorId": "buffer",
      "inputs": {
        "source": {
          "type": "external",
          "sourceId": "data/schools.geojson"
        }
      },
      "output": {
        "adapterType": "geojson",
        "targetPath": "output/never-created.geojson"
      }
    }
  ]
}

运行校验：

daf validate --plan plans/invalid-missing-distance.json

输出 [ERR_CFG_PARAM_OUT_OF_RANGE]，提示缺少必需参数 distance，退出码 1。方案在执行前即被拦截，不会产生任何输出文件。

10.3 最佳实践

10.3.1 质量前置：先质检，后分析

演示仓库的 run-demo 建议工作流是：先跑方案 02（数据质检）发现并修复数据问题，再跑方案 01（空间分析）。无效几何（如蝴蝶结多边形）参与空间运算（如 clip 求交）会抛出 TopologyException，该要素被跳过并记录错误。与其在分析阶段排查莫名缺失的要素，不如在质检阶段就暴露问题。

10.3.2 坐标系先行

空间分析（buffer、clip、intersect）对坐标系敏感：

• 经纬度坐标系（如 4326）下，buffer 的 distance 单位是”度”，800 度毫无意义；
• 应先通过 coordinate_transform 转到米制投影坐标系（如 3857），再做空间运算；
• 面积/长度计算同样要求米制坐标系。

10.3.3 理解 clip 的逐面求交语义

clip 采用逐面求交语义：一个源要素与多个裁剪面相交时，会输出多条（可能分裂的）结果。这与 ogr2ogr/QGIS 先 union 再裁剪的行为不同。设计裁剪方案时需明确预期。

10.3.4 不要依赖 FID 作为业务主键

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

10.3.5 警惕 Shapefile 字段名限制

Shapefile 的 DBF 规范限制字段名 10 个字符。超过会被截断（如 landuse_type → landuse_ty），且截断无法自动恢复。跨数据源方案应优先引用短字段名。

10.3.6 用退出码驱动 CI

daf run 的退出码 0 表示全部成功，1 表示存在失败或跳过。在 CI 流水线中，应把退出码作为步骤成败的依据，让数据质量问题在构建阶段即被发现。

10.4 本章小结

• 方案管理命令把方案作为可版本化资产存入用户数据目录；
• 21 条校验规则把配置错误挡在执行前，validate 与 run 都会拦截；
• 最佳实践：质量前置、坐标系先行、理解 clip 语义、不依赖 FID、警惕 SHP 字段截断、用退出码驱动 CI。

至此，OpenGIS DAF 教程全部十章完成。从框架理念、方案配置、内置算子、数据适配，到质检实战、空间分析、失败调度、插件扩展与工程化实践，你已经掌握了用纯 JSON 方案驱动 GIS 数据分析与质检的完整方法。建议结合演示仓库动手运行每个方案，再尝试修改参数与编写自己的插件算子。