baiyue-firstleg/warehouse-overseas-service/AGENTS.md

Overseas Warehouse Service 模块指引

职责与边界

• Mapper 只由 BaiyueWarehouseOverseasApplication.java 对 com.baiyue.warehouse 根包按 @Mapper 过滤扫描；新增或移动 Mapper 后从后端根运行 node scripts/mapper-scan-contract.mjs，不得增加子域扫描配置。
• 负责海外库位、托盘及业务资源锁定/释放；只保存国内仓库 ID 引用，不保存仓库、地址或能力主档。
• 国内 warehouse-service 是仓库 ID、类型、状态、地址和能力的唯一权威；本服务通过内部目录校验平台共享 OVERSEAS + ACTIVE + RECEIVING 仓。尾程入仓计划通过内部网关请求资源；本模块不读取尾程订单库或头程数据库。

快速索引

功能	入口
国内仓库只读目录	client/DomesticWarehouseDirectoryClient.java、service/DomesticWarehouseDirectory.java；正结果缓存 30 分钟，空值和不存在不得长缓存
平台/商户库位与托盘	controller/PlatformWarehouseResourceController.java、MerchantWarehouseResourceController.java
内部资源锁定、释放、报废	controller/InternalWarehouseResourceLockController.java
PDA 托盘状态流转与补偿	controller/InternalPdaPalletTransitionController.java、service/WarehousePalletTransitionService.java、mapper/WarehousePalletTransitionMapper.java；内部前缀 /internal/v1/pda-pallet-transitions
托盘解析与业务绑定	controller/InternalWarehousePalletController.java、dto/WarehousePalletResolveResponse.java、entity/WarehousePalletBindingEntity.java
柜级入库计划批量托盘	controller/InternalWarehousePalletBatchController.java、service/WarehousePalletBatchService.java、warehouse-pallet-batch-internal-v1.yaml；以稳定批次键幂等执行 ensure-reserved → confirm，权威托盘码已存在且资源可预留时必须复用，未提供或不存在时才创建；Lastleg 本地计划事务失败时仅补偿仍为 RESERVED 的未确认资源，已 CONFIRMED 批次不得回退，同柜重放不得产生第二批资源
仓储资源服务	service/WarehouseResourceService.java、WarehouseResourceLockService.java
单张托盘标签 PDF	controller/PlatformWarehouseResourceController.java 的 /pallets/{id}/label、service/PalletLabelPrintService.java、client/PrintPdfClient.java；契约 src/main/resources/openapi/pallet-label-v1.yaml。有 FBA 仓码的托盘与国内统一调用 Print /internal/print/v1/pdfs/fba-pallet-labels、FBA_PALLET_A4_LANDSCAPE_V1：297×210 mm，顶部 SCK8 等仓码，完整托盘号作为 Code 128 与底部文字，141 等内部编号原样保留；其他托盘使用 INBOUND_MARK_V1。模板只在 Print 维护；沿用托盘列表权限与海外 Gateway 的 warehouse-admin/** 路由。baiyue.clients.print.url 对应 PRINT_SERVICE_URL，海外 Compose 必须与 BOL 一样显式注入国内 Print 地址，不能依赖海外 Nacos 发现国内服务；Feign 及熔断包装异常统一返回 S0503
内部服务令牌	security/InternalServiceTokenGuard.java
数据库基线与中文注释契约	src/main/resources/db/warehouse.sql、src/test/java/com/baiyue/warehouse/schema/SchemaChineseCommentContractTest.java
测试	src/test/java/com/baiyue/warehouse/

数据与安全规则

• 平台和商户接口必须分别执行访问域与租户范围校验；客户端传入的 tenantId 不能作为唯一授权依据。
• 平台维护的海外库位与实物托盘是公共资源，固定使用 customer_id=0；平台资源 API 不接收目标客户参数。资源锁记录仍使用真实业务客户 ID 隔离，但其托盘、库位查找和状态更新必须落到公共资源作用域。
• 资源锁定以业务幂等键和 reservation 标识防重；释放/报废操作必须验证当前状态。
• 可预留托盘必须满足 IDLE，且其绑定库位为 VIRTUAL + ACTIVE 或真实库位 IDLE；internal resolve 通过 reservable、reservationBlockReason、locationType、locationStatus 明示该事实，不得仅凭托盘状态宣称可预留。
• PDA 托盘状态流转必须在同一事务内锁定托盘及源/目标库位：真实库位与托盘同步 IDLE/OCCUPIED，移库原子释放源库位并占用目标库位；虚拟库位始终保持 ACTIVE。释放后的可复用托盘保留已回到 IDLE 的真实库位关联。
• 内部资源接口必须校验服务令牌；普通用户不得直接调用。
• 本服务不得注册仓库主档创建、编辑、状态或商户仓库查询 Controller；所有资源写入先以相同 warehouseId 校验国内只读目录。

数据库表索引与注释约束

业务域	表名	中文含义
库位	wh_location	海外仓库位资源
托盘	wh_pallet	海外仓实物托盘资源
资源锁	wh_resource_lock	仓储资源锁定记录
托盘绑定	wh_pallet_business_binding	托盘业务绑定关系
托盘操作	wh_pallet_operation	PDA 托盘物理状态流转、幂等与补偿记录
批量预留	wh_pallet_batch	柜级入库计划批量托盘预留与确认记录
批量明细	wh_pallet_batch_item	跨客户批量托盘明细与资源锁关联

• 新增或修改表时，表 COMMENT 和每个普通字段的 COMMENT 必须填写准确的中文业务含义。
• SchemaChineseCommentContractTest 自动扫描全部 wh_ 表；新增字段必须同步更新基线 SQL、统一增量 SQL 和存量备注迁移。

修改与验证

• 字段、注释和索引同步维护基线 SQL 与统一增量 SQL；海外数据库禁止新增 wh_warehouse、wh_warehouse_address、wh_service_capability 或指向它们的外键。
• PDA 托盘流转必须校验内部服务令牌、仓库范围、当前物理状态和幂等键；跨服务业务失败只能通过显式补偿接口恢复，不得由 Lastleg 直接修改 wh_ 资源表。
• 定向验证：mvn -pl warehouse-overseas-service -am test。