# 工作流 TaskNode 合约（v0.1.820 / 8.2.0）

本文件记录 `guanwf` 结构化 DSL 的平台事实源。合约来自当前 `workflow_web` 节点定义和
`guandata-workflow` DTO/校验逻辑；未知或版本新增字段由 `nodes/<id>/task.json` 无损保留。

## 通用字段

所有结构化节点导出 `id/name/type/desc/params/preTasks/preTaskScheduleTypes`，并带平台默认的
`runFlag/retryEnabled/maxRetryTimes/retryInterval/workerGroupId/taskTimeoutParameter`。Go DSL
字段覆盖 `task.json`，base-only 字段保留。依赖始终以 `workflow.go` 为准。

## 工作流参数

`Workflow.Params` 保存到 `processDefinitionJson.globalParams`。平台识别：

- `STRING`、`NUMBER`、`DATE`；bool 兼容为 STRING，日期时间/时间宏兼容为 DATE。
- 字段：`name/description/valueType/defaultValue/optionValue/customize/multiple/freeze/paramType`。
- 引用：`[WORKFLOW_PARAMS.name]`、`[DYNAMIC_PARAMS.name]`、
  `[DATADRIVEN_PARAMS.name]`、`[BUILTIN_PARAMS.name]`。
- `run --param key=value` 复制完整参数对象并只覆盖 `value`。

`required` 是本地 DSL 元数据，当前平台没有同名持久化字段；因此
`ParamRequired()` 会在本地导出校验时要求提供非空 `DefaultValue`，确保保存到平台后仍有可执行值。

## 节点 params

| TaskNode.type | 结构化 DSL | 已确认 params |
|---|---|---|
| `DATASET` | `DatasetNode` | `datasetId/datasetName/dbAccount/dbType/dirPath/displayType/schemaSql/uniformResourceType/updateSql` |
| `SHELL` | `ShellNode` | 仅模型保留；8.2.0 后端未注册，CLI 拒绝保存 |
| `HTTP` | `HTTPNode` | `connectionConfig{type,url,headers,parameters,body,authentication}`，以及递归轮询配置 |
| `SQL` | `SQLNode` | `cnId/acId/sql/preSqlList/postSqlList/fieldConfigs` |
| `PARAMETER_ASSIGNMENT` | `ParameterAssignmentNode` | `dataSourceType/sql/fieldConfigs`；DATABASE 使用 `cnId/acId`，DATASET 使用 `dsId/dsName/dirPath/displayType` |
| `SWITCH` | `SwitchNode` | `switchResult.dependTaskList[]`，每项含 `nextNode/combineType/conditions` |
| `LOOP` | `LoopNode` | 仅模型保留；8.2.0 后端未注册，CLI 拒绝保存 |
| `SUB_PROCESS+PROCESS` | `SubWorkflowNode` / `SubTaskNode` | `subProcessId/subProcessName/subProcessParams/subProcessDynamicParams/runTimeParams` |

## 关键语义

- `PARAMETER_ASSIGNMENT` 是查询结果列到数据驱动参数的映射，不是任意 key/value 赋值。
- DATASET 必须使用已有数据集的 `datasetId`。8.2.0 的 DATASET 执行器只会按 ID 触发 BI
  数据集刷新，不会根据 `datasetName + schemaSql` 创建数据集；需要创建/写入目标数据集时，
  应使用 DATAFLOW/DB_DATAFLOW 的输出节点。`DATA_SET_OFFLINE_DEV` 不能用于 DatasetNode：8.2.0
  会把刷新接口的文本响应当 JSON，CLI 会提前阻断并提示改用产出工作流的 SubWorkflowNode。
- 参数赋值的 `DATASET` 来源遵守 8.2.0 后端 SQL 执行契约。数据库直连数据集会返回 60006，
  CLI 会提前阻断；查询 StarRocks 表请改用 `DATABASE` 来源。后端支持的非直连抽取/离线开发
  产出数据集可使用 `DATASET` 来源（这是 CLI 相对页面选择器的明确扩展），SQL 中表名为 `input1`。
- `SWITCH.nextNode` 必须是 Switch 的直接 DAG 下游节点。
- SHELL/LOOP 的字段模型供兼容导入和后续版本使用，不代表 8.2.0 可执行能力。
- Switch/条件 Loop 的 `combineType` 仅支持 `AND/OR`，FilterType 与 FieldType 必须是 BI
  条件评估接口支持的枚举，参数来源和值不能为空。
- `LOOP` 循环调用另一个工作流，不内嵌任意节点；模式为 `ITERATE` 或 `CONDITION`，
  `maxLoopTimes` 为 2–500，默认 128；遍历项必须提供 `prop/type`。
- HTTP 当前确认 GET/POST。认证值只保存在权限为 0600 的 `task.json`；导入不把明文凭据复制到
  `workflow.go`。
- SQL TaskNode 与数据流内部 `SQL_SCRIPT` 是两类节点。
- 无法满足当前合约的旧 payload 自动回退 `RawTask`，避免导入时虚构字段或破坏保存结果。

## 外置文件

- SHELL: `script.sh`
- SQL / PARAMETER_ASSIGNMENT: `query.sql`
- HTTP: `body.json` 或 `body.txt`；递归请求体为 `recursion-body.txt`
- 所有路径必须位于对应节点目录内，禁止 `..` 或绝对路径逃逸。