VWED_server/VWED任务模块接口文档/外部任务接口文档.md

# 外部任务接口文档

## 外部任务模块接口

### 1. 创建新任务 (create_new_task)

#### 接口描述
根据任务类型自动选择对应的任务模板并执行任务，用于外部系统调用创建和启动任务。

#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/newTask`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| ReqCode | String | 是 | 请求唯一标识码 |
| SourceID | String | 否 | 来源ID |
| TargetID | String | 是 | 目标ID |
| TaskType | TaskTypeEnum | 是 | 任务类型 |

#### 任务类型枚举 (TaskTypeEnum)

| 枚举值 | 描述 | 模板ID |
|-------|------|-------|
| GG2MP | 高柜到MP | template_gg2mp_id |
| GGFK2MP | 高柜发库到MP | template_ggfk2mp_id |
| GT2MP | 高台到MP | 571985c1-cfa5-4186-8acd-6e3868a5e08c |
| GTFK2MP | 高台发库到MP | template_gtfk2mp_id |
| ZG2MP | 中柜到MP | template_zg2mp_id |
| QZ2MP | 清洗到MP | template_qz2mp_id |
| LG2MP | 料柜到MP | template_lg2mp_id |
| PHZ2MP | 配货站到MP | template_phz2mp_id |
| MP2GG | MP到高柜 | template_mp2gg_id |
| MP2GGFK | MP到高柜发库 | template_mp2ggfk_id |
| MP2GT | MP到高台 | template_mp2gt_id |
| MP2GTFK | MP到高台发库 | template_mp2gtfk_id |
| MP2ZG | MP到中柜 | template_mp2zg_id |
| MP2QZ | MP到清洗 | template_mp2qz_id |
| MP2LG | MP到料柜 | template_mp2lg_id |
| MP2PHZ | MP到配货站 | template_mp2phz_id |

#### 请求示例

```json
{
  "ReqCode": "123e4567-e89b-12d3-a456-426614174000",
  "SourceID": "WH-A-001",
  "TargetID": "WH-B-002",
  "TaskType": "GT2MP"
}
```

#### 响应参数

```json
{
  "code": 0,
  "reqCode": "123e4567-e89b-12d3-a456-426614174000",
  "message": "成功",
  "rowCount": 1
}
```

#### 错误响应

1. 不支持的任务类型时：
```json
{
  "code": 400,
  "reqCode": "123e4567-e89b-12d3-a456-426614174000",
  "message": "不支持的任务类型: UNKNOWN_TYPE",
  "rowCount": 0
}
```

2. 任务启动失败时：
```json
{
  "code": 500,
  "reqCode": "123e4567-e89b-12d3-a456-426614174000",
  "message": "任务启动失败",
  "rowCount": 0
}
```

3. 系统异常时：
```json
{
  "code": 500,
  "reqCode": "123e4567-e89b-12d3-a456-426614174000",
  "message": "创建任务失败: [详细错误信息]",
  "rowCount": 0
}
```

### 2. AGV调度任务 (GenAgvSchedulingTask)

#### 接口描述
用于生成AGV调度任务，支持更丰富的调度参数配置，包括位置路径、安全密钥验证等。

#### 请求方式
- **HTTP方法**: POST
- **接口路径**: `/GenAgvSchedulingTask`

#### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| ReqCode | String | 是 | 请求唯一标识码 |
| TaskTyp | String | 是 | 任务类型（使用TaskTypeEnum中的值） |
| SecurityKey | String | 是 | 安全密钥 |
| Type | String | 是 | 类型标识 |
| TaskCode | String | 是 | 任务代码 |
| SubType | String | 是 | 子类型标识 |
| AreaPositonCode | String | 是 | 区域位置代码 |
| AreaPositonName | String | 是 | 区域位置名称 |
| PositionCodePath | Array<PositionCodePath> | 是 | 位置代码路径 |
| ClientCode | String | 否 | 客户端代码 |
| TokenCode | String | 否 | 令牌代码 |

#### PositionCodePath 参数结构

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|-----|------|
| PositionCode | String | 是 | 位置代码 |
| Type | String | 是 | 类型 |

#### 请求示例

```json
{
  "ReqCode": "a98334b940af48328290389a64b71bcc",
  "TaskTyp": "MP2GGFK",
  "SecurityKey": "2JN4YW5IJSQRXDEPBT3YQKEGJMT2GS1X",
  "Type": "1",
  "TaskCode": "d074b178e9c54a72a484a782d8955aa3",
  "SubType": "3",
  "AreaPositonCode": "1-1",
  "AreaPositonName": "1-1,ZK",
  "PositionCodePath": [
    {
      "PositionCode": "AP190",
      "Type": "00"
    },
    {
      "PositionCode": "AP313",
      "Type": "04"
    }
  ],
  "ClientCode": "",
  "TokenCode": ""
}
```

#### 响应参数

```json
{
  "code": 0,
  "reqCode": "a98334b940af48328290389a64b71bcc",
  "message": "成功",
  "rowCount": 0
}
```

#### 错误响应

1. 安全密钥为空时：
```json
{
  "code": 400,
  "reqCode": "a98334b940af48328290389a64b71bcc",
  "message": "安全密钥不能为空",
  "rowCount": 0
}
```

2. 不支持的任务类型时：
```json
{
  "code": 400,
  "reqCode": "a98334b940af48328290389a64b71bcc",
  "message": "不支持的任务类型: UNKNOWN_TYPE",
  "rowCount": 0
}
```

3. 任务启动失败时：
```json
{
  "code": 500,
  "reqCode": "a98334b940af48328290389a64b71bcc",
  "message": "任务启动失败",
  "rowCount": 0
}
```

4. 系统异常时：
```json
{
  "code": 500,
  "reqCode": "a98334b940af48328290389a64b71bcc",
  "message": "创建任务失败: [详细错误信息]",
  "rowCount": 0
}
```

## 通用说明

### 响应码说明

| 响应码 | 描述 |
|-------|------|
| 0 | 成功 |
| 400 | 请求参数错误 |
| 404 | 资源不存在 |
| 409 | 冲突（如任务已在运行） |
| 500 | 服务器内部错误 |

### 安全说明

1. 所有接口都需要提供有效的请求标识码(ReqCode)
2. AGV调度任务接口需要提供有效的安全密钥(SecurityKey)
3. 系统会记录所有请求的客户端信息和来源
4. 建议在生产环境中启用HTTPS

### 调用注意事项

1. 请求标识码(ReqCode)应保证全局唯一性
2. 任务类型必须在支持的枚举范围内
3. 系统会根据任务类型自动选择对应的任务模板
4. 位置代码路径用于指定AGV的行驶路径
5. 系统支持并发调用，但相同设备的相同任务可能有限制

### 监控和日志

1. 所有接口调用都会记录详细日志
2. 支持通过ReqCode追踪任务执行状态
3. 错误信息会包含足够的上下文用于排查问题
4. 建议定期监控接口响应时间和成功率