优化

warehouse-overseas-service/AGENTS.md

@@ -2,20 +2,19 @@
 
 ## 职责与边界
 
-- 负责海外仓库、地址、服务能力、库位、托盘及业务资源锁定/释放。
-- 尾程入仓计划通过内部网关请求资源；本模块不读取尾程订单库或头程数据库。
+- 负责海外库位、托盘及业务资源锁定/释放；只保存国内仓库 ID 引用，不保存仓库、地址或能力主档。
+- 国内 `warehouse-service` 是仓库 ID、类型、状态、地址和能力的唯一权威；本服务通过内部目录校验平台共享 `OVERSEAS + ACTIVE + RECEIVING` 仓。尾程入仓计划通过内部网关请求资源；本模块不读取尾程订单库或头程数据库。
 
 ## 快速索引
 
 | 功能 | 入口 |
 |---|---|
-| 平台仓库管理 | `src/main/java/com/baiyue/warehouse/controller/PlatformWarehouseController.java` |
-| 商户仓库查询 | `controller/MerchantWarehouseController.java` |
+| 国内仓库只读目录 | `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/WarehouseApplicationService.java`、`WarehouseResourceService.java`、`WarehouseResourceLockService.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/` |
@@ -26,6 +25,7 @@
 - 平台维护的海外库位与实物托盘是公共资源，固定使用 `customer_id=0`；平台资源 API 不接收目标客户参数。资源锁记录仍使用真实业务客户 ID 隔离，但其托盘、库位查找和状态更新必须落到公共资源作用域。
 - 资源锁定以业务幂等键和 reservation 标识防重；释放/报废操作必须验证当前状态。
 - 内部资源接口必须校验服务令牌；普通用户不得直接调用。
+- 本服务不得注册仓库主档创建、编辑、状态或商户仓库查询 Controller；所有资源写入先以相同 `warehouseId` 校验国内只读目录。
 
 ## 数据库表索引与注释约束
 
@@ -34,9 +34,6 @@
 | 库位 | `wh_location` | 海外仓库位资源 |
 | 托盘 | `wh_pallet` | 海外仓实物托盘资源 |
 | 资源锁 | `wh_resource_lock` | 仓储资源锁定记录 |
-| 仓库 | `wh_warehouse` | 海外仓档案 |
-| 仓库地址 | `wh_warehouse_address` | 海外仓地址 |
-| 服务能力 | `wh_service_capability` | 海外仓服务能力 |
 | 托盘绑定 | `wh_pallet_business_binding` | 托盘业务绑定关系 |
 | 托盘操作 | `wh_pallet_operation` | PDA 托盘物理状态流转、幂等与补偿记录 |
 
@@ -45,6 +42,6 @@
 
 ## 修改与验证
 
-- 字段、注释和索引同步维护基线 SQL 与统一增量 SQL。
+- 字段、注释和索引同步维护基线 SQL 与统一增量 SQL；海外数据库禁止新增 `wh_warehouse`、`wh_warehouse_address`、`wh_service_capability` 或指向它们的外键。
 - PDA 托盘流转必须校验内部服务令牌、仓库范围、当前物理状态和幂等键；跨服务业务失败只能通过显式补偿接口恢复，不得由 Lastleg 直接修改 `wh_` 资源表。
 - 定向验证：`mvn -pl warehouse-overseas-service -am test`。