baiyue-firstleg/warehouse/AGENTS.md

# Warehouse Service 模块指引

## 职责与边界

- Mapper 只由 `BaiyueWarehouseApplication.java` 对 `com.baiyue.warehouse` 根包按 `@Mapper` 过滤扫描；新增或移动 Mapper 后从后端根运行 `node scripts/mapper-scan-contract.mjs`，不得增加子域扫描配置。
- 负责国内收货仓及现有平台仓库主数据、地址/能力、往来单位、快递公司、平台公共供应商、国内整柜库存/出入库，以及托盘主数据、库位预占和占用。四期只在本模块扩展“海外仓合作仓”仓库类型及其公共主数据契约。
- 入库单、测量和入库状态归 `firstleg/`；订单只通过内部接口校验并保存快照。
- 四期海外接柜、卸货、海外入库、换标、产品、箱号、库存和库内作业属于海外区域服务，不得落入本国内 Warehouse Service；范围先读 `../../docs/四期/README.md`。
- 公共资源统一 `tenant_id=0`，不得绑定客户或要求客户筛选。

## 模块入口

| 目标 | 入口 |
|---|---|
| 仓库/地址/能力 | `controller/PlatformWarehouseController.java`、`MerchantWarehouseController.java`、`service/WarehouseApplicationService.java` |
| FBA 目的仓公共主数据与 Admin 候选 | 权威表 `wh_warehouse` 的 `tenant_id=0 + warehouse_type=FBA` 记录；Admin 直接调用 `GET /api/platform/v1/warehouse-admin?warehouseType=FBA&status=ACTIVE&page=1&size=200`，权限 `platform:warehouse:list`，DTO `WarehouseSummaryResponse` 的 `id/warehouseCode/warehouseName/status/countryCode/primaryAddress.stateProvince` 分别作为 ID/编码/名称/状态/国家/区域 |
| FBA 目的仓内部校验 | `InternalWarehouseController.java` 的 `GET /internal/warehouses/0/{warehouseId}/active`，使用内部服务令牌返回 `WarehouseDetailResponse`；调用方仍须校验 `warehouseType=FBA` 及 ID/编码/名称一致，不得把 `OVERSEAS` 实际收货仓或 `DOMESTIC` 中转仓当作 FBA 目的仓 |
| 公共海外收货仓内部目录 | `controller/InternalWarehouseController.java` 的 `/internal/warehouses/shared-overseas`、`/shared-overseas/{warehouseId}`，响应 `dto/SharedOverseasWarehouseResponse.java`；只返回平台公共 `OVERSEAS + ACTIVE + RECEIVING` 仓，供海外资源服务按 warehouseId 引用 |
| 四期海外仓合作仓类型 | 沿用仓库/地址/能力入口；同步核对仓库 DTO、OpenAPI、`src/main/resources/db/`、统一 SQL 及 Admin `modules/warehouses/`，并与普通海外仓语义明确区分 |
| 往来单位/快递 | `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` |
| 测试/验证 | Java 测试 `src/test/java/com/baiyue/warehouse/`，执行 `mvn -pl warehouse -am test`；公共 FBA 仓 CSV 与 SQL 离线合同 `scripts/warehouse-public-master-data-contract.test.mjs`，从后端根执行 `node --test warehouse/scripts/warehouse-public-master-data-contract.test.mjs`；局部说明见 `scripts/README.md` |

## 修改约束

- 内部仓储接口使用 `X-Internal-Service-Token`，不加入 Gateway 公网路由；资源停用/不存在遵循统一 body code。
- 仓库 ID、类型、状态、地址和服务能力在本模块唯一维护；海外服务不得复制仓库主档。共享海外收货仓目录只接受内部服务令牌，列表和单项必须使用相同的 `tenant_id=0 + OVERSEAS + ACTIVE + RECEIVING` 判定。
- 导入先全量校验再原子写入；调整 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，设备真机事项不改变服务端资源契约。