docs: 增加ACS空木箱入库设计

docs/superpowers/specs/2026-08-22-acs-empty-box-inbound-design.md

@@ -0,0 +1,87 @@
+# ACS 申请空木箱入库设计
+
+## 1. 目标与范围
+
+在 WMS 模块中新增独立的外部系统服务目录，为 ACS 提供“申请空木箱入库”能力。本次仅实现入库业务类型 `2`，不实现空托盘、退货、成品入库。
+
+入库业务类型统一定义为：
+
+- `1`：申请空托盘入库；
+- `2`：申请空木箱入库；
+- `3`：申请退货入库；
+- `4`：申请成品入库。
+
+## 2. 接口设计
+
+- 请求方式：`POST`
+- 请求路径：`/acs/call/applyEmptyBoxInbound`
+- 调用方：ACS
+- 登录要求：沿用现有 ACS 接口的 `@PermitAll` 方式
+
+请求字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `deviceCode` | String | 是 | 申请入库的设备号，同时作为任务起点 |
+| `materialCode` | String | 是 | 空木箱类型编码 |
+| `taskType` | Integer | 是 | ACS 入库业务类型，本接口只接受 `2` |
+
+响应字段：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `taskId` | Long | 创建的运输任务 ID |
+| `boxNo` | String | 系统生成的虚拟空木箱号 |
+| `targetStructCode` | String | 分配并锁定的目标仓位编码 |
+
+## 3. 代码结构
+
+新增 `service/external/acs` 目录：
+
+- `AcsExternalService`：定义 ACS 外部调用能力；
+- `AcsExternalServiceImpl`：校验 ACS 业务类型并编排现有空木箱服务；
+- 入参和响应仍放在 `controller/acs/vo`，Controller 只负责参数校验和统一响应包装。
+
+现有 `CallTaskController` 新增接口方法并调用 `AcsExternalService`。现有通用 `/acs/call/inbound/apply` 暂不接入业务，避免影响其他尚未实现的入库类型。
+
+## 4. 业务流程
+
+1. Controller 使用注解校验 `deviceCode`、`materialCode`、`taskType` 必填。
+2. `AcsExternalService` 校验 `taskType` 必须为 `2`；其他值返回明确业务异常。
+3. 外部服务构造现有 `EmptyBoxInboundCreateReq`，调用 `EmptyBoxService.createInbound`。
+4. 现有空木箱服务按 `materialCode` 查询木箱类型；不存在则终止。
+5. 使用 `BOX_CODE` 编码规则创建虚拟空木箱号。
+6. 优先在同规格排选择空仓位，否则从全空排选择仓位，并以预占码原子锁定。
+7. 向 `wmw_boxinfo` 插入待入库木箱信息。
+8. 创建空木箱入库运输任务，起点为 `deviceCode`，终点为分配仓位，运输任务内部 `task_type` 继续使用现有固定值 `010501`。
+9. 将仓位预占码替换为任务 ID 和入库锁类型，随后下发任务。
+10. 返回 `taskId`、`boxNo`、`targetStructCode`。
+
+上述步骤沿用 `EmptyBoxService.createInbound` 的事务边界，任一步失败时回滚木箱记录和仓位预占。远程任务创建或下发失败沿用现有可回滚调用语义。
+
+## 5. 任务完成与取消
+
+运输任务继续使用处理器编码 `EMPTYBOXTASK`：
+
+- 完成时由 `EmptyBoxTask.complete` 调用 `EmptyBoxService.completeTask`，解除入库锁、写入仓位库存并将木箱状态更新为已入库；
+- 取消时由 `EmptyBoxTask.cancel` 调用 `EmptyBoxService.cancelTask`，释放仓位锁并删除待入库木箱记录。
+
+本次不新增完成回调逻辑，只复用并验证现有链路。
+
+## 6. 异常规则
+
+- `taskType` 不是 `2`：提示当前接口仅支持申请空木箱入库；
+- 木箱类型不存在：不生成箱号任务和库存；
+- 无可用仓位：不创建木箱和任务；
+- 仓位抢占冲突：继续尝试其他候选仓位，无候选后失败；
+- 木箱插入、任务创建、仓位绑定或任务下发失败：事务回滚并返回业务异常。
+
+由于请求字段中没有 ACS 请求流水号，本次接口不提供调用幂等；ACS 每次成功调用都会申请一个新的空木箱入库任务。
+
+## 7. 验证范围
+
+用户未授权新增测试，因此不新增测试代码。实现后执行：
+
+- WMS 模块及依赖模块 Maven 编译；
+- XML、Java 格式和 `git diff --check` 静态检查；
+- 静态核对 Controller、外部 Service、现有入库任务处理器的调用链。