docs: 增加ACS空木箱入库实现计划
This commit is contained in:
zhouz
159
docs/superpowers/plans/2026-08-22-acs-empty-box-inbound.md
Normal file
159
docs/superpowers/plans/2026-08-22-acs-empty-box-inbound.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# ACS 申请空木箱入库实现计划
|
||||
|
||||
> **面向 AI 代理的工作者：** 必需子技能：使用 superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans 逐任务实现此计划。步骤使用复选框（`- [ ]`）语法来跟踪进度。
|
||||
|
||||
**目标：** 在 WMS 中为 ACS 新增独立外部服务和空木箱入库申请接口，复用现有空木箱任务全链路。
|
||||
|
||||
**架构：** `CallTaskController` 只接收和校验 ACS 协议，委托 `service/external/acs` 下的服务校验业务类型并调用现有 `EmptyBoxService.createInbound`。虚拟箱号、箱型校验、仓位选择与锁定、任务创建下发、完成入账和取消回滚仍由现有空木箱领域服务负责。
|
||||
|
||||
**技术栈：** Java 17、Spring Boot、Jakarta Validation、MyBatis、现有 WMS/Task RPC。
|
||||
|
||||
---
|
||||
|
||||
## 文件结构
|
||||
|
||||
- 创建 `nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/enums/acs/AcsInboundTaskTypeEnum.java`：统一定义 1/2/3/4 四类 ACS 入库业务。
|
||||
- 创建 `nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/vo/AcsEmptyBoxInboundApplyReqVO.java`：ACS 空木箱入库请求。
|
||||
- 创建 `nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/vo/AcsEmptyBoxInboundApplyRespVO.java`：ACS 空木箱入库响应。
|
||||
- 创建 `nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/external/acs/AcsExternalService.java`：ACS 外部服务接口。
|
||||
- 创建 `nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/external/acs/AcsExternalServiceImpl.java`：业务类型校验和现有空木箱服务编排。
|
||||
- 修改 `nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/CallTaskController.java`：暴露 ACS 申请接口并修正旧类型注释。
|
||||
|
||||
### 任务 1：定义 ACS 协议与业务类型
|
||||
|
||||
**文件：**
|
||||
- 创建：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/enums/acs/AcsInboundTaskTypeEnum.java`
|
||||
- 创建：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/vo/AcsEmptyBoxInboundApplyReqVO.java`
|
||||
- 创建：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/vo/AcsEmptyBoxInboundApplyRespVO.java`
|
||||
- 修改：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/vo/AcsApplyInboundReqVO.java`
|
||||
|
||||
- [ ] **步骤 1：增加入库业务类型枚举**
|
||||
|
||||
枚举定义 `EMPTY_PALLET(1)`、`EMPTY_BOX(2)`、`RETURNED_GOODS(3)`、`FINISHED_GOODS(4)`，只保留 `Integer code` 字段，并使用中文注释说明用途。
|
||||
|
||||
- [ ] **步骤 2：增加请求对象**
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class AcsEmptyBoxInboundApplyReqVO {
|
||||
@NotBlank(message = "设备号不能为空")
|
||||
private String deviceCode;
|
||||
@NotBlank(message = "木箱类型不能为空")
|
||||
private String materialCode;
|
||||
@NotNull(message = "任务类型不能为空")
|
||||
private Integer taskType;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **步骤 3：增加响应对象**
|
||||
|
||||
```java
|
||||
@Data
|
||||
@AllArgsConstructor
|
||||
@NoArgsConstructor
|
||||
public class AcsEmptyBoxInboundApplyRespVO {
|
||||
private Long taskId;
|
||||
private String boxNo;
|
||||
private String targetStructCode;
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **步骤 4：修正旧通用请求注释**
|
||||
|
||||
将 `AcsApplyInboundReqVO` 中 6/7/8/9 的说明统一改为 1/2/3/4，但不改变该接口当前的空实现行为。
|
||||
|
||||
### 任务 2：实现 ACS 外部服务
|
||||
|
||||
**文件：**
|
||||
- 创建：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/external/acs/AcsExternalService.java`
|
||||
- 创建：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/external/acs/AcsExternalServiceImpl.java`
|
||||
|
||||
- [ ] **步骤 1：定义外部服务接口**
|
||||
|
||||
```java
|
||||
public interface AcsExternalService {
|
||||
/** 申请空木箱入库任务。 */
|
||||
AcsEmptyBoxInboundApplyRespVO applyEmptyBoxInbound(AcsEmptyBoxInboundApplyReqVO reqVO);
|
||||
}
|
||||
```
|
||||
|
||||
- [ ] **步骤 2：实现业务类型校验和领域服务调用**
|
||||
|
||||
实现类使用 `@Service` 和 `@Resource` 注入 `EmptyBoxService`。先校验 `reqVO.getTaskType()` 等于 `AcsInboundTaskTypeEnum.EMPTY_BOX.getCode()`，不匹配时抛出 `ServiceException(500, "当前接口仅支持申请空木箱入库")`。
|
||||
|
||||
随后逐字段构造 `EmptyBoxInboundCreateReq`：
|
||||
|
||||
```java
|
||||
EmptyBoxInboundCreateReq request = new EmptyBoxInboundCreateReq();
|
||||
request.setDeviceCode(reqVO.getDeviceCode());
|
||||
request.setMaterialCode(reqVO.getMaterialCode());
|
||||
EmptyBoxInboundCreateResp result = emptyBoxService.createInbound(request);
|
||||
return new AcsEmptyBoxInboundApplyRespVO(
|
||||
result.getTaskId(), result.getBoxNo(), result.getTargetStructCode());
|
||||
```
|
||||
|
||||
不复制 `EmptyBoxServiceImpl` 内部的箱型查询、编码生成、仓位锁定和任务逻辑。
|
||||
|
||||
### 任务 3：暴露 ACS 接口
|
||||
|
||||
**文件：**
|
||||
- 修改：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs/CallTaskController.java`
|
||||
|
||||
- [ ] **步骤 1：注入 ACS 外部服务**
|
||||
|
||||
使用 `@Resource private AcsExternalService acsExternalService;`，保留现有 `ShippingAreaService`。
|
||||
|
||||
- [ ] **步骤 2：增加接口方法**
|
||||
|
||||
```java
|
||||
@PostMapping("/applyEmptyBoxInbound")
|
||||
@Operation(summary = "申请空木箱入库")
|
||||
@PermitAll
|
||||
public CommonResult<AcsEmptyBoxInboundApplyRespVO> applyEmptyBoxInbound(
|
||||
@Valid @RequestBody AcsEmptyBoxInboundApplyReqVO reqVO) {
|
||||
return success(acsExternalService.applyEmptyBoxInbound(reqVO));
|
||||
}
|
||||
```
|
||||
|
||||
最终地址为 `POST /acs/call/applyEmptyBoxInbound`。不修改现有 `/inbound/apply` 的空实现行为。
|
||||
|
||||
### 任务 4：验证完整链路
|
||||
|
||||
**文件：**
|
||||
- 核对：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/emptybox/EmptyBoxServiceImpl.java`
|
||||
- 核对：`nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/task/EmptyBoxTask.java`
|
||||
|
||||
- [ ] **步骤 1：执行格式和占位符检查**
|
||||
|
||||
```bash
|
||||
rg -n "FIXME|待补充" \
|
||||
nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/external/acs \
|
||||
nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs
|
||||
git diff --check
|
||||
```
|
||||
|
||||
预期：新增代码无占位符，`git diff --check` 无输出。
|
||||
|
||||
- [ ] **步骤 2：编译 WMS 及依赖模块**
|
||||
|
||||
```bash
|
||||
mvn -pl nl-module-wms/nl-module-wms-server -am -DskipTests compile
|
||||
```
|
||||
|
||||
预期：Reactor Summary 中所有模块为 `SUCCESS`，最终输出 `BUILD SUCCESS`。
|
||||
|
||||
- [ ] **步骤 3：静态核对任务完成和取消链路**
|
||||
|
||||
确认新接口调用 `EmptyBoxService.createInbound`；运输任务仍使用 `HANDLE_CODE = "EMPTYBOXTASK"`；`EmptyBoxTask.complete` 调用 `completeTask` 更新仓位库存和木箱状态；`EmptyBoxTask.cancel` 调用 `cancelTask` 释放仓位并删除待入库木箱。
|
||||
|
||||
- [ ] **步骤 4：提交实现**
|
||||
|
||||
```bash
|
||||
git add \
|
||||
nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/enums/acs \
|
||||
nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/controller/acs \
|
||||
nl-module-wms/nl-module-wms-server/src/main/java/cn/code/nl/module/wms/service/external/acs
|
||||
git commit -m "feat: 增加ACS空木箱入库申请接口"
|
||||
```
|
||||
|
||||
不暂存工作区内与本需求无关的用户改动。
|
||||
Reference in New Issue
Block a user