modelRT/doc/async_task_api.md

# ModelRT 异步任务 API 文档

## 1. 概述

ModelRT 异步任务系统基于 RabbitMQ 消息驱动，提供完整的任务生命周期管理。任务创建后进入队列，由后台 Worker 消费并执行，调用方可通过轮询接口获取进度和结果。

**Base URL**: `http://{host}:{port}`（默认 `localhost:8080`）

**鉴权**: 公开接口需在 Header 中携带 `X-Service-Token`（由服务端启动时生成）。

---

## 2. API 端点总览

| 方法   | 路径                               | 描述             | 权限   |
| :----- | :--------------------------------- | :--------------- | :----- |
| POST   | `/task/async`                      | 创建异步任务     | 公开   |
| GET    | `/task/async/results`              | 批量查询任务结果 | 公开   |
| GET    | `/task/async/{task_id}`            | 查询单个任务详情 | 公开   |
| POST   | `/task/async/{task_id}/cancel`     | 取消异步任务     | 公开   |
| POST   | `/task/internal/async/progress`    | 更新任务进度     | 内部   |
| POST   | `/task/internal/async/status`      | 更新任务状态     | 内部   |

---

## 3. 通用响应结构

### 成功响应

```json
{
  "code": 2000,
  "msg": "success message",
  "payload": {}
}
```

### 失败响应

```json
{
  "code": 4001,
  "msg": "error description",
  "payload": null
}
```

### 响应码说明

| code | 含义                   |
| :--- | :--------------------- |
| 2000 | 成功                   |
| 3000 | 处理失败               |
| 4001 | 请求参数无效           |
| 4002 | 未授权（Token 无效）   |
| 5000 | 服务器内部错误         |

---

## 4. 详细接口说明

### 4.1 创建异步任务

**POST** `/task/async`

创建新的异步任务，任务进入队列等待 Worker 消费。返回 `task_id` 用于后续查询。

**请求头**

```
Content-Type: application/json
X-Service-Token: <token>
```

**请求体**

```json
{
  "task_type": "TOPOLOGY_ANALYSIS",
  "params": { }
}
```

| 字段        | 类型   | 必填 | 说明                                                                              |
| :---------- | :----- | :--- | :-------------------------------------------------------------------------------- |
| `task_type` | string | 是   | 任务类型，枚举值见 §5.1                                                           |
| `params`    | object | 是   | 任务参数，不同任务类型的参数结构见 §5.3                                           |

**成功响应** `200`

```json
{
  "code": 2000,
  "msg": "task created successfully",
  "payload": {
    "task_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}
```

**失败响应**

| 场景               | code | msg                         |
| :----------------- | :--- | :-------------------------- |
| 参数格式错误       | 4001 | invalid request parameters  |
| task_type 不合法   | 4001 | invalid task type           |
| params 内容不合法  | 4001 | invalid task parameters     |
| 数据库连接失败     | 5000 | database connection error   |
| 任务写库失败       | 5000 | failed to create task       |

**curl 示例**

```bash
curl -X POST "http://localhost:8080/task/async" \
  -H "Content-Type: application/json" \
  -H "X-Service-Token: <token>" \
  -d '{
    "task_type": "TOPOLOGY_ANALYSIS",
    "params": {
      "start_component_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "end_component_uuid": "550e8400-e29b-41d4-a716-446655440001",
      "check_in_service": true
    }
  }'
```

---

### 4.2 批量查询任务结果

**GET** `/task/async/results`

根据一组任务 ID 批量查询状态和结果，适用于轮询多个任务。

**Query 参数**

| 参数       | 类型   | 必填 | 说明                                 |
| :--------- | :----- | :--- | :----------------------------------- |
| `task_ids` | string | 是   | 逗号分隔的 UUID 列表，最少 1 个      |

**请求示例**

```
GET /task/async/results?task_ids=123e4567-e89b-12d3-a456-426614174000,223e4567-e89b-12d3-a456-426614174001
```

**成功响应** `200`

```json
{
  "code": 2000,
  "msg": "query completed",
  "payload": {
    "total": 2,
    "tasks": [
      {
        "task_id": "123e4567-e89b-12d3-a456-426614174000",
        "task_type": "TOPOLOGY_ANALYSIS",
        "status": "RUNNING",
        "progress": 50,
        "created_at": 1741846200
      },
      {
        "task_id": "223e4567-e89b-12d3-a456-426614174001",
        "task_type": "PERFORMANCE_ANALYSIS",
        "status": "COMPLETED",
        "progress": 100,
        "created_at": 1741846200,
        "finished_at": 1741846260,
        "result": {
          "components_analyzed": 5
        }
      }
    ]
  }
}
```

**失败响应**

| 场景               | code | msg                         |
| :----------------- | :--- | :-------------------------- |
| 缺少 task_ids      | 4001 | task_ids parameter is required |
| UUID 格式不合法    | 4001 | invalid task ID format      |
| 数据库连接失败     | 5000 | database connection error   |
| 查询失败           | 5000 | failed to query tasks       |

**curl 示例**

```bash
curl "http://localhost:8080/task/async/results?task_ids=123e4567-e89b-12d3-a456-426614174000"
```

---

### 4.3 查询单个任务详情

**GET** `/task/async/{task_id}`

查询单个任务的完整信息，包含结果或错误详情。

**路径参数**

| 参数      | 类型   | 必填 | 说明            |
| :-------- | :----- | :--- | :-------------- |
| `task_id` | string | 是   | 任务 UUID       |

**成功响应** `200`

```json
{
  "code": 2000,
  "msg": "query completed",
  "payload": {
    "task_id": "123e4567-e89b-12d3-a456-426614174000",
    "task_type": "TOPOLOGY_ANALYSIS",
    "status": "COMPLETED",
    "progress": 100,
    "created_at": 1741846200,
    "finished_at": 1741846260,
    "result": {
      "path_exists": true,
      "path_length": 3,
      "path_nodes": ["comp-001", "comp-005", "comp-999"]
    }
  }
}
```

任务失败时 payload 附带错误信息：

```json
{
  "code": 2000,
  "msg": "query completed",
  "payload": {
    "task_id": "123e4567-e89b-12d3-a456-426614174000",
    "task_type": "TOPOLOGY_ANALYSIS",
    "status": "FAILED",
    "created_at": 1741846200,
    "finished_at": 1741846210,
    "error_code": 400102,
    "error_message": "Component UUID not found",
    "error_detail": {
      "component_uuid": "550e8400-0000-0000-0000-000000000000"
    }
  }
}
```

**失败响应**

| 场景               | code | msg                         |
| :----------------- | :--- | :-------------------------- |
| 缺少 task_id       | 4001 | task_id parameter is required |
| UUID 格式不合法    | 4001 | invalid task ID format      |
| 任务不存在         | 404  | task not found              |
| 数据库连接失败     | 5000 | database connection error   |

**curl 示例**

```bash
curl "http://localhost:8080/task/async/123e4567-e89b-12d3-a456-426614174000"
```

---

### 4.4 取消异步任务

**POST** `/task/async/{task_id}/cancel`

取消指定任务。**仅 `SUBMITTED`（排队中）状态的任务可以被取消**，已开始执行（`RUNNING`）或已结束的任务无法取消。

取消后任务状态变为 `FAILED`，错误码 `40003`，错误信息 `task cancelled by user`。

**路径参数**

| 参数      | 类型   | 必填 | 说明      |
| :-------- | :----- | :--- | :-------- |
| `task_id` | string | 是   | 任务 UUID |

**成功响应** `200`

```json
{
  "code": 2000,
  "msg": "task cancelled successfully"
}
```

**失败响应**

| 场景                     | code | msg                                                        |
| :----------------------- | :--- | :--------------------------------------------------------- |
| 缺少 task_id             | 400  | task_id parameter is required                              |
| UUID 格式不合法          | 400  | invalid task ID format                                     |
| 任务不存在               | 404  | task not found                                             |
| 任务已执行或已完成       | 400  | task cannot be cancelled (already running or completed)    |
| 数据库连接失败           | 500  | database connection error                                  |
| 取消操作失败             | 500  | failed to cancel task                                      |

**curl 示例**

```bash
curl -X POST "http://localhost:8080/task/async/123e4567-e89b-12d3-a456-426614174000/cancel"
```

---

### 4.5 内部接口：更新任务进度

**POST** `/task/internal/async/progress`

由 Worker 内部调用，更新任务执行进度（0-100）。

**请求体**

```json
{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "progress": 75
}
```

| 字段       | 类型   | 必填 | 说明              |
| :--------- | :----- | :--- | :---------------- |
| `task_id`  | string | 是   | 任务 UUID         |
| `progress` | int    | 是   | 进度值，范围 0-100 |

**成功响应** `200`

```json
{
  "code": 2000,
  "msg": "task progress updated successfully",
  "payload": null
}
```

---

### 4.6 内部接口：更新任务状态

**POST** `/task/internal/async/status`

由 Worker 内部调用，更新任务状态。当状态更新为 `COMPLETED` 或 `FAILED` 时，同步写入 `finished_at` 时间戳。

**请求体**

```json
{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "RUNNING",
  "timestamp": 1741846205
}
```

| 字段        | 类型   | 必填 | 说明                                     |
| :---------- | :----- | :--- | :--------------------------------------- |
| `task_id`   | string | 是   | 任务 UUID                                |
| `status`    | string | 是   | 目标状态，枚举值见 §5.2                  |
| `timestamp` | int64  | 是   | 状态变更时间戳（Unix 秒）                |

**成功响应** `200`

```json
{
  "code": 2000,
  "msg": "task status updated successfully",
  "payload": null
}
```

---

## 5. 数据结构参考

### 5.1 任务类型（task_type）

| 枚举值                 | 描述         |
| :--------------------- | :----------- |
| `TOPOLOGY_ANALYSIS`    | 拓扑连通性分析 |
| `PERFORMANCE_ANALYSIS` | 性能分析     |
| `EVENT_ANALYSIS`       | 事件分析     |
| `BATCH_IMPORT`         | 批量数据导入 |
| `TEST`                 | 测试任务（系统验证用） |

### 5.2 任务状态（status）

| 枚举值      | 描述               | 可转换至                        |
| :---------- | :----------------- | :------------------------------ |
| `SUBMITTED` | 已提交至队列       | `RUNNING`, `FAILED`（取消）     |
| `RUNNING`   | 正在执行           | `COMPLETED`, `FAILED`           |
| `COMPLETED` | 执行成功           | —                               |
| `FAILED`    | 执行失败或被取消   | —                               |

### 5.3 各任务类型的 params 结构

#### TOPOLOGY_ANALYSIS — 拓扑连通性分析

分析两个元件之间是否存在连通路径。

```json
{
  "start_component_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "end_component_uuid":   "550e8400-e29b-41d4-a716-446655440001",
  "check_in_service":     true
}
```

| 字段                   | 类型    | 必填 | 说明                                   |
| :--------------------- | :------ | :--- | :------------------------------------- |
| `start_component_uuid` | string  | 是   | 起始元件 UUID                          |
| `end_component_uuid`   | string  | 是   | 目标元件 UUID                          |
| `check_in_service`     | boolean | 否   | 是否只检查投运状态元件，默认 `true`    |

#### PERFORMANCE_ANALYSIS — 性能分析

```json
{
  "component_ids": ["comp-001", "comp-002"],
  "time_range": {
    "start": "2026-03-01T00:00:00Z",
    "end":   "2026-03-02T00:00:00Z"
  }
}
```

| 字段             | 类型     | 必填 | 说明                |
| :--------------- | :------- | :--- | :------------------ |
| `component_ids`  | []string | 是   | 待分析的元件 ID 列表（至少 1 个） |
| `time_range`     | object   | 否   | 分析时间范围        |

#### EVENT_ANALYSIS — 事件分析

```json
{
  "event_type":  "MOTOR_START",
  "start_time":  "2026-03-01T00:00:00Z",
  "end_time":    "2026-03-02T00:00:00Z",
  "components":  ["comp-001", "comp-002"]
}
```

| 字段          | 类型     | 必填 | 说明                |
| :------------ | :------- | :--- | :------------------ |
| `event_type`  | string   | 是   | 事件类型            |
| `start_time`  | string   | 否   | 事件起始时间（RFC3339） |
| `end_time`    | string   | 否   | 事件截止时间（RFC3339） |
| `components`  | []string | 否   | 关联的元件列表      |

#### BATCH_IMPORT — 批量导入

```json
{
  "file_path": "/data/import/model.csv",
  "file_type": "CSV",
  "options": {
    "overwrite":    false,
    "validate":     true,
    "notify_user":  true
  }
}
```

| 字段                   | 类型    | 必填 | 说明                              |
| :--------------------- | :------ | :--- | :-------------------------------- |
| `file_path`            | string  | 是   | 导入文件路径                      |
| `file_type`            | string  | 否   | 文件类型：`CSV`, `JSON`, `XML`    |
| `options.overwrite`    | boolean | 否   | 是否覆盖已有数据，默认 `false`    |
| `options.validate`     | boolean | 否   | 是否校验数据，默认 `true`         |
| `options.notify_user`  | boolean | 否   | 完成后是否通知用户，默认 `true`   |

#### TEST — 测试任务

```json
{
  "sleep_duration": 30
}
```

| 字段             | 类型 | 必填 | 说明                                            |
| :--------------- | :--- | :--- | :---------------------------------------------- |
| `sleep_duration` | int  | 否   | 模拟执行耗时（秒），默认 60，最大 3600          |

### 5.4 任务结果对象（AsyncTaskResult）

| 字段            | 类型   | 说明                                                 |
| :-------------- | :----- | :--------------------------------------------------- |
| `task_id`       | string | 任务 UUID                                            |
| `task_type`     | string | 任务类型                                             |
| `status`        | string | 当前状态                                             |
| `progress`      | int    | 进度（0-100），仅 `RUNNING` 时返回                   |
| `created_at`    | int64  | 创建时间戳（Unix 秒）                                |
| `finished_at`   | int64  | 完成时间戳（Unix 秒），仅 `COMPLETED`/`FAILED` 返回  |
| `result`        | object | 任务结果，仅 `COMPLETED` 时返回                      |
| `error_code`    | int    | 错误码，仅 `FAILED` 时返回                           |
| `error_message` | string | 错误描述，仅 `FAILED` 时返回                         |
| `error_detail`  | object | 错误详情，仅 `FAILED` 时返回                         |

---

## 6. 典型调用流程

```
创建任务
  └─ POST /task/async
       └─ 返回 task_id

轮询状态（建议间隔 2-5 秒）
  └─ GET /task/async/{task_id}
       ├─ status=SUBMITTED → 继续等待
       ├─ status=RUNNING   → 查看 progress
       ├─ status=COMPLETED → 读取 result 字段
       └─ status=FAILED    → 读取 error_code / error_message

如需中止（仅 SUBMITTED 状态有效）
  └─ POST /task/async/{task_id}/cancel
```

---

## 7. 队列配置参考

| 配置项         | 值                          |
| :------------- | :-------------------------- |
| Exchange       | `modelrt.tasks.exchange`    |
| Queue          | `modelrt.tasks.queue`       |
| Routing Key    | `modelrt.task`              |
| 优先级范围     | 0–10（默认 5）              |
| 消息 TTL       | 24 小时                     |
| 最大重试次数   | 3 次                        |
| 重试初始延迟   | 1 秒（指数退避，最大 5 分钟）|

---

**文档版本**: 1.1  
**最后更新**: 2026-04-28  
**相关文档**: [异步任务系统设计文档](./async_task_system.md)