# 手动下发任务到 WCS 功能设计

**日期**: 2026-04-12
**状态**: 已批准

---

## 1. 功能概述

在 WMS 前端任务管理页面添加工具栏按钮，支持从任务列表中选择一个或多个任务，手动编辑地址（起点/终点）和优先级后，下发到 WCS 系统执行。

**使用场景**：当任务因设备故障、网络问题等原因未能正常下发时，操作员可手动重新下发。

---

## 2. 前端改动

### 2.1 新增文件

| 文件 | 用途 |
|------|------|
| `WMS/WIDESEA_WMSClient/src/extension/taskinfo/extend/dispatchTasksToWCS.vue` | 批量下发编辑弹窗组件 |

### 2.2 修改文件

| 文件 | 改动 |
|------|------|
| `WMS/WIDESEA_WMSClient/src/extension/taskinfo/task.js` | 添加工具栏"手动下发"按钮 |

### 2.3 弹窗交互

**触发方式**：工具栏点击"手动下发"按钮

**前置条件**：至少选中一项任务

**弹窗内容**：
- 顶部显示"已选任务数: N 个"
- 表格展示所有选中任务，列：任务号、起点地址、终点地址、优先级、状态
- 地址字段：`el-input` 或 `el-select`（取决于是否有标准地址字典）
- 优先级：`el-input-number`，范围 1-99
- 状态列：仅展示，不可编辑

**按钮**：取消、确认下发

**下发后**：
- 成功：弹窗关闭，刷新任务列表
- 失败：弹窗内显示失败任务列表（任务号 + 失败原因）

---

## 3. 后端改动

### 3.1 新增 DTO

**文件**: `WMS/WIDESEA_WMSServer/WIDESEA_DTO/Task/DispatchTaskDto.cs`

```csharp
public class DispatchTaskDto
{
    public long TaskId { get; set; }
    public string SourceAddress { get; set; }
    public string TargetAddress { get; set; }
    public int Priority { get; set; }
}
```

### 3.2 新增接口

**Controller**: `WMS/WIDESEA_WMSServer/WIDESEA_WMSServer/Controllers/TaskInfo/TaskController.cs`

```
POST /api/TaskInfo/DispatchTasksToWCS
```

**Service**: `WMS/WIDESEA_WMSServer/WIDESEA_TaskInfoService/TaskService_WCS.cs`

新增方法 `DispatchTasksToWCSAsync(List<DispatchTaskDto> dtos)`

### 3.3 业务逻辑

```
1. 校验选中任务数量 > 0
2. 校验任务状态，仅允许以下状态的任务下发：
   - 入库：InNew（入库新单）
   - 出库：OutNew（出库新单）
   - 移库：RelocationNew（移库新单）
3. 更新任务的地址（SourceAddress、TargetAddress）和优先级（Grade）
4. 调用 WCS 接口：POST http://localhost:9292/api/Task/ReceiveManualTask
5. 汇总每条任务的下发结果（成功/失败及原因）
6. 返回给前端
```

### 3.4 WCS 接口复用

**已有接口**: `POST /api/Task/ReceiveManualTask`（commit b032763）

WMS 调用该接口，将任务数据以 `WMSTaskDTO` 格式发送。

---

## 4. 错误处理

| 场景 | 前端处理 | 后端处理 |
|------|----------|----------|
| 未选中任务 | 按钮置灰；点击提示"请先选择任务" | 返回错误提示 |
| 任务状态不可下发 | 行内状态列标红，地址/优先级置灰不可编辑 | 校验并返回不可下发任务列表 |
| WCS 调用超时 | 该任务标记"下发超时" | 标记任务，下发结果返回前端 |
| WCS 返回失败 | 显示 WCS 错误原因（如"设备忙"） | 透传 WCS 错误信息 |
| 全部成功 | 弹窗关闭，刷新列表 | 返回成功 |

---

## 5. 涉及的代码文件

| 层级 | 文件路径 | 改动类型 |
|------|----------|----------|
| 前端 | `WMS/WIDESEA_WMSClient/src/extension/taskinfo/task.js` | 修改 |
| 前端 | `WMS/WIDESEA_WMSClient/src/extension/taskinfo/extend/dispatchTasksToWCS.vue` | 新增 |
| 前端 | `WMS/WIDESEA_WMSClient/src/api/` | 新增 API 方法 |
| 后端 | `WMS/WIDESEA_WMSServer/WIDESEA_DTO/Task/DispatchTaskDto.cs` | 新增 |
| 后端 | `WMS/WIDESEA_WMSServer/WIDESEA_TaskInfoService/TaskService_WCS.cs` | 修改 |
| 后端 | `WMS/WIDESEA_WMSServer/WIDESEA_WMSServer/Controllers/TaskInfo/TaskController.cs` | 修改 |
| 后端 | `WMS/WIDESEA_WMSServer/WIDESEA_Core/Helper/HTTP/HttpClientHelper.cs` | 复用 |

---

## 6. UI 示意图

```
┌─────────────────────────────────────────────────────────────┐
│  手动下发任务到 WCS                                    [X]  │
├─────────────────────────────────────────────────────────────┤
│  已选任务数: 5 个                                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ 任务号 │ 起点地址     │ 终点地址    │ 优先级 │ 状态  │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │ T001   │ [PLC-A01  ] │ [Rack-05] │ [ 5 ] │ 入库新单│   │
│  │ T002   │ [PLC-A02  ] │ [Rack-06] │ [ 3 ] │ 入库新单│   │
│  └─────────────────────────────────────────────────────┘   │
├─────────────────────────────────────────────────────────────┤
│                                    [取消]  [确认下发]       │
└─────────────────────────────────────────────────────────────┘
```

---

## 7. 验收标准

- [ ] 工具栏添加"手动下发"按钮，未选中任务时按钮可用但点击提示选择
- [ ] 弹窗正确显示所有选中任务
- [ ] 仅入库新单/出库新单/移库新单状态的任务可编辑地址和优先级
- [ ] 确认下发后调用后端接口
- [ ] 成功/失败结果正确反馈给用户
- [ ] 成功后刷新任务列表