# 天风任务系统 API 接口文档

## 目录

- [组件管理 API](#组件管理-api)
  - [获取所有组件类型及详细信息](#获取所有组件类型及详细信息)
  - [获取指定类型的组件详细信息](#获取指定类型的组件详细信息)
  - [自动发现并注册组件](#自动发现并注册组件)
- [任务管理 API](#任务管理-api)
  - [获取任务列表](#获取任务列表)
  - [获取任务类型列表](#获取任务类型列表)
  - [创建任务](#创建任务)
  - [删除任务](#删除任务)
  - [批量删除任务](#批量删除任务)
  - [更新任务基本信息](#更新任务基本信息)
  - [获取任务编辑信息](#获取任务编辑信息)（还没完成）
  - [获取可用的子任务列表](#获取可用的子任务列表)
- [任务参数管理 API](#任务参数管理-api)
  - [获取任务输入参数表单字段定义](#获取任务输入参数表单字段定义)
  - [获取任务输入参数配置](#获取任务输入参数配置)
  - [更新任务输入参数配置](#更新任务输入参数配置)

## 组件管理 API

### 获取所有组件类型及详细信息

获取系统中所有组件类型及其详细信息。

**接口地址**：`/component/components`

**请求方式**：`GET`

**请求参数**：无

**响应数据**：

```json
{
  "code": 200,
  "message": "获取组件类型成功",
  "data": {
    "component_types": ["string"],
    "component_type_info": [
      {
        "type": "string",
        "name": "string"
      }
    ],
    "component_categories": {
      "category": ["string"]
    },
    "component_details": ["object"],
    "component_details_by_type": {
      "type": ["object"]
    }
  }
}
```

**说明**：
- `component_types`: 所有组件类型的列表
- `component_type_info`: 包含中文名称的组件类型信息
- `component_categories`: 按类别分组的组件类型
- `component_details`: 所有组件的详细配置
- `component_details_by_type`: 按组件类型分组的详细配置

### 获取指定类型的组件详细信息

获取指定类型的组件详细信息。

**接口地址**：`/component/components/{component_type}`

**请求方式**：`GET`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| component_type | string | 是 | 组件类型 |

**响应数据**：

```json
{
  "code": 200,
  "message": "获取组件详细信息成功",
  "data": {
    "components": ["object"]
  }
}
```

**说明**：
- `components`: 指定类型的组件详细配置列表

### 自动发现并注册组件

自动发现并注册组件。

**接口地址**：`/component/components/discover`

**请求方式**：`POST`

**请求参数**：

```json
{
  "package_name": "string"
}
```

**响应数据**：

```json
{
  "code": 200,
  "message": "自动发现组件成功，共发现 x 个组件",
  "data": {
    "component_types": ["string"]
  }
}
```

**说明**：
- `component_types`: 发现的组件类型列表

## 任务管理 API

### 获取任务列表

获取任务列表，支持多种筛选条件、排序和分页。

**接口地址**：`/tasks`

**请求方式**：`GET`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| status | string | 否 | 任务状态 |
| task_type | string | 否 | 任务类型 |
| name | string | 否 | 任务名称（模糊查询）|
| is_scheduled | boolean | 否 | 是否为定时任务 |
| created_start | integer | 否 | 创建时间起始（毫秒时间戳）|
| created_end | integer | 否 | 创建时间结束（毫秒时间戳）|
| sort_by | string | 否 | 排序字段，默认为 CREATED_AT |
| sort_order | string | 否 | 排序方式，默认为 DESC |
| page | integer | 否 | 页码，默认为 1 |
| page_size | integer | 否 | 每页数量，默认为 10 |

**响应数据**：

```json
{
  "code": 200,
  "message": "获取任务列表成功",
  "data": {
    "tasks": ["object"],
    "pagination": {
      "page": 1,
      "page_size": 10,
      "total": 100,
      "total_pages": 10
    }
  }
}
```

**说明**：
- `tasks`: 任务列表
- `pagination`: 分页信息

### 获取任务类型列表

获取系统中所有任务类型列表。

**接口地址**：`/task/types`

**请求方式**：`GET`

**请求参数**：无

**响应数据**：

```json
{
  "code": 200,
  "message": "获取任务类型列表成功",
  "data": [
    {
      "key": "string",
      "name": "string",
      "description": "string",
      "value": "string"
    }
  ]
}
```

**说明**：
- `key`: 任务类型的键
- `name`: 任务类型的名称
- `description`: 任务类型的描述
- `value`: 任务类型的枚举值

### 创建任务

创建一个新任务。

**接口地址**：`/task/create`

**请求方式**：`POST`

**请求参数**：

```json
{
  "name": "string",
  "task_type": "string"
}
```

**响应数据**：

```json
{
  "code": 200,
  "message": "创建任务成功",
  "data": {
    "task_id": "string",
    "name": "string",
    "task_type": "string",
    "task_type_name": "string",
    "created_at": "timestamp",
    "updated_at": "timestamp"
  }
}
```

**说明**：
- `task_id`: 任务ID
- `name`: 任务名称
- `task_type`: 任务类型
- `task_type_name`: 任务类型中文名称

### 删除任务

删除指定ID的任务。

**接口地址**：`/task/{task_id}`

**请求方式**：`DELETE`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| task_id | string | 是 | 任务ID |

**响应数据**：

```json
{
  "code": 200,
  "message": "删除任务成功",
  "data": null
}
```

### 批量删除任务

批量删除多个任务。

**接口地址**：`/task/batch`

**请求方式**：`DELETE`

**请求参数**：

```json
{
  "task_ids": ["string"]
}
```

**响应数据**：

```json
{
  "code": 200,
  "message": "批量删除任务成功，共删除 x 个任务",
  "data": {
    "deleted_count": 0,
    "total_count": 0,
    "not_found_ids": ["string"]
  }
}
```

**说明**：
- `deleted_count`: 成功删除的任务数量
- `total_count`: 总共请求删除的任务数量
- `not_found_ids`: 未找到的任务ID列表

### 更新任务基本信息

更新任务的基本信息。

**接口地址**：`/task/{task_id}`

**请求方式**：`PUT`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| task_id | string | 是 | 任务ID |

```json
{
  "name": "string",
  "description": "string",
  "task_type": "string",
  "blocks": ["object"],
  "variables": ["object"],
  "schedule": "object"
}
```

**响应数据**：

```json
{
  "code": 200,
  "message": "更新任务成功",
  "data": {
    "task": "object"
  }
}
```

### 获取任务编辑信息

获取任务的编辑信息，包括任务实例、组件、参数等。

**接口地址**：`/task/{task_id}/edit`

**请求方式**：`GET`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| task_id | string | 是 | 任务ID |

**响应数据**：

```json
{
  "code": 200,
  "message": "获取任务编辑信息成功",
  "data": {
    "task": "object",
    "instance": "object",
    "component_types": "object",
    "common_params": "object",
    "task_input_params": ["object"],
    "block_output_params": "object",
    "context_params": "object"
  }
}
```

**说明**：
- `task`: 任务基本信息
- `instance`: 任务实例信息
- `component_types`: 组件类型信息
- `common_params`: 常用参数数据
- `task_input_params`: 任务输入参数
- `block_output_params`: 块输出参数
- `context_params`: 上下文参数

### 获取可用的子任务列表

获取可用的子任务列表，用于任务嵌套。

**接口地址**：`/tasks/available-subtasks`

**请求方式**：`GET`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| current_task_id | string | 否 | 当前任务ID，用于排除自身 |

**响应数据**：

```json
{
  "code": 200,
  "message": "获取可用子任务列表成功",
  "data": {
    "subtasks": [
      {
        "task_id": "string",
        "name": "string"
      }
    ]
  }
}
```

## 任务参数管理 API

### 获取任务输入参数表单字段定义

获取任务输入参数表单字段定义，用于前端表单生成。

**接口地址**：`/task/input-params/fields`

**请求方式**：`GET`

**请求参数**：无

**响应数据**：

```json
{
  "code": 200,
  "message": "获取任务输入参数表单字段定义成功",
  "data": {
    "form_fields": ["object"]
  }
}
```

**说明**：
- `form_fields`: 表单字段定义列表

### 获取任务输入参数配置

获取任务输入参数配置，包括系统默认参数和用户自定义参数。

**接口地址**：`/task/{task_id}/input-params`

**请求方式**：`GET`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| task_id | string | 是 | 任务ID |
| instance_id | string | 否 | 任务实例ID，不传则使用最新实例 |

**响应数据**：

```json
{
  "code": 200,
  "message": "获取任务输入参数成功",
  "data": {
    "task_id": "string",
    "instance_id": "string",
    "params": ["object"]
  }
}
```

**说明**：
- `params`: 任务输入参数列表

### 更新任务输入参数配置

更新任务输入参数配置，批量保存用户自定义的任务输入参数配置。

**接口地址**：`/task/{task_id}/input-params`

**请求方式**：`POST`

**请求参数**：

| 参数名 | 类型 | 必须 | 说明 |
|-------|------|------|------|
| task_id | string | 是 | 任务ID |
| instance_id | string | 否 | 任务实例ID，不传则使用最新实例或创建新实例 |

请求体：
```json
[
  {
    "param_name": "string",
    "label": "string",
    "param_type": "string",
    "required": true,
    "default_value": "any",
    "description": "string"
  }
]
```

**响应数据**：

```json
{
  "code": 200,
  "message": "更新任务输入参数成功",
  "data": {
    "task_id": "string",
    "instance_id": "string",
    "updated_params_count": 0,
    "has_changes": true
  }
}
```

**说明**：
- `updated_params_count`: 更新的参数数量
- `has_changes`: 是否有参数变动