baiyue-firstleg/warehouse/AGENTS.md

Warehouse Service 模块指引

职责边界

• 负责国内收货仓、仓库地址、服务能力、启停校验、往来单位主数据，以及二期托盘、库位、预占和占用资源。
• 往来单位保存在 baiyue_warehouse.wh_partner，不是独立服务；订单只通过内部接口校验并保存快照。
• 入库流程状态和测量数据属于 firstleg/；本模块只维护仓储资源及其容量、预占和占用状态，不复制入库单领域模型。

功能快速索引

功能	入口
商户可用仓库列表与详情	controller/MerchantWarehouseController.java
平台仓库增改查与启停	controller/PlatformWarehouseController.java
内部仓库有效性校验	controller/InternalWarehouseController.java
商户往来单位候选与详情	controller/MerchantPartnerController.java
内部往来单位有效性校验	controller/InternalPartnerController.java
平台往来单位增改查、启停与 XLSX 导入	controller/PlatformPartnerController.java、service/PlatformPartnerQueryService.java、PartnerImportService.java；模板 /import-template，导入 /import
平台快递公司增改查、启停与 XLSX 导入	controller/PlatformExpressCompanyController.java、service/ExpressCompanyQueryService.java、ExpressCompanyImportService.java；模板 /import-template，导入 /import
平台托盘增改查	controller/PlatformPalletController.java → service/PalletApplicationService.java → repository/PalletRepository.java；体积分托盘规则在 service/PalletVolumeSplitter.java
平台库位增改查、可用库位与容量	controller/PlatformLocationController.java → service/LocationApplicationService.java、LocationResourceService.java → repository/LocationRepository.java
海外仓阶梯费用 CRUD	controller/PlatformOverseasStorageFeeController.java → service/OverseasStorageFeeService.java → repository/OverseasStorageFeeRepository.java；客户主记录与阶梯明细分别落 wh_overseas_storage_fee_rule、wh_overseas_storage_fee_tier
Firstleg 托盘库位预占、确认和释放	controller/InternalPalletLocationController.java（/reservations、/confirm、/release）→ service/PalletLocationAllocationService.java；只允许内部令牌调用
服务与数据库结构状态	controller/WarehouseHealthController.java、service/WarehouseSchemaReadinessService.java
数据访问异常映射	controller/WarehouseDataAccessExceptionHandler.java；数据库不可用或结构漂移统一返回 S0503/503
仓库业务编排	service/WarehouseApplicationService.java
往来单位查询与停用过滤	service/PartnerQueryService.java
请求与详情 DTO	dto/WarehouseRequests.java、WarehouseDetailResponse.java、MasterDataQueries.java
仓库、地址、能力、往来单位与快递公司持久化	entity/、mapper/、repository/；往来单位多类型关联为 PartnerTypeEntity.java 与 wh_partner_type
表结构、伙伴、快递公司与种子数据	src/main/resources/db/warehouse.sql、warehouse-partner.sql、warehouse-express-company.sql、phase1-warehouse-schema-migration.sql、warehouse-seed.sql
二期托盘库位表与迁移	src/main/resources/db/phase2-pallet-location-schema.sql、phase2-pallet-location-schema-migration.sql、phase2-location-overflow-migration.sql；统一部署入口 ../deploy/sql/头程数据库统一增量-MySQL8.sql，历史日期脚本仅作追溯
测试	src/test/java/com/baiyue/warehouse/

修改与验证

• 往来单位、仓库、快递公司、托盘、库位等均是平台公共主数据，统一归属平台技术作用域 tenant_id=0，不得绑定任一客户；客户只读取平台共享往来单位。平台启停必须检查业务约束，不能只改状态字段。列表接口默认查询全部公共资源，不得要求 Admin 先选择客户，也不得让客户筛选控制仓库、往来单位、快递、托盘或库位候选范围。历史接口或字段仍出现 tenantId 时只保留兼容，只允许传平台公共作用域 0，不得传客户 ID 作为资源归属。接口同时校验平台访问域和按钮权限：列表/详情使用 platform:warehouse:list，新增使用 platform:warehouse:create，编辑使用 platform:warehouse:edit，启停使用 platform:warehouse:status；OpenAPI 的 403 响应说明必须与权限码同步。
• 往来单位与仓库查询供 Order 使用，DTO 或有效性语义变化需同步检查 order/client/ 和订单快照逻辑。
• 往来单位类型以 types 多值集合和 wh_partner_type 为准，允许同一单位同时作为客户、供应商等；wh_partner.partner_type 与 DTO 的 partnerType 仅保留旧数据兼容。写入时 Entity、Mapper、Repository、平台保存/导入和 Order 客户端必须一起核对。
• 往来单位与快递公司导入只接收标准 XLSX 模板，文件上限 5MB、最多 1000 行；先完成整表头、字段、文件内重复和数据库重复校验，再原子写入，任一行失败整批不落库。权限分别是 platform:counterparty:import 与 platform:express:import。
• 模板与导入 DTO 在 dto/MasterDataQueries.java，Apache POI 依赖在 pom.xml；调整模板版本、列顺序或枚举时同步修改生成、解析、错误行号和两组 ImportService 测试。
• Warehouse 内部仓库/往来单位接口使用 X-Internal-Service-Token：公共仓库和平台共享往来单位均按 tenant_id=0 校验；往来单位不存在使用 HTTP 200 + body code A0404，资源已停用使用 HTTP 200 + A0409。WarehouseDataAccessExceptionHandler 捕获的数据库或结构故障保留真实 HTTP 503 + S0503。内部路径不加入 Gateway 公网路由。
• 托盘和库位平台接口必须执行平台访问域、平台技术作用域 tenant_id=0 和对应权限校验，不得要求目标客户；预占、确认、释放只通过 InternalPalletLocationController 提供给 Firstleg，不加入 Gateway 公网路由。Firstleg 的入库单仍按客户 tenant_id>0 隔离，调用公共仓储资源时必须把业务客户归属与公共资源归属分开校验。
• 公共资源与客户数据必须分开：公共仓库、往来单位、快递公司、托盘、库位使用 tenant_id=0；客户订单、文件和费用使用所属客户 tenant_id>0。10001 是客户 ID，不得再用于平台公共资源归属。
• 库位容量、共享溢出、预占和占用必须在数据库事务及条件更新中保持一致；修改分配算法时同步覆盖并发冲突、容量不足、重复确认、释放和共享溢出测试。
• Firstleg 只保存托盘/库位逻辑引用和入库快照。内部 DTO、预占状态或容量口径变化时同步检查 firstleg/client/WarehousePalletLocationClient.java、MeasurementLocationOccupationService.java 和双方测试。
• 数据表、Entity、Mapper、Repository 与种子数据必须同步；历史订单不随主数据更新。
• 既有数据库发布必须按 warehouse.sql、warehouse-partner.sql、warehouse-express-company.sql、phase1-warehouse-schema-migration.sql、warehouse-seed.sql 的顺序执行；服务不在启动时自动跑 SQL。
• /api/platform/v1/warehouses/status 必须执行真实字段探针；缺表或缺列时返回 DEGRADED/503，不得只根据进程存活伪报 UP。
• Warehouse 的数据库访问异常和 readiness/结构状态探针都保留真实 HTTP 503；其他由公共异常处理器捕获的业务失败才使用 HTTP 200 + body code。
• 从父目录运行 mvn -pl warehouse -am test，再运行 scripts/order-warehouse-real-api-regression.ps1。
• 二期直接验证至少运行 PalletApplicationServiceTest、LocationApplicationServiceTest、LocationResourceServiceTest、PalletLocationAllocationServiceTest 及两个平台 Controller 契约测试；存量数据库迁移后确认统一脚本末尾 Warehouse 核验全部为 PASS。

分期快速索引

• 一期：PlatformWarehouseController、InternalWarehouseController、Partner/Express Controller 提供平台公共仓与主数据；先读 ../../docs/一期/README.md、../../docs/一期/一期头程订单闭环设计.md。资源归属固定 tenant_id=0，不得绑定客户或由客户筛选候选范围。
• 二期：PlatformPalletController、PlatformLocationController、InternalPalletLocationController 支撑托盘/库位预占、确认、释放；先读 ../../docs/二期/README.md、主流程文档和 8 月 4 日迁移说明。入库状态仍归 firstleg/，Warehouse 只维护资源容量与占用。
• 三期：当前 NO-GO；暂不实现分柜、装柜、出仓库存扣减或 PDA 专用资源。解除 ../../docs/三期/三期需求确认表.md 阻断项后，再锁定资源状态机与 Firstleg 内部 DTO。