# Warehouse Service 模块指引

## 职责与边界

- 负责国内收货仓、地址/能力、往来单位、快递公司、平台公共供应商、国内整柜库存/出入库，以及托盘主数据、库位预占和占用。
- 入库单、测量和入库状态归 `firstleg/`；订单只通过内部接口校验并保存快照。
- 公共资源统一 `tenant_id=0`，不得绑定客户或要求客户筛选。

## 模块入口

| 目标 | 入口 |
|---|---|
| 仓库/地址/能力 | `controller/PlatformWarehouseController.java`、`MerchantWarehouseController.java`、`service/WarehouseApplicationService.java` |
| 往来单位/快递 | `controller/PlatformPartnerController.java`、`PlatformExpressCompanyController.java`、`service/PlatformPartnerQueryService.java`、`PartnerImportService.java` |
| 托盘 | `controller/PlatformPalletController.java`、`service/PalletApplicationService.java` |
| 库位与分配 | `controller/PlatformLocationController.java`、`InternalPalletLocationController.java`、`service/PalletLocationAllocationService.java` |
| 海外仓阶梯费用 | `controller/PlatformOverseasStorageFeeController.java`、`service/OverseasStorageFeeService.java` |
| 平台公共供应商 | `controller/PlatformSupplierController.java`、`service/SupplierService.java`；契约见 `src/main/resources/openapi/supplier-v1.yaml` |
| 国内整柜业务 | `domesticcontainer/controller/PlatformDomesticContainerController.java`、`domesticcontainer/service/DomesticContainerService.java`；契约见 `src/main/resources/openapi/domestic-container-v1.yaml` |
| DTO/持久化 | `dto/`、`entity/`、`mapper/`、`repository/` |
| SQL | `src/main/resources/db/`；存量统一 `../deploy/sql/头程数据库统一增量-MySQL8.sql` |
| 测试/验证 | `src/test/java/com/baiyue/warehouse/`；`mvn -pl warehouse -am test` |

## 修改约束

- 内部仓储接口使用 `X-Internal-Service-Token`，不加入 Gateway 公网路由；资源停用/不存在遵循统一 body code。
- 导入先全量校验再原子写入；调整 DTO、类型或容量规则时同步 Order/Firstleg 客户端和契约测试。

## 三期托盘、库位与 A0 规则

- 托盘是可复用标识和称重主数据，不参与 `AVAILABLE → RESERVED → OCCUPIED → AVAILABLE`；同一托盘主数据可被多条分配复用。
- 普通库位保持单活动预占/占用；A0 是系统创建的共享临时溢出位，可承载多条占用，但每条库位占用仍必须通过 `reservation_id`、`occupancy_id` 独立识别。
- 头程 PDA 结算接口 `/internal/warehouse/v1/pallet-locations/settlements` 是释放、子单转移和全部释放后重新分配的原子边界。不得将其拆成多个可独立提交的远程操作。
- 部分拣货的资源操作必须按 `reservationId` 定位，不能按 `locationId` 定位；A0 多托盘共享时，按 `locationId` 会误释放或合并资源。
- 当父单全部库位释放但子单仍有剩余数量时，在同一仓库事务内优先分配自然 A-Z 顺序的普通空闲库位；普通库位不足时使用 A0，并保持预占、占用和子单归属一致。
- A0 换绑入口包括内部接口和平台接口：平台人员使用 `/api/platform/v1/locations/temporary-occupancies/{occupancyId}/rebind`，需要 `platform:location:edit`。目标必须为同仓 `AVAILABLE` 的普通库位；A0 不允许人工编辑、停用或删除。
- 资源结算、释放、转移和换绑必须保存可重放的幂等记录或具有等价的状态幂等语义，并在测试中覆盖并发状态变更。

## 全量验收导航

本模块承载公共仓与主数据、托盘/库位预占占用、海外仓费用、PDA 拣货和资源结算协作；按本次验收链路读取对应阶段文档，核对实时库存、当前位置、可用量、原子结算和客户隔离。不扩展未确认的完整 WMS，设备真机事项不改变服务端资源契约。