第03章 - 方案配置详解

方案（Plan）是 OpenGIS DAF 的核心抽象——一个纯 JSON 配置文件，完整描述”读什么数据、用什么算子处理、结果写到哪里”。本章逐层拆解方案配置的完整结构。

3.1 方案顶层结构

一个方案 JSON 由顶层字段、items（处理项数组）和可选的 executionPolicy（执行策略）组成：

{
  "id": "demo-01-school-service-area",
  "name": "学校服务区分析",
  "version": "1.0.0",
  "group": "demo",
  "items": [ ... ],
  "executionPolicy": {
    "failurePolicy": "stopOnAny",
    "maxParallelism": 4
  }
}

3.1.1 顶层字段

字段	类型	必填	说明
`id`	string	是	方案唯一标识
`name`	string	是	方案名称
`version`	string	是	版本号，推荐语义化（如 `1.0.0`）
`group`	string	否	分组，用于方案管理归类
`items`	array	是	处理项数组，至少 1 个
`subPlans`	array	否	子方案（当前 P3 阶段忽略）
`executionPolicy`	object	否	方案级执行策略

3.2 处理项（Item）

每个 item 描述一个独立的处理步骤，对应一个算子实例：

{
  "id": "buffer-schools",
  "operatorId": "buffer",
  "inputs": {
    "source": {
      "type": "upstream",
      "sourceId": "transform-schools",
      "outputKey": "output"
    }
  },
  "parameters": {
    "distance": 800
  },
  "output": {
    "adapterType": "geojson",
    "targetPath": "output/demo01/school-buffer-800m.geojson",
    "isIntermediate": true
  },
  "executionPolicy": {
    "timeout": "00:05:00",
    "maxRetries": 1,
    "retryInterval": "00:00:02"
  }
}

3.2.1 Item 字段

字段	类型	必填	说明
`id`	string	是	处理项标识，供上游绑定引用
`operatorId`	string	是	使用的算子标识（内置或插件）
`inputs`	object	是	输入绑定字典，键为算子定义的输入名
`parameters`	object	否	算子参数
`output`	object	是	输出目标
`executionPolicy`	object	否	处理项级执行策略

3.3 输入绑定（InputBinding）

inputs 的每个值是一个绑定对象，声明该输入的数据来源：

{
  "type": "external",          // external | upstream | subPlan
  "sourceId": "data/schools.geojson",  // 文件路径 或 上游 itemId
  "outputKey": "output"        // 可选，默认 "output"
}

字段	类型	说明
`type`	enum	`external`（外部文件/数据源）、`upstream`（引用上游处理项输出）、`subPlan`（子方案，P3 不支持）
`sourceId`	string	`external` 时为文件路径；`upstream` 时为上游处理项的 `id`
`outputKey`	string	可选，指定上游输出的哪个键，默认 `"output"`

示例：upstream 绑定把前一步的输出作为本步输入，从而串联成 DAG：

"inputs": {
  "source": {
    "type": "upstream",
    "sourceId": "buffer-schools"
  }
}

3.4 输出绑定（OutputBinding）

output 声明处理结果写到哪里：

{
  "adapterType": "geojson",
  "targetPath": "output/demo01/school-buffer-800m.geojson",
  "isIntermediate": true
}

字段	类型	说明
`adapterType`	string	输出适配器短名（`console`/`geojson`/`shapefile`/`postgis`）或枚举成员名（`ConsoleWriter`/`GeoJsonWriter`/`ShapefileWriter`/`PostGISWriter`），大小写不敏感
`targetPath`	string	输出路径（`console` 忽略）
`connectionConfig`	object	仅 `postgis` 需要；`encryptedPassword` 必须是 DPAPI/AES 密文，不能明文
`formatOptions`	object	可选，格式选项
`isIntermediate`	bool	是否为中间结果（可缓存复用，供下游引用）

重要：PostGIS 输出没有覆盖策略——目标表已存在会直接报错 Layer already exists，不会静默覆盖。这是保护生产数据的有意设计。

3.5 执行策略

3.5.1 方案级执行策略（PlanExecutionPolicy）

"executionPolicy": {
  "failurePolicy": "stopOnAny",
  "maxParallelism": 4
}

字段	类型	默认	说明
`failurePolicy`	enum	`stopOnAny`	`stopOnAny`：任一失败即停止；`continueIndependent`：失败后继续执行无依赖的独立项
`maxParallelism`	int	4	最大并行度（P2 阶段启用）

3.5.2 处理项级执行策略（ItemExecutionPolicy）

"executionPolicy": {
  "qcMode": false,
  "maxRetries": 0,
  "retryInterval": "00:00:05",
  "timeout": "00:30:00",
  "exponentialBackoff": true
}

字段	类型	默认	说明
`qcMode`	bool	false	质检模式，开启后算子以质检规则方式运行并输出问题
`maxRetries`	int	0	最大重试次数
`retryInterval`	string	`"00:00:05"`	重试间隔
`timeout`	string	`"00:30:00"`	超时时间
`exponentialBackoff`	bool	true	是否指数退避

注意：maxRetries 仅对执行期错误（ERR_RT_*）生效。输入/数据源解析失败（SCH_*，如文件不存在、上游不可用）在调度层直接失败，不重试。

3.6 方案校验

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

示例：一个 buffer 算子缺少必需的 distance 参数：

{
  "id": "demo-invalid-missing-distance",
  "name": "故意构造的非法方案",
  "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"
      }
    }
  ]
}

运行 validate：

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

输出：

[ERR_CFG_PARAM_OUT_OF_RANGE] 缺少必需参数'distance'.

退出码为 1，方案被拦截，不会执行。

3.7 本章小结

方案 = 顶层元数据 + items 处理项数组 + 可选执行策略。
每个处理项绑定一个算子，通过 inputs 的 external/upstream 绑定串联成 DAG。
output 声明写到哪里，isIntermediate 标记中间结果。
执行策略分方案级（失败策略/并行度）与处理项级（重试/超时/质检模式）。
21 条校验规则在 validate 与 run 前拦截非法方案。

下一章详解 9 个内置算子。

上一章：快速入门与环境配置目录下一章：内置算子详解