309 lines
11 KiB
Markdown
309 lines
11 KiB
Markdown
# 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 反馈、重复业务回调
|