优化

src/modules/overseas-warehouse/API_INTEGRATION_MATRIX.md

@@ -0,0 +1,18 @@
+# 海外仓真实接口接入矩阵
+
+浏览器只通过共享 `overseasHttp` 请求海外网关，模块路径统一从 `/platform/v1/...` 开始。长整型 ID 全程按字符串处理。以下结论来自 `gateway-overseas`、`lastleg-service`、`warehouse-overseas-service` 当前 Controller/DTO；三者当前没有静态 OpenAPI YAML，本轮未把 Springdoc 注解之外的路径推断为正式接口。
+
+| 原型页面 | 页面 ID | 当前真实接口 | 接入状态 | 说明 |
+|---|---|---|---|---|
+| 尾程订单列表 | `fba-last-mile-order` | `GET /platform/v1/last-leg/orders` | 已接入 | 显式 `customerId`；支持 `page/size/orderNo/inboundCode/containerNo/status`。原型其余筛选保留但禁用，不发送无效参数。 |
+| 尾程订单详情 | `fba-last-mile-order-detail` | `GET /platform/v1/last-leg/orders/{id}` | 已接入 | 展示订单、货物、状态历史和既有单据编号；出库/派送编号只读，不提供离仓动作。 |
+| 入库单列表/详情 | `fba-inbound-order*` | 仅有 `GET /platform/v1/last-leg/inbound-plans/{planNo}` | 阻断 | 没有分页列表，无法由详情接口反推列表；当前页面继续明确显示契约待接入。 |
+| 换标单列表/详情 | `fba-relabel-order*` | `GET /platform/v1/last-leg/relabel-applications`、`GET /{relabelNo}` | 已接入只读 | 列表 DTO 可展示单号、SKU、箱数和状态；详情补产品名、标签要求、文件。预算/费用继续显示空值并记录缺口，未伪造金额。 |
+| 库存/进销存/详情 | `fba-inventory*` | `GET /platform/v1/last-leg/inventory/summary|balances|ledger` | 阻断 | API 是入库单/包裹余额口径，原型是客户/仓库/SKU/产品口径，缺 SKU、产品名及原型指标。 |
+| 托盘列表/详情 | `fba-pallet*` | `GET /platform/v1/warehouse-admin/{warehouseId}/pallets`、`GET /{id}` | 阻断 | API 强制 `customerId + warehouseId` 且资源客户绑定；产品契约要求平台公共资源、独立查询全部客户/仓库。字段还缺 FBA 仓和采购价。 |
+| 箱号列表/详情 | `fba-carton*` | 无平台查询接口 | 阻断 | 只有内部接收事件产生快照，浏览器不得调用内部端点。 |
+| 产品库列表/详情 | `fba-product*` | 无平台查询接口 | 阻断 | 只有内部一件代发快照写入，未提供平台查询/维护端点。 |
+
+状态映射仅使用服务端已有事实：`PENDING_ASSIGNMENT`（待分配）、`DESTINATION_ASSIGNED`（已分配目的仓）、`INBOUND_PLANNED`（已生成入库计划）。未定义的原型状态不发送到接口。
+
+当前所有上述海外业务 Controller 均未声明与前端 `platform:overseas-warehouse:*` 对应的服务端 `@PreAuthorize`。因此本轮只接入尾程只读查询；已有写端点在服务端权限、幂等和原型字段未一致前不向 Admin 暴露。