baiyue-firstleg/warehouse/AGENTS.md

Warehouse Service 模块指引

数据库访问与中文注释约束

• 强制遵守根 ../AGENTS.md 的“数据库访问与中文代码注释”全部规则：正常业务访问统一为 Controller → Service → Repository → Mapper，不得省略 Repository 或跨层直调；生产 SQL 由 Mapper 执行，Repository 不得直接使用 JdbcTemplate 或原生 JDBC。非 HTTP 入口从 Service 进入；无数据库模块不引入数据库访问。
• 每个手写方法及构造器须有简短中文说明；核心业务规则、复杂 SQL、事务、锁、幂等、并发及失败处理须补充适量中文注释，重点说明原因和边界。新增、修改方法立即执行，触及的存量代码同步整改。

职责与边界

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

模块入口

目标	入口
仓库/地址/能力	controller/PlatformWarehouseController.java、MerchantWarehouseController.java、service/WarehouseApplicationService.java；国内 PDA 仓库目录由 InternalWarehouseController.java 的 /internal/warehouses/domestic 提供给 Firstleg
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 引用
公共海外收货仓平台候选	controller/PlatformOverseasReceivingOptionsController.java；统一 Gateway 的 /api/platform/v1/warehouse-admin/overseas-receiving-options，权限 platform:overseas-warehouse:warehouse:list，平台主体且公共作用域，固定 OVERSEAS + ACTIVE + RECEIVING；分页上限200，契约见 src/main/resources/openapi/warehouse-v1.yaml
海外仓合作仓类型	沿用仓库/地址/能力入口；同步核对仓库 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；TRUCKING 必须设置互斥 truckingScope=DOMESTIC（国内拖车）/OVERSEAS（海外车队），其他类别为空；分页/导出支持类型筛选，导入模板版本3必填类型；契约见 src/main/resources/openapi/supplier-v1.yaml controller/InternalSupplierController.java 的 /{supplierId}/trucking-contact 为 Firstleg 提供平台 TRUCKING + OVERSEAS 海外车队邮箱资料，取消旧请求允许读取已停用车队邮箱，仍验证内部令牌及平台归属。
国内整柜业务	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，设备真机事项不改变服务端资源契约。