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

# Overseas Warehouse Service 模块指引

## 数据库访问与中文注释约束

- 强制继承 `../AGENTS.md` 的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。

## 职责与边界

- 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`；企业端不得直接维护物理库位与托盘 |
| 内部资源锁定、释放、报废 | `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`；其他托盘调用 `/internal/print/v1/pdfs/pallet-a4-labels`、`PALLET_A4_LANDSCAPE_V1`。两者均为 297×210 mm A4 横向，托盘完整编码作为 Code 128 与底部文字，托盘标不得回退到 100×100 mm 箱唛模板。模板只在 Print 维护；沿用托盘列表权限与统一 Gateway 的 `overseas-warehouse-resources/**` 路由。`baiyue.clients.print.url` 对应 `PRINT_SERVICE_URL`，单机 Compose 使用内部 Print 地址，所有服务位于同一测试 Nacos Namespace；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`。