admin-web/src/modules/overseas-warehouse/API_INTEGRATION_MATRIX.md

# 海外仓真实接口接入矩阵

浏览器只通过共享 `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 预约 | `fba-inbound-order*` | `GET /platform/v1/last-leg/inbound-plans`、`GET /{planNo}`、`POST /fba-appointments/batch`、`GET/PUT /fba-appointments/{appointmentNo}` | 已接入 | 显式 `customerId`、真实分页和筛选；支持按入库明细勾选、同客户/同 FBA 仓校验、预计装车时间以及预约编辑。 |
| 换标单列表/详情 | `fba-relabel-order*` | `GET /platform/v1/last-leg/relabel-applications`、`GET /{relabelNo}` | 已接入只读 | 列表 DTO 可展示单号、SKU、箱数和状态；详情补产品名、标签要求、文件。预算/费用继续显示空值并记录缺口，未伪造金额。 |
| 库存/进销存/详情 | `fba-inventory*` | `GET /platform/v1/last-leg/inventory/summary|balances|balances/{id}/positions|ledger` | 已接入只读 | 列表、汇总、库位/托盘位置与流水已接入；余额返回 SKU/产品名数组，流水返回 SKU 和库位代码。 |
| 托盘列表/详情 | `fba-pallet*` | `GET/POST /platform/v1/warehouse-admin/{warehouseId}/pallets`、`GET/PUT/DELETE /{id}` | 已接入 | 所有请求显式携带 `customerId` 和仓库范围；新增、编辑、删除使用真实 DTO 和真实 Controller 端点。 |
| 箱号列表/详情 | `fba-carton*` | 无平台查询接口 | 本期暂缓 | 本期已从模块正式路由移除；页面、类型、权限常量与测试源码保留，供后续恢复。只有内部接收事件产生快照，浏览器不得调用内部端点。 |
| 产品库列表/详情 | `fba-product*` | 无平台查询接口 | 本期暂缓 | 本期已从模块正式路由移除；页面、类型、权限常量与测试源码保留，供后续恢复。只有内部一件代发快照写入，未提供平台查询/维护端点。 |

状态映射仅使用服务端已有事实：`PENDING_ASSIGNMENT`（待分配）、`DESTINATION_ASSIGNED`（已分配目的仓）、`INBOUND_PLANNED`（已生成入库计划）。未定义的原型状态不发送到接口。

菜单、路由与操作按钮使用真实 Controller 权限：`platform:overseas-warehouse:*`（尾程、入库、换标、库存、仓库、库位和托盘资源）。Admin 未接 PDA、扫码、卸柜照片、内部事件及 `allocate/unallocate/pick/ship` 等离仓命令。

当前正式路由只保留尾程订单、入库单、换标单、托盘管理和库存管理；箱号和产品库本期暂缓，不恢复正式路由。