docs: task服务核心业务设计文档
This commit is contained in:
0
doc/remark.txt
Normal file
0
doc/remark.txt
Normal file
308
docs/superpowers/specs/2026-07-14-task-core-design.md
Normal file
308
docs/superpowers/specs/2026-07-14-task-core-design.md
Normal file
@@ -0,0 +1,308 @@
|
||||
# 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 反馈、重复业务回调
|
||||
@@ -0,0 +1,8 @@
|
||||
package cn.code.nl.module.task.enums;
|
||||
|
||||
/**
|
||||
*
|
||||
* @Author: liyongde
|
||||
* @Date: 2026/7/14 16:14
|
||||
*/public enum TransportTaskStatusEnum {
|
||||
}
|
||||
Reference in New Issue
Block a user