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
仓储资源服务	service/WarehouseResourceService.java、WarehouseResourceLockService.java
内部服务令牌	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 标识防重；释放/报废操作必须验证当前状态。
• 内部资源接口必须校验服务令牌；普通用户不得直接调用。
• 本服务不得注册仓库主档创建、编辑、状态或商户仓库查询 Controller；所有资源写入先以相同 warehouseId 校验国内只读目录。

数据库表索引与注释约束

业务域	表名	中文含义
库位	wh_location	海外仓库位资源
托盘	wh_pallet	海外仓实物托盘资源
资源锁	wh_resource_lock	仓储资源锁定记录
托盘绑定	wh_pallet_business_binding	托盘业务绑定关系
托盘操作	wh_pallet_operation	PDA 托盘物理状态流转、幂等与补偿记录

• 新增或修改表时，表 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。