zhouz/huachuang
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0eadd801b6d37530fab9586269a19addd810071b
huachuang/docs/superpowers/plans/2026-08-22-acs-empty-box-inbound.md
zhouz 0eadd801b6 docs: 增加ACS空木箱入库实现计划
2026-08-22 11:31:21 +08:00

7.1 KiB
Raw Blame History

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：增加请求对象
@Data
public class AcsEmptyBoxInboundApplyReqVO {
    @NotBlank(message = "设备号不能为空")
    private String deviceCode;
    @NotBlank(message = "木箱类型不能为空")
    private String materialCode;
    @NotNull(message = "任务类型不能为空")
    private Integer taskType;
}
  • 步骤 3：增加响应对象
@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：定义外部服务接口

public interface AcsExternalService {
    /** 申请空木箱入库任务。 */
    AcsEmptyBoxInboundApplyRespVO applyEmptyBoxInbound(AcsEmptyBoxInboundApplyReqVO reqVO);
}
  • 步骤 2：实现业务类型校验和领域服务调用

实现类使用 @Service 和 @Resource 注入 EmptyBoxService。先校验 reqVO.getTaskType() 等于 AcsInboundTaskTypeEnum.EMPTY_BOX.getCode()，不匹配时抛出 ServiceException(500, "当前接口仅支持申请空木箱入库")。

随后逐字段构造 EmptyBoxInboundCreateReq：

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：增加接口方法
@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：执行格式和占位符检查

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 及依赖模块
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：提交实现
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空木箱入库申请接口"

不暂存工作区内与本需求无关的用户改动。