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

Overseas Warehouse Service 模块指引

职责与边界

• 负责海外仓库、地址、服务能力、库位、托盘及业务资源锁定/释放。
• 尾程入仓计划通过内部网关请求资源；本模块不读取尾程订单库或头程数据库。

快速索引

功能	入口
平台仓库管理	src/main/java/com/baiyue/warehouse/controller/PlatformWarehouseController.java
商户仓库查询	controller/MerchantWarehouseController.java
平台/商户库位与托盘	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/WarehouseApplicationService.java、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 标识防重；释放/报废操作必须验证当前状态。
• 内部资源接口必须校验服务令牌；普通用户不得直接调用。

数据库表索引与注释约束

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

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

修改与验证

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