feat(phase4): automate admin integration acceptance

src/modules/overseas-warehouse/API_INTEGRATION_MATRIX.md

@@ -1,20 +1,32 @@
 # 海外仓真实接口接入矩阵
 
-浏览器只通过共享 `overseasHttp` 请求海外网关，模块路径统一从 `/platform/v1/...` 开始。长整型 ID 全程按字符串处理。以下结论来自 `gateway-overseas`、`lastleg-service`、`warehouse-overseas-service` 当前 Controller/DTO；三者当前没有静态 OpenAPI YAML，本轮未把 Springdoc 注解之外的路径推断为正式接口。
+浏览器统一通过共享 `overseasHttp` 请求海外 Gateway，模块传入 `/platform/v1/...`；Controller 完整路径带 `/api` 前缀。长整型 ID 及业务单号均按字符串传递，path 参数使用 `encodeURIComponent`。接口事实已核对 Controller/DTO、Springdoc 与 `lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml`，不再沿用“无静态 OpenAPI”的旧结论。
 
-| 原型页面 | 页面 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*` | 无平台查询接口 | 本期暂缓 | 本期已从模块正式路由移除；页面、类型、权限常量与测试源码保留，供后续恢复。只有内部一件代发快照写入，未提供平台查询/维护端点。 |
+| 页面/能力 | 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` | 车厢：`draftToken,capacity`；锁：`planPalletId,draftToken,draftContainerId?`；释放：`draftToken`；预排：`planPalletIds:string[],draftToken` | `...:inbound-order:smart-dispatch`；Controller 受 `lastleg.smart-dispatch-api.enabled` 控制；409 锁冲突显示真实错误；不调用编辑、取消、depart、PDA 或派送 |
+| 库存汇总/余额 | `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` 编码；只展示后端事实 |
+| 公共海外仓候选 | `GET /platform/v1/warehouse-admin` | `page=1,size=200`，不传 `customerId` | `...:warehouse:list`；仓储资源固定公共作用域 `customer_id=0` |
+| 托盘列表/详情 | `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 海外仓；同一弹框会话重试复用同一幂等键，失败保留 |
+| 换标状态 | `PUT /platform/v1/last-leg/relabel-applications/{relabelNo}/status` | body：`status,remark?` | `...:relabel-order:status`；仅允许 `PENDING_PROCESSING→PROCESSING/REJECTED/CANCELLED`、`PROCESSING→COMPLETED/REJECTED/CANCELLED` |
 
-状态映射仅使用服务端已有事实：`PENDING_ASSIGNMENT`（待分配）、`DESTINATION_ASSIGNED`（已分配目的仓）、`INBOUND_PLANNED`（已生成入库计划）。未定义的原型状态不发送到接口。
+## 原型与范围
 
-菜单、路由与操作按钮使用真实 Controller 权限：`platform:overseas-warehouse:*`（尾程、入库、换标、库存、仓库、库位和托盘资源）。Admin 未接 PDA、扫码、卸柜照片、内部事件及 `allocate/unallocate/pick/ship` 等离仓命令。
-
-当前正式路由只保留尾程订单、入库单、换标单、托盘管理和库存管理；箱号和产品库本期暂缓，不恢复正式路由。
+- 页面 ID：尾程 `fba-last-mile-order*`、入库 `fba-inbound-order*`、换标 `fba-relabel-order*`、托盘 `fba-pallet*`、库存 `fba-inventory*`。排车没有独立海外仓原型页，只在入库页智能排车弹框及既有排车查询页承载。
+- 托盘原型操作列仅查看、编辑，工具栏仅新增；后端即使存在 DELETE，Admin 也不暴露。所有业务表格操作列保持第一列并固定左侧。
+- 箱号、产品库本期暂缓并从正式 routes 移除；海外出库、退货出库、海外派送、PDA、卸柜照片、内部事件以及库存离仓命令均排除。
+- 1920×1080、浏览器 100% 的人工截图仍待验收。