# 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` |
| 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 客户端和契约测试。

## 分期导航

- 一期：公共仓与主数据；先读 `../../docs/一期/README.md`。
- 二期：托盘/库位预占占用和海外仓费用；先读 `../../docs/二期/README.md` 与主流程。
- 三期：NO-GO；待确认后再扩展出仓资源。