# Workflow 规范

## 概述

`workflow.yaml` 定义套件的步骤、参数和执行流程。

## 文件结构

```yaml
name: 套件名称
description: 套件功能描述
version: 1.0.0
author: 作者名
tags: [标签1, 标签2]
platform: all
category: 业务分类（如：土地整治）

params:
  input_path:
    type: string
    required: true
    desc: 输入文件路径
  buffer_distance:
    type: number
    default: 100
    desc: 缓冲区半径（米）

base_image: gis-base:latest

env:
  LOG_LEVEL: INFO

steps:
  - id: step1
    name: 步骤名称
    type: python
    runtime: python3
    script_id: run
    params:
      input: $params.input_path
      distance: $params.buffer_distance
```

## 字段说明

| 字段 | 必填 | 说明 |
|------|------|------|
| `name` | ✅ | 套件名称 |
| `description` | ✅ | 套件功能描述 |
| `version` | ✅ | 语义化版本号 |
| `slug` | ❌ | 英文包名。不传则从 name 自动转拼音 |
| `params` | ❌ | 参数声明（供用户查看） |
| `base_image` | ❌ | Docker 镜像，默认 `gis-base:latest` |
| `steps` | ✅ | 步骤列表，至少 1 步 |

### steps 字段

| 字段 | 必填 | 说明 |
|------|------|------|
| `id` | ✅ | 步骤唯一 ID |
| `name` | ❌ | 步骤显示名称 |
| `type` | ✅ | 步骤类型，当前固定为 `python` |
| `script_id` | ✅ | 脚本 ID（对应 scripts/ 下的 .py 文件名，不含扩展名） |
| `params` | ❌ | 步骤参数，值中使用 `$params.xxx` 引用用户输入 |
| `depends_on` | ❌ | 依赖的步骤 ID 列表，控制执行顺序 |

## 参数传递

步骤参数通过 `$params.xxx` 语法引用用户输入：

```yaml
params:
  input: $params.input_path     # 引用用户的 input_path 参数
  distance: $params.buffer_distance  # 引用用户的 buffer_distance 参数
```

引擎会自动：
1. 将用户提供的文件路径复制到工作目录
2. 替换路径为容器内可访问的路径（`/tmp/output/文件名`）
3. shapefile 自动复制配套文件（.shx/.dbf/.prj）

## 执行顺序

- 无 `depends_on` 的步骤并行执行
- 有 `depends_on` 的步骤在依赖步骤完成后执行
- 默认串行（`depends_on` 为空时按列表顺序执行）

## 步骤输出

每个步骤执行完成后，脚本向 stdout 输出 JSON 结果。步骤间的数据通过 `/tmp/output/` 目录共享。