11 KiB
11 KiB
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 状态枚举
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 模块）：
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; // 扩展参数
}
创建逻辑：
- 参数校验
- 幂等检查：同 bizType + bizId 下是否有未完结任务 (status < 067)，有则返回已有 taskId
- 生成 taskId / taskCode
- 参数完整 → status=040，否则 status=010
- 保存并返回 taskId
4.2 ACS → Task：状态反馈
POST /api/task/transport/acs-feedback
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 调用对应服务。
// 请求
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)
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
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 同步路由）
// 根据 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 反馈、重复业务回调