# 调度定义 API 契约 V1

冻结日期：2026-07-28  
状态：`implemented`

## 1. 范围

本契约只覆盖调度定义，不触发任务执行：

- 调度方案增删改查；
- 稳定版本制品列表；
- 节点和连线增删改；
- 五段 Cron 校验与未来时间预览；
- DAG 完整性和有向无环校验。

立即运行、Cron 自动触发、Redis Streams 事件和 Worker 执行属于后续小步。

## 2. 请求上下文

所有接口都要求：

| Header | 含义 |
|---|---|
| `X-User-ID` | 当前用户 |
| `X-Workspace-ID` | 当前 Workspace |
| `X-Request-ID` | 请求追踪 ID；可省略，由服务端生成 |

服务端只返回当前 Workspace 的调度。节点引用的 `versions_id` 必须属于当前
Workspace，且当前用户有权读取。

## 3. HTTP 接口

| 方法 | 路径 | 作用 |
|---|---|---|
| `GET` | `/api/v1/schedule-artifacts` | 查询可加入调度的稳定版本 |
| `POST` | `/api/v1/cron/preview` | 校验 Cron 并预览未来时间 |
| `GET` | `/api/v1/schedules` | 查询调度列表 |
| `POST` | `/api/v1/schedules` | 新建调度 |
| `GET` | `/api/v1/schedules/{schedule_id}` | 查询调度及完整 DAG |
| `PUT/PATCH` | `/api/v1/schedules/{schedule_id}` | 修改调度基本信息 |
| `DELETE` | `/api/v1/schedules/{schedule_id}` | 软删除调度 |
| `POST` | `/api/v1/schedules/{schedule_id}/nodes` | 新建节点 |
| `PUT` | `/api/v1/schedules/{schedule_id}/nodes/{node_id}` | 修改节点 |
| `DELETE` | `/api/v1/schedules/{schedule_id}/nodes/{node_id}` | 删除节点及关联连线 |
| `POST` | `/api/v1/schedules/{schedule_id}/edges` | 新建有向连线 |
| `PUT` | `/api/v1/schedules/{schedule_id}/edges/{edge_id}` | 修改连线条件 |
| `DELETE` | `/api/v1/schedules/{schedule_id}/edges/{edge_id}` | 删除连线 |
| `POST` | `/api/v1/schedules/{schedule_id}/validate` | 校验当前 DAG |

成功响应统一为：

```json
{
  "request_id": "01...",
  "data": {},
  "meta": {}
}
```

## 4. 并发修改契约

新建调度时 `workflow_version=1`。每次修改调度、节点或连线都必须在请求体中
提交当前 `workflow_version`，成功后版本号加一。

版本不一致时返回 `412 Precondition Failed`：

```json
{
  "detail": {
    "code": "WORKFLOW_VERSION_CONFLICT",
    "message": "schedule was modified by another request",
    "expected": 3,
    "current": 4
  }
}
```

前端收到 `412` 后必须重新读取调度，不得用旧画布直接覆盖。

## 5. 调度与 Cron 约束

- `trigger_type`：`manual / cron / api`；
- `failure_policy`：`stop / continue`；
- Cron 固定为五段：`minute hour day month weekday`；
- 时区使用 IANA 名称，例如 `Asia/Shanghai`；
- `cron` 类型必须提供 `cron_expression`，其他类型不得提供；
- 新建的空调度不能直接启用；
- 只有 DAG 校验通过的调度才能设为 `enabled=true`；
- `next_run_at` 在数据库和接口中按 UTC 保存和返回。

Cron 预览请求示例：

```json
{
  "cron_expression": "*/5 * * * *",
  "timezone": "Asia/Shanghai",
  "count": 5,
  "base_time": "2026-07-28T08:00:00+08:00"
}
```

## 6. 节点与 DAG 约束

- 节点必须引用不可变稳定版本 `versions_id`，不能引用工作副本；
- 同一个调度内 `node_key` 唯一；
- 节点保存超时、重试、位置、参数和环境引用；
- 连线的起点、终点必须属于同一调度；
- 不允许自环、重复连线和有向环；
- 删除节点会同时删除与该节点相连的边；
- 已有运行历史的节点不能物理删除；
- 校验结果返回根节点、叶节点、拓扑顺序和错误列表。

## 7. 典型状态码

| 状态码 | 场景 |
|---|---|
| `201` | 调度、节点或连线创建成功 |
| `404` | 调度、稳定版本、节点或连线不存在/不可见 |
| `409` | 名称冲突、重复连线、DAG 成环或无效 DAG 启用 |
| `412` | `workflow_version` 已过期 |
| `422` | 请求字段、Cron、时区或节点归属不合法 |