# 海外仓前端剩余契约与环境缺口

已接请求、权限、客户作用域和错误承载见 `API_INTEGRATION_MATRIX.md`。本文件只保留当前仍影响真实联调或原型完整度的差异，不再把 FBA 预约、换标写接口、托盘公共作用域或静态 OpenAPI 记为“未接/不存在”。

## 需后端或产品继续确认

- **库存客户/海外仓快照**：正式余额 DTO 已返回 `customerName` 与 `overseasWarehouseName`，Admin 列表和详情只显示这两个服务端快照，空值为 `—`，不以 `customerId`、客户候选、国内来源仓、目的仓/FBA 仓或固定值补齐。当前测试数据“客户全为 — / 海外仓显示义乌仓”属于后端库存事实阻断：`LoadingCompletedConsumer#registerInTransit` 的客户名来自可能为空的跨区 `source.customerName`，并把国内装柜 `payload.warehouseName` 传入库存的 `overseasWarehouseName`；后续命中既有余额时 `InventoryCommandService#balance` 不会修订快照。后端需保证正式客户名称快照，并在实际海外收货仓冻结前保持海外仓为空、冻结后写入真实海外收货仓；前端不修复或猜测历史/错误事实。
- **换标原型字段**：列表 Summary 仍不含 `productNameZh/labelRequirement/relabelFile/budgetTotal/relabelCost`；本模块没有可用的换标文件上传端点。页面不伪造金额或文件名。创建 DTO 额外要求海外仓、截止时间、联系人、电话、货件号和新 SKU，这是完成真实创建的最小扩展。
- **托盘新增服务端权限**：前端新增按钮按 `platform:overseas-warehouse:pallet:create` 控制，但当前审计的 `PlatformWarehouseResourceController#createPallet` 未见对应 `@PreAuthorize`；需后端补齐或确认由网关等价强制。原型要求“托盘重量”，当前 Save DTO 无该字段，页面不伪造或发送。
- **托盘状态语义**：原型只给闲置/占用，DTO 还允许 `SCRAPPED`。是否允许 Admin 在普通编辑中直接改为报废仍需确认；不新增独立停用/报废动作。PUT 已按冻结契约携带详情 `version`，旧版本 `A0409`。
- **库存导出**：后端已存在只读 `GET /inventory/balances/export` 与 `GET /inventory/ledger/export`（权限 `...:inventory:export`），当前模块页面/adapter 尚无二进制下载实现；原型承载与共享下载约定确认后再接，不能用 JSON 请求替代。
- **入库补充托盘**：`POST /inbound-plans/{planNo}/pallets/supplement` 已存在，但权限、幂等、打印及原型承载未整体冻结，Admin 不接。FBA 预约创建、详情和编辑已经接入。

## 真实环境仍需的数据与配置

- 可获得海外 Token 且持有矩阵 canonical 权限的 Admin 测试账号；失败响应需验证 `requestId/traceId`。
- 至少一个 ACTIVE 客户，以及国内 Warehouse 中 `tenantId=0`、`OVERSEAS`、`ACTIVE`、启用 `RECEIVING` 的公共收货仓；换标写验收还需允许关联的专用测试尾程订单/SKU，不能操作历史数据。
- 带 `sourceOrderId`、明细和托盘的入仓计划，以及已有 FBA 预约号，用于详情长 ID 与预约编辑。
- 开启 `lastleg.dispatch-query-api.enabled`、`lastleg.smart-dispatch-api.enabled`，并准备未锁候选托盘；验证 409 草稿锁冲突、关闭释放和预排回读。
- 至少一个国内公共海外收货仓 ID，以及 Warehouse Overseas 中引用同一 ID 的公共托盘；新增需验证洛杉矶仓下 `IDLE + ABE3`，编辑需验证正确 version 与旧 version `A0409`。
- 至少一条含 SKU/产品名、位置和 ledger 的库存事实，用于核对分页、汇总与长 ID；不调用离仓命令。

## 仍然排除

箱号平台、产品库、海外出库、退货出库、海外派送、PDA 扫描/拣货/卸柜照片、内部事件，以及库存 `allocate/unallocate/pick/ship`。不得为自动化覆盖扩展这些前端路径。