From 1e89f95e662d0253533bffd1caa81351188997f0 Mon Sep 17 00:00:00 2001 From: liyongde <1419499670@qq.com> Date: Tue, 14 Jul 2026 16:50:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20task=E6=9C=8D=E5=8A=A1=E6=A0=B8?= =?UTF-8?q?=E5=BF=83=E4=B8=9A=E5=8A=A1=E8=AE=BE=E8=AE=A1=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/remark.txt | 0 .../specs/2026-07-14-task-core-design.md | 308 ++++++++++++++++++ .../task/enums/TransportTaskStatusEnum.java | 8 + 3 files changed, 316 insertions(+) create mode 100644 doc/remark.txt create mode 100644 docs/superpowers/specs/2026-07-14-task-core-design.md create mode 100644 nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/enums/TransportTaskStatusEnum.java diff --git a/doc/remark.txt b/doc/remark.txt new file mode 100644 index 00000000..e69de29b diff --git a/docs/superpowers/specs/2026-07-14-task-core-design.md b/docs/superpowers/specs/2026-07-14-task-core-design.md new file mode 100644 index 00000000..ae74d780 --- /dev/null +++ b/docs/superpowers/specs/2026-07-14-task-core-design.md @@ -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 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 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 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 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 反馈、重复业务回调 diff --git a/nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/enums/TransportTaskStatusEnum.java b/nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/enums/TransportTaskStatusEnum.java new file mode 100644 index 00000000..39bef81f --- /dev/null +++ b/nl-module-task/nl-module-task-api/src/main/java/cn/code/nl/module/task/enums/TransportTaskStatusEnum.java @@ -0,0 +1,8 @@ +package cn.code.nl.module.task.enums; + +/** + * + * @Author: liyongde + * @Date: 2026/7/14 16:14 + */public enum TransportTaskStatusEnum { +}