diff --git a/docs/superpowers/plans/2026-08-22-acs-empty-box-inbound.md b/docs/superpowers/plans/2026-08-22-acs-empty-box-inbound.md new file mode 100644 index 00000000..46200bba --- /dev/null +++ b/docs/superpowers/plans/2026-08-22-acs-empty-box-inbound.md @@ -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 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空木箱入库申请接口" +``` + +不暂存工作区内与本需求无关的用户改动。