6.6 KiB
6.6 KiB
海外仓真实接口接入矩阵
海外业务与库位/托盘资源通过共享 overseasHttp 请求海外 Gateway；仓库主数据候选只通过国内 http 请求国内 Warehouse。长整型 ID 及业务单号均按字符串传递，path 参数使用 encodeURIComponent。接口事实已核对 Controller/DTO、Springdoc 与 lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml，不再沿用“海外 Gateway 提供仓库根列表”的旧结论。
| 页面/能力 | Method + Path | Params / Body（当前 adapter） | 权限与承载 |
|---|---|---|---|
| 尾程列表/详情 | GET /platform/v1/last-leg/orders；GET /orders/{id} |
list query：page,size,orderNo,orderType,warehouse,inboundCode,sourceOrderNo,containerNo,currentStatus,transferWarehouseCode,abnormal,detained,createdFrom,createdTo；平台跨客户，不传 customerId |
platform:overseas-warehouse:last-mile-order:list；真实分页、空态、错误及 request/trace 元数据；详情只读展示离仓关联事实 |
| 尾程转目的仓 | PUT /platform/v1/last-leg/orders/destination |
body：orderIds:string[],warehouseId,warehouseCode,warehouseName,remark? |
...:last-mile-order:edit；失败保留弹框，不提示成功 |
| 尾程转入仓计划 | POST /platform/v1/last-leg/inbound-plans/convert |
body：orderId:string，不传客户 |
...:inbound-order:create；不接补托/PDA |
| 入库列表 | GET /platform/v1/last-leg/inbound-plans |
query：page,size,planNo,inboundCode,status,warehouse,fbaWarehouseCode,appointmentStatus,dispatchStatus,createdFrom,createdTo；平台跨客户 |
...:inbound-order:list；lineId/planId/orderId/customerId 均为字符串 |
| 入库详情 | GET /platform/v1/last-leg/inbound-plans/{planNo} |
query：显式 customerId；path 编码 |
同 list；缺客户范围时页面明确报错；sourceOrderId 字符串化 |
| FBA 预约新增 | POST /platform/v1/last-leg/inbound-plans/fba-appointments/batch |
body：customerId,lineIds:string[],appointmentNo,appointmentAt,expectedLoadingAt,appointmentStatus,appointmentRemark? |
...:inbound-order:fba-appointment；只允许同客户、同 FBA 仓勾选 |
| FBA 预约详情/编辑 | GET /fba-appointments/{appointmentNo}?customerId=...；PUT 同 path |
PUT body：customerId,appointmentAt,expectedLoadingAt,appointmentStatus,appointmentRemark? |
GET 同 list；PUT 同 appointment；失败保留弹框和错误元数据 |
| 排车列表/详情 | GET /platform/v1/last-leg/dispatches；GET /dispatches/{dispatchNo} |
list query：page,size,dispatchNo,vehiclePlate,status,fbaAppointmentNo；不传客户 |
...:inbound-order:list；Controller 受 lastleg.dispatch-query-api.enabled 控制 |
| 排车候选 | GET /platform/v1/last-leg/dispatches/candidates |
query：planIds?（逗号分隔长 ID）、orderNo?,fbaWarehouseCode?,sourceStage?,draftToken? |
同 inbound list；仅发 PLAN/RECEIVED |
| 草稿/锁/预排 | GET /dispatches/drafts；POST /drafts/containers；DELETE /drafts/{draftToken}/containers/{containerId}；`POST /draft-locks/lock |
unlock | release；POST /pre-arrange` |
| 库存汇总/余额 | GET /platform/v1/last-leg/inventory/summary；GET /balances |
summary 强制 page=1,size=200；余额保留页面分页；支持 skuCode,productName 与仓库/入库/批次/库位筛选；不传客户 |
...:inventory:list；只读，不调用 allocate/unallocate/pick/ship |
| 库存位置/进销存 | GET /inventory/balances/{balanceId}/positions；GET /inventory/ledger |
position：palletNo?,batchNo?,inventoryStatus?；ledger 含 page,size,skuCode 与业务单/仓库/时间筛选 |
同 inventory list；balanceId 编码；只展示后端事实 |
| 公共海外收货仓候选（国内 HTTP） | GET /platform/v1/warehouse-admin |
tenantId=0,page=1,size=200,capabilityCode=RECEIVING,warehouseType=OVERSEAS,status=ACTIVE |
国内 Warehouse 是唯一仓库主数据源；托盘、库存和换标复用公共候选并保留字符串 ID，不请求海外仓库根路径 |
| 托盘列表/详情 | GET /platform/v1/warehouse-admin/{warehouseId}/pallets；GET /pallets/{palletId} |
list：page,size,keyword?,palletType?,status?；无客户参数 |
...:pallet:list；仓库/托盘长 ID 编码 |
| 托盘新增 | POST /platform/v1/warehouse-admin/{warehouseId}/pallets |
body：palletCode,palletType,fbaWarehouseCode,capacityCbm,unitPrice,status,locationId,remark，明确不带 version |
前端 ...:pallet:create；失败不模拟成功 |
| 托盘编辑 | PUT /platform/v1/warehouse-admin/{warehouseId}/pallets/{palletId} |
新增同字段，并必传详情返回的 version:number |
...:pallet:edit；旧版本返回 A0409，页面保留真实冲突错误。原型未定义删除，模块不保留删除 adapter/入口 |
| 换标列表/详情 | GET /platform/v1/last-leg/relabel-applications；GET /{relabelNo} |
list：page,size,skuCode?,status?；平台跨客户；详情 path 编码 |
...:relabel-order:list；未返回字段不填演示值 |
| 换标创建 | POST /platform/v1/last-leg/relabel-applications?customerId={positiveLong} |
customerId 只在 query；body：customerOrderNo,overseasWarehouseId,labelDeadline,contactName,contactPhone,remark?,idempotencyKey,items[] |
...:relabel-order:create；显式 ACTIVE 客户与公共 ACTIVE+OVERSEAS+RECEIVING 收货仓分别选择；同一弹框会话重试复用同一幂等键，失败保留 |
| 换标状态 | PUT /platform/v1/last-leg/relabel-applications/{relabelNo}/status |
body：status,remark? |
...:relabel-order:status；仅允许 PENDING_PROCESSING→PROCESSING/REJECTED/CANCELLED、PROCESSING→COMPLETED/REJECTED/CANCELLED |
原型与范围
- 页面 ID：尾程
fba-last-mile-order*、入库fba-inbound-order*、换标fba-relabel-order*、托盘fba-pallet*、库存fba-inventory*。排车没有独立海外仓原型页，只在入库页智能排车弹框及既有排车查询页承载。 - 托盘原型操作列仅查看、编辑，工具栏仅新增；后端即使存在 DELETE，Admin 也不暴露。所有业务表格操作列保持第一列并固定左侧。
- 箱号、产品库本期暂缓并从正式 routes 移除；海外出库、退货出库、海外派送、PDA、卸柜照片、内部事件以及库存离仓命令均排除。
- 1920×1080、浏览器 100% 的人工截图仍待验收。