# Task 服务核心业务设计文档

> 日期: 2026-07-14
> 分支: feature/20260713/task-module
> 参考: doc/task-service-technical-development.md

## 1. 概述

Task 服务是搬运任务生命周期中台，负责接收 LMS/WMS 创建的任务、接收 ACS 状态反馈、维护任务状态机、以及通过 HTTP/MQ 将状态变更通知回 LMS/WMS。

### 1.1 本期范围

| 本期做 | 本期不做 |
|--------|----------|
| LMS/WMS 创建任务 (RPC) | 定时器自动下发 ACS |
| ACS 反馈：执行中、取货完成、完成、取消 | ACS 下发接口调用 |
| 取货完成同步 HTTP 回调 LMS/WMS | 下发中超时补偿 |
| 完成/取消 MQ 异步通知 LMS/WMS | 回调超时重试补偿 |
| 业务回调结果接收 + 状态更新 | AcsTaskDto 转换器 |
| 幂等控制（创建、反馈、回调） | 人工完成/取消 |
| 管理后台 CRUD（已有） | 任务过程日志表 |

## 2. 整体交互流程

```
LMS/WMS                          Task 服务                          ACS
   │                                │                                │
   │── POST /rpc-api/task/transport/create ──→│                      │
   │                                │ 保存任务(status=040)           │
   │←── 返回 taskId ───────────────│                                │
   │                                │                                │
   │                                │   (后续: 定时器下发ACS)       │
   │                                │                                │
   │                                │←── ACS 反馈 执行中(60) ───────│
   │                                │ 更新状态, 直接返回成功         │
   │                                │                                │
   │                                │←── ACS 反馈 取货完成(61) ─────│
   │                                │ 更新状态                       │
   │←── POST /rpc-api/{service}/transport-task/status-callback ──│   │
   │── 同步执行业务处理 ──────────→│                                │
   │←── 返回业务结果 ─────────────│                                │
   │                                │──── 返回成功给 ACS ───────────→│
   │                                │       (AGV 可继续)              │
   │                                │                                │
   │                                │←── ACS 反馈 完成 ─────────────│
   │                                │ status=067, callback=PENDING    │
   │←── MQ: TASK_EVENT:LMS ───────│  (异步)                        │
   │  业务处理 → 回调 Task ───────→│ status=070, callback=SUCCESS    │
   │                                │                                │
   │                                │←── ACS 反馈 取消 ─────────────│
   │                                │ status=069, callback=PENDING    │
   │←── MQ: TASK_EVENT:LMS ───────│  (异步)                        │
   │  业务处理 → 回调 Task ───────→│ status=080, callback=SUCCESS    │
```

### 2.1 回调策略总结

| ACS 状态 | Task 动作 | 通知方式 | 说明 |
|----------|----------|----------|------|
| 执行中(60) | 更新 status=060 | 无 | 直接改状态 |
| 取货完成(61) | 更新 status=061 | HTTP 同步 | 调 LMS/WMS，等业务完成再回 ACS |
| 完成 | status=067, callback=PENDING | MQ 异步 | 通知后不等待，LMS/WMS 处理完回调 |
| 取消 | status=069, callback=PENDING | MQ 异步 | 同上 |

## 3. 状态机

### 3.1 状态枚举

```java
CREATED(10, "生成")
READY(40, "待下发")
ISSUING(45, "下发中")
ISSUED(50, "已下发")
EXECUTING(60, "执行中")
PICKED(61, "已取货搬运中")
FINISHED_CALLBACK_PENDING(67, "外部完成待业务处理")
CANCEL_EXTERNAL_PENDING(68, "外部取消中")
CANCEL_CALLBACK_PENDING(69, "外部取消待业务处理")
FINISHED(70, "完成")
CANCELLED(80, "取消")
FAILED(90, "失败")
```

### 3.2 本期状态流转

```
010(生成) → 040(待下发)
040(待下发) → 060(执行中) → 061(取货完成) → 067(外部完成待业务处理) → 070(完成)
                                            → 069(外部取消待业务处理) → 080(取消)
```

### 3.3 状态前置校验

| 目标状态 | 允许的前置状态 |
|----------|---------------|
| EXECUTING(60) | 040, 050, 060 |
| PICKED(61) | 060, 061 |
| FINISHED_CALLBACK_PENDING(67) | 050, 060, 061, 067 |
| CANCEL_CALLBACK_PENDING(69) | 040, 050, 060, 061, 069 |

## 4. 接口设计

### 4.1 LMS/WMS → Task：创建任务

```
POST /rpc-api/task/transport/create
```

请求 DTO（位于 `nl-module-task-api` 模块）：

```java
public class TransportTaskCreateReqDTO {
    @NotEmpty String taskName;
    @NotEmpty String ownerService;    // LMS / WMS，路由键
    @NotEmpty String bizType;         // 业务类型
    @NotEmpty String bizId;           // 业务侧单据ID（幂等）
    @NotEmpty String handleCode;      // LMS/WMS内部handler编码
    @NotEmpty String acsTaskType;     // ACS任务类型
    @NotEmpty String agvSystemType;
    String pointCode1, pointCode2, pointCode3, pointCode4;
    String vehicleCode, vehicleCode2;
    String priority;
    String productArea;
    String isAutoIssue;               // 是否自动下发
    Map<String, Object> requestParam;  // 扩展参数
}
```

创建逻辑：
1. 参数校验
2. 幂等检查：同 bizType + bizId 下是否有未完结任务 (status < 067)，有则返回已有 taskId
3. 生成 taskId / taskCode
4. 参数完整 → status=040，否则 status=010
5. 保存并返回 taskId

### 4.2 ACS → Task：状态反馈

```
POST /api/task/transport/acs-feedback
```

```java
public class AcsFeedbackReqDTO {
    @NotNull Long taskId;
    @NotEmpty String status;          // EXECUTING / PICKED / FINISHED / CANCELLED
    String eventId;                   // 幂等键
    Map<String, Object> payload;      // 保存到 resultParam
}
```

### 4.3 Task → LMS/WMS：同步回调（取货完成）

```
POST /rpc-api/transport-task/status-callback
```

LMS/WMS 需实现此端点。路由方式：根据 `ownerService` 通过 Nacos 服务发现 + HTTP 调用对应服务。

```java
// 请求
public class TaskStatusCallbackReqDTO {
    Long taskId;
    String taskCode;
    String status;                    // PICKED(61)
    String ownerService;
    String bizType;
    String bizId;
    String handleCode;                // LMS/WMS内部通过此字段路由到具体handler
    Map<String, Object> payload;
}

// 响应
public class TaskStatusCallbackRespDTO {
    Boolean success;
    String message;
}
```

### 4.4 Task → LMS/WMS：MQ 异步通知（完成/取消）

```
Topic: TASK_EVENT_TOPIC
Tag:   LMS 或 WMS (即 ownerService)
```

```java
public class TaskEventMessage {
    String eventId;
    String eventType;                 // TASK_FINISHED / TASK_CANCELLED
    Long taskId;
    String taskCode;
    String ownerService;
    String bizType;
    String bizId;
    String handleCode;
    Map<String, Object> payload;
}
```

### 4.5 LMS/WMS → Task：业务处理结果回调

```
POST /rpc-api/task/transport/callback-result
```

```java
public class TaskCallbackResultReqDTO {
    @NotNull Long taskId;
    @NotEmpty String eventId;
    @NotEmpty String result;          // SUCCESS / FAILED
    String message;
}
```

回调后状态更新：

| 场景 | taskStatus | callbackStatus |
|------|-----------|----------------|
| 完成业务成功 | 070 | SUCCESS |
| 完成业务失败 | 067 | FAILED |
| 取消业务成功 | 080 | SUCCESS |
| 取消业务失败 | 069 | FAILED |

## 5. 服务层设计

### 5.1 模块结构

```
nl-module-task-server/
  controller/
    TransportTaskController          ← 已有，管理后台 CRUD
    AcsFeedbackController            ← 新增：接收 ACS 状态反馈
  api/
    TransportTaskApiImpl             ← 新增：实现 rpc-api 创建任务接口
  service/
    TransportTaskService             ← 已有，扩展创建方法
    TransportTaskFeedbackService     ← 新增：处理 ACS 状态反馈
    TransportTaskCallbackService     ← 新增：处理 LMS/WMS 业务回调结果
  mq/
    TaskEventProducer                ← 新增：发送完成/取消 MQ
  client/
    TransportTaskStatusClient        ← 新增：同步 HTTP 调 LMS/WMS

nl-module-task-api/
  dto/
    TransportTaskCreateReqDTO        ← 新增
    AcsFeedbackReqDTO                ← 新增
    TaskStatusCallbackReqDTO         ← 新增（LMS/WMS 依赖此 DTO 实现端点）
    TaskStatusCallbackRespDTO        ← 新增
    TaskCallbackResultReqDTO         ← 新增
    TaskEventMessage                 ← 新增
  enums/
    TransportTaskStatusEnum          ← 已有（需对齐状态码）
    CallbackStatusEnum               ← 新增
    TaskEventTypeEnum                ← 新增
```

### 5.2 TransportTaskFeedbackService（核心）

```
receiveAcsFeedback(AcsFeedbackReqDTO req):
  1. 查询任务，校验存在
  2. eventId 幂等判断
  3. 前置状态校验（不合法则记日志并返回成功）
  4. 保存 resultParam
  5. 按 status 路由：
     EXECUTING:
       → 更新 taskStatus=060
     PICKED:
       → 更新 taskStatus=061
       → 同步 HTTP 调 LMS/WMS status-callback
       → 回调失败：记 callbackStatus=FAILED，仍返回成功给 ACS
     FINISHED:
       → 更新 taskStatus=067, callbackStatus=PENDING
       → 发送 MQ (TASK_FINISHED)
       → MQ 失败：记 callbackStatus=FAILED, callbackErrorMsg
     CANCELLED:
       → 更新 taskStatus=069, callbackStatus=PENDING
       → 发送 MQ (TASK_CANCELLED)
       → MQ 失败：记 callbackStatus=FAILED, callbackErrorMsg
```

### 5.3 TransportTaskStatusClient（HTTP 同步路由）

```java
// 根据 ownerService → Nacos 服务名 → 构造 URL 调用
// LMS/WMS 通过 handleCode 路由到内部 handler
```

## 6. 错误处理与幂等

| 场景 | 处理 |
|------|------|
| 创建时参数校验失败 | 返回参数错误码 |
| 创建时同名未完结任务已存在 | 返回已有 taskId |
| ACS 反馈 taskId 不存在 | 记录日志，返回成功（防 ACS 重试报错） |
| 反馈状态前置校验不通过 | 记录日志，返回成功 |
| 取货完成同步回调 LMS/WMS 失败 | 记 callbackStatus=FAILED，仍返回 ACS 成功（不阻塞 AGV） |
| MQ 发送失败 | 记 callbackStatus=FAILED + callbackErrorMsg |
| 业务回调结果已终态(070/080) | 直接返回成功 |
| 重复 eventId 反馈 | 直接返回成功 |
| 重复创建（同 bizType+bizId） | 返回已有 taskId |

## 7. 测试策略

- **单元测试**：TransportTaskFeedbackService 各状态分支、状态机约束
- **集成测试**：创建 → 执行中 → 取货完成 → 完成 → 业务回调 → 终态 完整链路
- **幂等测试**：重复创建、重复 ACS 反馈、重复业务回调