Merge origin/dev and resolve backend conflicts

lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml

@@ -3,6 +3,18 @@ info:
   title: Lastleg Overseas Business API
   version: 1.0.0
 paths:
+  /api/platform/v1/last-leg/inventory/balances/{balanceId}:
+    get:
+      summary: 查询单条库存余额详情
+      description: 仅平台且要求 lastleg:inventory:list；按 balanceId 直接查询非零库存余额，不依赖列表分页。可选 customerId 用于精确客户隔离，越权或不存在统一返回404。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { in: path, name: balanceId, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$', description: 长整型ID按字符串传输 } }
+        - { in: query, name: customerId, required: false, schema: { type: string } }
+      responses:
+        '200': { description: 单条库存余额, content: { application/json: { schema: { $ref: '#/components/schemas/InventoryBalanceApiResponse' } } } }
+        '403': { description: 非平台身份或缺少库存查看权限 }
+        '404': { description: 库存余额不存在、已归零或不属于指定客户 }
   /api/platform/v1/last-leg/inventory/inbound-code-relationships/{inboundCode}:
     get:
       summary: 按入仓码查询海外关系摘要
@@ -149,7 +161,7 @@ paths:
   /api/platform/v1/last-leg/orders:
     get:
       summary: 分页查询尾程订单
-      description: 权限 platform:overseas-warehouse:order:list；平台管理员省略 customerId 时查询全部客户。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；平台管理员省略 customerId 时查询全部客户。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -160,13 +172,13 @@ paths:
         - { name: inboundCode, in: query, schema: { type: string } }
         - { name: sourceOrderNo, in: query, schema: { type: string } }
         - { name: containerNo, in: query, schema: { type: string } }
-        - { name: warehouse, in: query, schema: { type: string } }
+        - { name: warehouse, in: query, description: 按尾程订单冻结的海外接柜仓名称或编码进行大小写无关的包含匹配, schema: { type: string } }
         - { name: transferWarehouseCode, in: query, schema: { type: string } }
         - { name: abnormal, in: query, schema: { type: boolean } }
         - { name: detained, in: query, schema: { type: boolean } }
         - { name: createdFrom, in: query, schema: { type: string, format: date-time } }
         - { name: createdTo, in: query, schema: { type: string, format: date-time } }
-      responses: { '200': { description: 统一 ApiResponse 包装的尾程订单分页；列表行 destinationType 为 FBA 或 OVERSEAS } }
+      responses: { '200': { description: 统一 ApiResponse 包装的尾程订单分页；列表行 destinationType 为 FBA 或 OVERSEAS；inboundCode 仅返回真实来源入仓码，无入仓关系的换标申请和本土散板为空 } }
   /api/platform/v1/last-leg/orders/{id}:
     get:
       summary: 查询尾程订单详情
@@ -192,25 +204,46 @@ paths:
       responses:
         '200': { description: 新增后的费用明细, content: { application/json: { schema: { $ref: '#/components/schemas/LastMileFeeApiResponse' } } } }
         '404': { description: 尾程订单不存在或不属于操作客户 }
-  /api/platform/v1/last-leg/orders/{id}/detained:
+  /api/platform/v1/last-leg/orders/{id}/hold:
     put:
       summary: 设置或解除尾程订单暂扣
-      description: 权限 platform:overseas-warehouse:last-mile-order:edit；库存同步转入或释放暂扣，并通过跨区事件回写国内入仓单。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；使用订单版本和 Idempotency-Key 原子写入计费标记、原因及不可变历史。已进入出库流程的订单不得新增暂扣；暂扣只作用于当前票，不影响同柜其他订单。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
         - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
       requestBody:
         required: true
         content:
           application/json:
-            schema:
-              type: object
-              required: [detained, remark]
-              properties:
-                detained: { type: boolean }
-                remark: { type: string, minLength: 1, maxLength: 500 }
-      responses: { '200': { description: 暂扣状态已更新 } }
+            schema: { $ref: '#/components/schemas/LastlegOrderHoldRequest' }
+      responses:
+        '200': { description: 暂扣状态已更新, content: { application/json: { schema: { type: object, properties: { code: { type: string }, data: { $ref: '#/components/schemas/LastlegOrderHoldResponse' } } } } } }
+        '409': { description: 版本冲突、幂等键冲突、重复状态或订单已进入出库流程 }
+  /api/platform/v1/last-leg/orders/{id}/manual-nodes:
+    get:
+      summary: 查询尾程订单人工展示节点
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；人工覆盖开启后返回完整且固定顺序的8行快照，行值允许为空。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses: { '200': { description: 完整人工展示节点快照 } }
+    put:
+      summary: 永久启用并保存尾程订单人工展示节点
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；提交完整8行快照且至少一个时间非空，使用订单版本和 Idempotency-Key；保存后 nodeSource 永久为 MANUAL，不回写柜节点，也不提供清除或恢复继承接口。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/LastlegOrderManualNodesRequest' } } }
+      responses:
+        '200': { description: 更新后的完整8行人工展示节点快照 }
+        '409': { description: 订单版本或幂等键冲突 }
   /api/platform/v1/last-leg/orders/{id}/pallet-merge-required:
     put:
       summary: 设置尾程订单合托标记
@@ -253,7 +286,7 @@ paths:
   /api/platform/v1/last-leg/orders/container-summaries:
     get:
       summary: 分页查询柜级入库计划进度
-      description: 权限 platform:overseas-warehouse:order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响，仅返回仍有入仓码待生成有效独立计划的柜，全部入仓码均已生成有效独立计划的柜在分页前排除。containerNo 只返回装柜完成事件携带并规范化冻结的真实集装箱号，不从 cabinetNo、订单号或内部 ID 推导。plannedArrivalAt 仅来自装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at；按该时间升序、null 最后、稳定柜 ID 升序。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响，返回全部稳定来源柜；全部入仓码均已生成有效独立计划的柜仍保留，供柜级接柜仓查询与修改，生成计划动作由 allPlansReady/pendingPlanCount 控制。containerNo 只返回装柜完成事件携带并规范化冻结的真实集装箱号，不从 cabinetNo、订单号或内部 ID 推导。plannedArrivalAt 仅来自装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at；按该时间升序、null 最后、稳定柜 ID 升序。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -283,7 +316,7 @@ paths:
   /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}:
     get:
       summary: 查询柜级入库计划进度详情
-      description: 权限 platform:overseas-warehouse:order:list；按稳定柜 ID 返回柜内全部尾程订单、入仓码及各自计划状态，不受订单分页截断。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；按稳定柜 ID 返回柜内全部尾程订单、入仓码及各自计划状态，不受订单分页截断。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
@@ -298,10 +331,27 @@ paths:
                   code: { type: string, enum: ['200'] }
                   data: { $ref: '#/components/schemas/ContainerPlanProgressDetail' }
         '404': { description: 稳定柜 ID 不存在 }
+  /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}/receiving-warehouse:
+    put:
+      summary: 修改整柜海外接柜仓
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；目标必须为国内 Warehouse Service 有效 OVERSEAS 仓。使用柜级版本和 Idempotency-Key，事务内原子同步柜内全部尾程订单及已有入库计划；海外PDA一旦建立接柜会话即永久锁定。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ChangeReceivingWarehouseRequest' }
+      responses:
+        '200': { description: 更新后的柜级摘要, content: { application/json: { schema: { type: object, properties: { code: { type: string, enum: ['200'] }, data: { $ref: '#/components/schemas/ContainerPlanProgressSummary' } } } } }
+        '400': { description: 请求无效或目标不是有效 OVERSEAS 仓 }
+        '409': { description: 版本冲突、幂等键冲突或PDA接柜会话已建立 }
   /api/platform/v1/last-leg/orders/{id}/destination:
     put:
       summary: 将单票尾程订单转入 FBA 目的仓
-      description: 权限 platform:overseas-warehouse:order:edit；目标必须来自国内 Warehouse Service 平台公共 ACTIVE FBA 主档，warehouseId/warehouseCode/warehouseName 必须与权威记录一致。实际海外收货仓、普通国内中转仓、停用仓或伪造字段均返回 A0400“所选FBA仓不存在或已停用”。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；目标必须来自国内 Warehouse Service 平台公共 ACTIVE FBA 主档，warehouseId/warehouseCode/warehouseName 必须与权威记录一致。实际海外收货仓、普通国内中转仓、停用仓或伪造字段均返回 A0400“所选FBA仓不存在或已停用”。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
@@ -318,7 +368,7 @@ paths:
   /api/platform/v1/last-leg/orders/destination:
     put:
       summary: 批量将尾程订单转入 FBA 目的仓
-      description: 权限 platform:overseas-warehouse:order:edit；一次校验国内 Warehouse Service 权威 FBA 主档后，在 Lastleg 事务内更新所选订单及冻结明细。目标仓必须为平台公共 ACTIVE FBA 且 ID/编码/名称完全一致。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；一次校验国内 Warehouse Service 权威 FBA 主档后，在 Lastleg 事务内更新所选订单及冻结明细。目标仓必须为平台公共 ACTIVE FBA 且 ID/编码/名称完全一致。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
@@ -331,26 +381,59 @@ paths:
         '200': { description: 统一 ApiResponse 包装的更新订单数 }
         '400': { description: 所选FBA仓不存在、已停用、类型错误或字段不一致 }
         '503': { description: 国内FBA仓权威主数据暂不可用，写入失败关闭 }
-  /api/platform/v1/last-leg/inbound-plans/convert:
-    post:
-      summary: 平台生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；必须同时传入真实 customerId 与 orderId，服务端按该客户和订单 ID 锁定归属，缺失 customerId 返回 A0400。
+  /api/platform/v1/last-leg/inbound-plans:
+    get:
+      summary: 平台分页查询海外入库订单
+      description: 权限 platform:overseas-warehouse:inbound-order:list；列表中的 overseasWarehouseCode/overseasWarehouseName 只取尾程订单预分配接柜仓事实，warehouseCode/warehouseName 仍表示目的仓。
       security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
+        - { name: planNo, in: query, schema: { type: string } }
+        - { name: inboundCode, in: query, schema: { type: string } }
+        - { name: lxCode, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string } }
+        - { name: overseasWarehouseId, in: query, schema: { type: string } }
+        - { name: destinationWarehouseCode, in: query, schema: { type: string } }
+        - { name: warehouse, in: query, schema: { type: string } }
+        - { name: fbaWarehouseCode, in: query, schema: { type: string } }
+        - { name: appointmentStatus, in: query, schema: { type: string, enum: [UNAPPOINTED, PENDING, SUCCESS, FAILED, CANCELLED] } }
+        - { name: dispatchStatus, in: query, schema: { type: string, enum: [UNSCHEDULED, SCHEDULED] } }
+        - { name: createdFrom, in: query, schema: { type: string, format: date-time } }
+        - { name: createdTo, in: query, schema: { type: string, format: date-time } }
+      responses: { '200': { description: 平台入库订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanPageResponse' } } } } }
+  /api/platform/v1/last-leg/inbound-plans/{planNo}:
+    get:
+      summary: 平台查询海外入库订单详情
+      description: 权限 platform:overseas-warehouse:inbound-order:list；详情中的 overseasWarehouseCode/overseasWarehouseName 只取当前计划来源尾程订单的预分配接柜仓事实。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: planNo, in: path, required: true, schema: { type: string } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses:
+        '200': { description: 平台入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }
+        '404': { description: 入库订单不存在或不属于指定客户 }
+  /api/platform/v1/last-leg/inbound-plans/manual:
+    post:
+      summary: 平台按单票手工生成入库计划
+      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、暂扣状态、真实入仓码、客户归属及有效公共接柜仓。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
       requestBody:
         required: true
         content:
           application/json:
-            schema:
-              type: object
-              required: [customerId, orderId]
-              properties:
-                customerId: { type: string, pattern: '^[1-9][0-9]*$' }
-                orderId: { type: string, pattern: '^[1-9][0-9]*$' }
-      responses: { '200': { description: 统一 ApiResponse 包装的入库计划详情 } }
+            schema: { $ref: '#/components/schemas/ManualInboundPlanRequest' }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的入库计划详情 }
+        '400': { description: 客户、入仓码、仓库主数据或请求字段无效 }
+        '409': { description: 订单版本、状态、暂扣状态、重复计划或幂等键冲突 }
   /api/platform/v1/last-leg/inbound-plans/convert-container:
     post:
-      summary: 按整柜批量生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；使用稳定 sourceContainerBookingId 锁定整柜订单，并要求全柜尾程订单及既有计划的真实 containerNo 快照一致。每个尾程订单/入仓码独立生成一个入库计划，整批原子且幂等；任何柜号漂移均冲突且不部分写入。
+      summary: 按整柜批量生成剩余入库计划
+      description: 权限 platform:overseas-warehouse:inbound-order:create；使用稳定 sourceContainerBookingId 锁定整柜订单，并要求全柜尾程订单及既有有效计划的真实 containerNo 与接柜仓快照一致。已有有效计划保持不变，只为剩余尾程订单/入仓码分别生成独立计划；响应按柜内订单稳定顺序返回全部已有及新增计划。整批原子且幂等，剩余为0时直接返回已有结果；任何快照漂移均冲突且不部分写入。
       security: [{ bearerAuth: [] }]
       requestBody:
         required: true
@@ -508,13 +591,25 @@ paths:
       parameters: [{ name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/OneClickOutboundCreate' } } } }
       responses: { '200': { description: 一件代发出库 PDA 任务 }, '409': { description: 库存或幂等冲突 } }
+  /api/platform/v1/last-leg/outbound-orders/one-click-dropship/candidates:
+    get:
+      summary: 查询一件代发出库候选库存
+      description: 权限 platform:overseas-warehouse:outbound:create；按客户及可选海外仓一次查询服务端权威候选，仅返回 ACTIVE 一件代发档案、OCCUPIED 正可用库存、AVAILABLE 箱唛与 SKU 余额共同覆盖且未被排车、转仓或待执行出库占用的维度。创建命令会再次校验，不信任前端候选快照。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: warehouseId, in: query, required: false, schema: { type: string } }
+      responses:
+        '200':
+          description: 最多 500 条一件代发出库候选；单次 SQL 返回，不逐行补查
+          content: { application/json: { schema: { type: array, items: { $ref: '#/components/schemas/OneClickOutboundCandidate' } } } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}:
     get:
       summary: 查询出库单详情
       description: 权限 platform:overseas-warehouse:outbound:list；只按全局唯一 outboundNo 定位并从记录解析客户范围，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: outboundNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: 出库单及关联派送单详情 }, '404': { description: 出库单不存在 } }
+      responses: { '200': { description: 出库单、出库托盘及关联派送单详情；pallets[].palletNo 为 Warehouse 权威实物托盘码 }, '404': { description: 出库单不存在 } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}/cancel:
     post:
       summary: 取消未执行出库单
@@ -526,13 +621,13 @@ paths:
   /api/platform/v1/last-leg/delivery-orders:
     get:
       summary: 分页查询平台派送单
-      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。
+      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。每行返回服务端计算的 allowedActions，页面不得自行推导状态门禁。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 派送单分页 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}:
     get:
       summary: 查询平台派送单详情
-      description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读。
+      description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读；order.allowedActions 为当前可执行动作。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 派送单详情 }, '404': { description: 派送单不存在 } }
@@ -548,6 +643,49 @@ paths:
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
       responses: { '200': { description: 已创建异常订单 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}:
+    get:
+      summary: 查询异常订单详情与冻结退回明细
+      description: 权限 platform:overseas-warehouse:exception-order:list；返回 version 和服务端 allowedActions。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 异常订单详情 }, '404': { description: 异常订单不存在 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/start-processing:
+    post:
+      summary: 开始处理异常订单
+      description: 权限 platform:overseas-warehouse:exception-order:process；仅 PENDING→PROCESSING，同版本与同幂等请求可重放。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExceptionStartProcessing' } } } }
+      responses: { '200': { description: 异常处理命令结果 }, '409': { description: 版本、状态或幂等冲突 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/evidence:
+    post:
+      summary: 上传异常处理证据
+      description: 权限 platform:overseas-warehouse:exception-order:process；文件按当前客户和异常订单绑定为 OVERSEAS_EXCEPTION_EVIDENCE。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } }
+      responses: { '200': { description: 异常处理证据元数据 }, '400': { description: 文件或归属无效 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/complete:
+    post:
+      summary: 完成异常处理并原子恢复退回库存
+      description: 权限 platform:overseas-warehouse:exception-order:process；仅 PROCESSING→COMPLETED。退回海外仓必须提交证据和实收目标，库存 RETURN_STOCK_IN 成功后才完成异常单和派送退回。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExceptionComplete' } } } }
+      responses: { '200': { description: 异常处理与库存恢复结果 }, '409': { description: 版本、状态、归属、数量或幂等冲突 } }
+  /api/platform/v1/last-leg/exception-orders/{exceptionNo}/cancel:
+    post:
+      summary: 取消未处理异常订单
+      description: 权限 platform:overseas-warehouse:exception-order:process；仅 PENDING→CANCELLED。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: exceptionNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ExceptionCancel' } } } }
+      responses: { '200': { description: 异常取消结果 }, '409': { description: 版本、状态或幂等冲突 } }
   /api/platform/v1/last-leg/exception-orders/resolve:
     get:
       summary: 解析异常订单关联关系
@@ -557,33 +695,34 @@ paths:
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/return-inbound-options:
     get:
       summary: 查询派送退回候选入仓单
-      description: 权限 platform:overseas-warehouse:exception-order:list；属于异常订单列表只读辅助接口。
+      description: 权限 platform:overseas-warehouse:exception-order:list；返回按原出库拣货事实解析的 returnSources，页面不得自由填写 SKU 或猜测库存位置。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 退回候选入仓单 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/mark-return:
     post:
       summary: 将派送单标记为退回入仓
-      description: 权限 platform:overseas-warehouse:delivery:return。
+      description: 权限 platform:overseas-warehouse:delivery:return；items 必须来自 return-inbound-options，服务端冻结源出库明细与批准退回上限。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryMarkReturn' } } } }
       responses: { '200': { description: 已创建退回异常单 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/complete:
     post:
       summary: 标记派送完成并生成回访记录
-      description: 权限 platform:overseas-warehouse:delivery:status。
+      description: 权限 platform:overseas-warehouse:delivery:status。仅 WAIT_DELIVERY/DELIVERING 可完成；DELIVERED 同状态重放成功，其他终态或倒退返回 409。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: 派送状态与回访记录 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
+      responses: { '200': { description: 派送状态与回访记录 }, '409': { description: 版本或状态冲突 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/status:
     put:
       summary: 更新派送状态
-      description: 权限 platform:overseas-warehouse:delivery:status。
+      description: 权限 platform:overseas-warehouse:delivery:status。只允许 WAIT_DELIVERY→DELIVERING/DELIVERED/REJECTED/CANCELLED、DELIVERING→DELIVERED/REJECTED；同状态幂等，终态不可倒退。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { type: object } } } }
-      responses: { '200': { description: 更新后的派送状态 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
+      responses: { '200': { description: 更新后的派送状态 }, '409': { description: 非法状态迁移 } }
   /api/platform/v1/last-leg/customer-visits:
     get:
       summary: 分页查询客户回访
@@ -811,7 +950,7 @@ paths:
   /api/merchant/v1/last-leg/inbound-plans:
     get:
       summary: 客户分页查询自己的海外入库订单
-      description: 权限 merchant:warehouse:inbound:list；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:warehouse:inbound:list；客户范围只取认证 Token，不接收 customerId；overseasWarehouseCode/overseasWarehouseName 只取该客户尾程订单预分配接柜仓事实，warehouseCode/warehouseName 仍表示目的仓。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -829,7 +968,7 @@ paths:
   /api/merchant/v1/last-leg/inbound-plans/{planNo}:
     get:
       summary: 客户查询自己的海外入库订单详情
-      description: 权限 merchant:warehouse:inbound:list；列表权限包含详情只读，不接收 customerId。
+      description: 权限 merchant:warehouse:inbound:list；列表权限包含详情只读，不接收 customerId；overseasWarehouseCode/overseasWarehouseName 只取该计划来源尾程订单的预分配接柜仓事实。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: planNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 当前客户入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }, '404': { description: 当前客户下入库订单不存在 } }
@@ -1186,6 +1325,39 @@ components:
         height: { type: number, exclusiveMinimum: 0, description: '箱高，CM' }
         weight: { type: number, exclusiveMinimum: 0, description: '箱重，KG' }
         idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+    InventoryBalance:
+      type: object
+      required: [id, customerId, totalPackages, availablePackages, holdPackages, allocatedPackages, pickedPackages, inTransitPackages, receivingPackages, procurementPackages]
+      properties:
+        id: { type: string, pattern: '^[1-9][0-9]*$', description: 库存余额长整型ID，按字符串传输 }
+        customerId: { type: string }
+        customerName: { type: string, nullable: true }
+        overseasWarehouseId: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, nullable: true }
+        overseasWarehouseName: { type: string, nullable: true }
+        destinationWarehouseId: { type: string, nullable: true }
+        destinationWarehouseCode: { type: string, nullable: true }
+        destinationWarehouseName: { type: string, nullable: true }
+        inboundOrderId: { type: string, nullable: true, pattern: '^[1-9][0-9]*$', description: 长整型ID按字符串传输 }
+        inboundOrderNo: { type: string, nullable: true }
+        inboundCode: { type: string, nullable: true }
+        skuCode: { type: string, nullable: true }
+        productNameZh: { type: string, nullable: true }
+        productNameEn: { type: string, nullable: true }
+        totalPackages: { type: integer, format: int64, minimum: 0 }
+        availablePackages: { type: integer, format: int64, minimum: 0 }
+        holdPackages: { type: integer, format: int64, minimum: 0 }
+        allocatedPackages: { type: integer, format: int64, minimum: 0 }
+        pickedPackages: { type: integer, format: int64, minimum: 0 }
+        inTransitPackages: { type: integer, format: int64, minimum: 0 }
+        receivingPackages: { type: integer, format: int64, minimum: 0 }
+        procurementPackages: { type: integer, format: int64, minimum: 0 }
+        updatedAt: { type: string, format: date-time, nullable: true }
+    InventoryBalanceApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/InventoryBalance' } }
     InboundCodeRelationship:
       type: object
       required: [inboundCode, found, taillegOrders, inboundPlans, palletCodes, inventory]
@@ -1259,10 +1431,16 @@ components:
               items: { type: string, pattern: '^[1-9][0-9]*$' }
     ContainerPlanProgressSummary:
       type: object
-      required: [sourceContainerBookingId, containerNo, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
+      required: [sourceContainerBookingId, containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, assignmentVersion, canChangeReceivingWarehouse, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
       properties:
         sourceContainerBookingId: { type: string }
         containerNo: { type: string, pattern: '^[A-Z]{3}[UJZ][0-9]{7}$', description: 装柜完成事件非空且通过 ISO 6346 校验位验证的规范化真实集装箱号；不使用 cabinetNo、订单号或内部 ID 回退 }
+        overseasWarehouseId: { type: string, pattern: '^[1-9][0-9]*$', description: 平台预分配的海外接柜仓ID，不是FBA目的仓 }
+        overseasWarehouseCode: { type: string, description: 海外接柜仓业务编码 }
+        overseasWarehouseName: { type: string, description: 海外接柜仓业务名称 }
+        assignmentVersion: { type: integer, minimum: 0, description: 柜级接柜仓乐观锁版本 }
+        canChangeReceivingWarehouse: { type: boolean }
+        receivingWarehouseLockReason: { type: string, nullable: true }
         totalOrderCount: { type: integer, format: int64 }
         inboundCodeCount: { type: integer, format: int64 }
         missingInboundCodeCount: { type: integer, format: int64 }
@@ -1272,6 +1450,13 @@ components:
         plannedArrivalAt: { type: string, format: date-time, nullable: true, description: 仅来源于装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at }
         allPlansReady: { type: boolean, description: 全柜每票均有入仓码且均存在有效独立计划时为 true }
         blockingReason: { type: string, nullable: true }
+    ChangeReceivingWarehouseRequest:
+      type: object
+      required: [overseasWarehouseId, expectedVersion]
+      properties:
+        overseasWarehouseId: { type: integer, format: int64, minimum: 1 }
+        expectedVersion: { type: integer, minimum: 0 }
+        remark: { type: string, maxLength: 500, nullable: true }
     ContainerPlanProgressDetail:
       type: object
       required: [summary, orders]
@@ -1495,10 +1680,12 @@ components:
         warehouseName: { type: string, description: 国内Warehouse Service主档维护的当前中文名称 }
     ReceivingCandidate:
       type: object
-      required: [sourceContainerBookingId, containerNo, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
+      required: [sourceContainerBookingId, containerNo, overseasWarehouseCode, overseasWarehouseName, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
       properties:
         sourceContainerBookingId: { type: string, description: 头程与尾程共享的稳定柜身份 }
         containerNo: { type: string }
+        overseasWarehouseCode: { type: string }
+        overseasWarehouseName: { type: string }
         status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
         totalOrderCount: { type: integer, minimum: 1 }
         missingInboundCodeCount: { type: integer, minimum: 0 }
@@ -1517,10 +1704,11 @@ components:
         currentAccount: { type: boolean }
     ReceivingSession:
       type: object
-      required: [containerNo, overseasWarehouseId, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, inbounds]
+      required: [containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, inbounds]
       properties:
         containerNo: { type: string }
-        overseasWarehouseId: { type: string, pattern: '^\d+$', description: PDA Token绑定并在认领柜号时冻结的共享实际海外收货仓ID }
+        overseasWarehouseId: { type: string, pattern: '^\d+$', description: 平台预分配并与PDA Token匹配的海外接柜仓ID }
+        overseasWarehouseCode: { type: string, description: 海外接柜仓业务编码快照 }
         overseasWarehouseName: { type: string, description: Warehouse Overseas服务校验后的共享实际海外收货仓名称快照 }
         status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
         operatorName: { type: string, nullable: true }
@@ -1637,7 +1825,7 @@ components:
         orderNo: { type: string }
         orderRefs: { type: string }
         inboundCode: { type: string }
-        palletNo: { type: string }
+        palletNo: { type: string, description: 未入库时为计划托盘码；绑定实物托盘后为 Warehouse 权威实物托盘码 }
         destinationWarehouseId: { type: string }
         destinationWarehouseCode: { type: string }
         destinationWarehouseName: { type: string }
@@ -1729,6 +1917,76 @@ components:
         sellerName: { type: string, nullable: true, maxLength: 128 }
         remark: { type: string, nullable: true, maxLength: 1000 }
         fees: { type: array, minItems: 1, maxItems: 20, items: { $ref: '#/components/schemas/DeliveryFeeInput' } }
+    DeliveryStatusChange:
+      type: object
+      required: [status, expectedVersion]
+      properties:
+        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, DELIVERED, REJECTED, CANCELLED] }
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        remark: { type: string, nullable: true, maxLength: 500 }
+    DeliveryAllowedAction:
+      type: string
+      enum: [START_DELIVERY, COMPLETE_DELIVERY, REJECT_DELIVERY, CANCEL_DELIVERY, MARK_RETURN]
+      description: START/COMPLETE/REJECT/CANCEL 使用通用 status 接口；MARK_RETURN 使用 mark-return 接口。
+    DeliveryMarkReturn:
+      type: object
+      required: [inboundOrderId, reason, returnDirection, items, idempotencyKey]
+      properties:
+        inboundOrderId: { type: string, pattern: '^[1-9][0-9]*$' }
+        reason: { type: string, minLength: 1, maxLength: 1000 }
+        returnDirection: { type: string, enum: [OVERSEAS_WAREHOUSE, CUSTOMER, OTHER] }
+        returnLogisticsNo: { type: string, nullable: true, maxLength: 128 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        items:
+          type: array
+          minItems: 1
+          maxItems: 200
+          items:
+            type: object
+            required: [outboundPalletItemId, inventoryPositionId, packageCount]
+            properties:
+              outboundPalletItemId: { type: string, pattern: '^[1-9][0-9]*$' }
+              inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
+              packageCount: { type: integer, format: int64, minimum: 1 }
+    ExceptionStartProcessing:
+      type: object
+      required: [expectedVersion, idempotencyKey]
+      properties:
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        handlingAction: { type: string, nullable: true, maxLength: 1000 }
+    ExceptionCancel:
+      type: object
+      required: [expectedVersion, idempotencyKey, reason]
+      properties:
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        reason: { type: string, minLength: 1, maxLength: 1000 }
+    ExceptionComplete:
+      type: object
+      required: [expectedVersion, idempotencyKey, handlingResult, evidenceFileIds]
+      properties:
+        expectedVersion: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        handlingResult: { type: string, minLength: 1, maxLength: 2000 }
+        evidenceFileIds: { type: array, minItems: 1, maxItems: 20, items: { type: string } }
+        receipts:
+          type: array
+          maxItems: 200
+          items:
+            type: object
+            required: [outboundPalletItemId, inventoryPositionId, receivedPackages, targetPalletId, targetPalletNo, targetLocationId, targetLocationCode]
+            properties:
+              outboundPalletItemId: { type: string, pattern: '^[1-9][0-9]*$' }
+              inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
+              receivedPackages: { type: integer, format: int64, minimum: 1 }
+              targetPalletId: { type: string, pattern: '^[1-9][0-9]*$' }
+              targetPalletNo: { type: string, minLength: 1, maxLength: 128 }
+              targetLocationId: { type: string, pattern: '^[1-9][0-9]*$' }
+              targetLocationCode: { type: string, minLength: 1, maxLength: 128 }
+    ExceptionAllowedAction:
+      type: string
+      enum: [START_PROCESSING, COMPLETE_EXCEPTION, CANCEL_EXCEPTION]
     DeliveryFeeInput:
       type: object
       required: [feeType, currency, amount]
@@ -1755,6 +2013,18 @@ components:
               inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
               packages: { type: integer, format: int64, minimum: 1 }
               sku: { type: string, maxLength: 128 }
+    OneClickOutboundCandidate:
+      type: object
+      required: [inventoryPositionId, overseasWarehouseId, palletNo, skuCode, availablePackages]
+      properties:
+        inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$', description: 创建命令提交键，不作为用户展示编号 }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseName: { type: string, nullable: true }
+        palletNo: { type: string }
+        inboundCode: { type: string, nullable: true }
+        skuCode: { type: string }
+        productName: { type: string, nullable: true }
+        availablePackages: { type: integer, format: int64, minimum: 1, description: 库存位置、SKU余额和AVAILABLE箱唛三者的可用最小值 }
     OutboundCancel:
       type: object
       required: [reason]
@@ -1909,6 +2179,58 @@ components:
         - { $ref: '#/components/schemas/MerchantApiResponse' }
         - type: object
           properties: { data: { $ref: '#/components/schemas/InboundPlanDetail' } }
+    LastlegOrderHoldRequest:
+      type: object
+      required: [held, chargeable, reason, expectedVersion]
+      properties:
+        held: { type: boolean }
+        chargeable: { type: boolean, description: 仅 held=true 时生效；解除暂扣后固定为 false }
+        reason: { type: string, minLength: 1, maxLength: 500 }
+        expectedVersion: { type: integer, minimum: 0 }
+    LastlegOrderHoldResponse:
+      type: object
+      required: [orderId, held, chargeable, version]
+      properties:
+        orderId: { type: integer, format: int64 }
+        held: { type: boolean }
+        chargeable: { type: boolean }
+        reason: { type: string, nullable: true }
+        version: { type: integer, minimum: 0 }
+    LastlegOrderManualNodeCode:
+      type: string
+      enum: [DOMESTIC_CUSTOMS_COMPLETED, ESTIMATED_DEPARTURE, ACTUAL_DEPARTURE, ESTIMATED_ARRIVAL, OVERSEAS_CUSTOMS_COMPLETED, ACTUAL_ARRIVAL_WAITING_UNLOAD, PICKUP_APPOINTED, UNLOADED]
+    LastlegOrderManualNode:
+      type: object
+      required: [nodeCode]
+      properties:
+        nodeCode: { $ref: '#/components/schemas/LastlegOrderManualNodeCode' }
+        nodeAt: { type: string, format: date-time, nullable: true }
+    LastlegOrderManualNodesRequest:
+      type: object
+      required: [expectedVersion, nodes]
+      properties:
+        expectedVersion: { type: integer, minimum: 0 }
+        nodes:
+          type: array
+          minItems: 8
+          maxItems: 8
+          description: 必须包含8个枚举节点且各出现一次，至少一个 nodeAt 非空。
+          items: { $ref: '#/components/schemas/LastlegOrderManualNode' }
+    ManualInboundPlanRequest:
+      type: object
+      description: 单票人工计划只能使用所属柜已冻结的接柜仓；接柜仓变更必须通过柜级接口完成。
+      required: [customerId, orderId, expectedOrderVersion, plannedArrivalDate, palletCount, palletType, assigned, mergeRequired, urgent]
+      properties:
+        customerId: { type: string, pattern: '^[1-9][0-9]*$' }
+        orderId: { type: integer, format: int64, minimum: 1 }
+        expectedOrderVersion: { type: integer, minimum: 0 }
+        plannedArrivalDate: { type: string, format: date }
+        palletCount: { type: integer, minimum: 1, maximum: 999 }
+        palletType: { type: string, minLength: 1, maxLength: 64 }
+        assigned: { type: boolean }
+        mergeRequired: { type: boolean }
+        urgent: { type: boolean }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     PageMetadata:
       type: object
       required: [page, size, total, pages]
@@ -2090,7 +2412,7 @@ components:
           properties: { records: { type: array, items: { $ref: '#/components/schemas/InboundPlanSummary' } } }
     InboundPlanSummary:
       type: object
-      required: [lineId, planId, planNo, customerId, orderId, inboundCode, packageCount, pickedPackageCount, palletCount, status, createdAt, version]
+      required: [lineId, planId, planNo, customerId, orderId, inboundCode, overseasWarehouseCode, overseasWarehouseName, packageCount, pickedPackageCount, palletCount, status, createdAt, version]
       properties:
         lineId: { type: string, pattern: '^[0-9]+$' }
         planId: { type: string, pattern: '^[0-9]+$' }
@@ -2099,6 +2421,8 @@ components:
         orderId: { type: string, pattern: '^[0-9]+$' }
         inboundCode: { type: string }
         orderType: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, description: 接柜仓编码，取自尾程订单预分配接收仓事实 }
+        overseasWarehouseName: { type: string, description: 接柜仓名称，取自尾程订单预分配接收仓事实 }
         warehouseId: { type: string, nullable: true }
         warehouseCode: { type: string, nullable: true }
         warehouseName: { type: string, nullable: true }
@@ -2118,19 +2442,28 @@ components:
         version: { type: integer }
     InboundPlanDetail:
       type: object
-      required: [id, planNo, customerId, status, lineCount, palletCount, totalVolumeCbm, expectedPackageCount, pickedPackageCount, lines, pallets, allocations, version]
+      required: [id, planNo, customerId, overseasWarehouseCode, overseasWarehouseName, status, lineCount, palletCount, totalVolumeCbm, expectedPackageCount, pickedPackageCount, lines, pallets, allocations, version]
       properties:
         id: { type: string, pattern: '^[0-9]+$' }
         planNo: { type: string }
         customerId: { type: string }
         sourceOrderId: { type: string, pattern: '^[0-9]+$', nullable: true }
         containerNo: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, description: 接柜仓编码，取自尾程订单预分配接收仓事实 }
+        overseasWarehouseName: { type: string, description: 接柜仓名称，取自尾程订单预分配接收仓事实 }
         status: { type: string }
         lineCount: { type: integer }
         palletCount: { type: integer }
         totalVolumeCbm: { type: number }
         expectedPackageCount: { type: integer }
         pickedPackageCount: { type: integer }
+        plannedArrivalDate: { type: string, format: date, nullable: true }
+        palletType: { type: string, nullable: true }
+        assigned: { type: boolean }
+        mergeRequired: { type: boolean }
+        urgent: { type: boolean }
+        creationMode: { type: string, enum: [AUTO, MANUAL] }
+        remark: { type: string, nullable: true }
         lines: { type: array, items: { $ref: '#/components/schemas/InboundPlanLine' } }
         pallets: { type: array, items: { $ref: '#/components/schemas/InboundPlanPallet' } }
         allocations: { type: array, items: { $ref: '#/components/schemas/InboundPlanAllocation' } }
@@ -2153,6 +2486,7 @@ components:
       properties:
         id: { type: string, pattern: '^[0-9]+$' }
         palletNo: { type: string }
+        palletType: { type: string, nullable: true }
         destinationWarehouseId: { type: string, nullable: true }
         destinationWarehouseCode: { type: string, nullable: true }
         destinationWarehouseName: { type: string, nullable: true }

lastleg-service/src/main/resources/openapi/overseas-pda-operations-v1.yaml

@@ -46,6 +46,14 @@ paths:
       description: 一件代发复用统一出库任务模型；不接收customerId或warehouseId，派送不进入PDA。
       parameters: [{ name: status, in: query, required: false, schema: { type: string } }]
       responses: { '200': { description: 出库任务列表 } }
+  /api/pda/v1/last-leg/outbound-tasks/resolve/{businessNo}:
+    get:
+      summary: 解析出库作业扫码业务号
+      description: 接受一件代发任务号、出库单号或排车单号；按Token绑定仓返回 OUTBOUND 的 taskNo 或 DISPATCH 的 dispatchNo，PDA据此进入正确作业页。
+      parameters: [{ name: businessNo, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200': { description: 正确作业类型及稳定业务编号 }
+        '404': { description: 当前绑定仓无此出库或排车任务 }
   /api/pda/v1/last-leg/outbound-tasks/{taskNo}:
     get:
       summary: 查询一件代发出库任务详情
@@ -581,7 +589,7 @@ components:
             required: [outboundPalletItemId, palletNo, skuCode, inboundCode, packageCount, pickedPackageCount, status, positions]
             properties:
               outboundPalletItemId: { type: string, description: pick请求提交键，不作为用户展示编号 }
-              palletNo: { type: string }
+              palletNo: { type: string, description: Warehouse 权威实物托盘码 }
               skuCode: { type: string }
               inboundCode: { type: string }
               packageCount: { type: integer }
@@ -594,7 +602,7 @@ components:
                   required: [inventoryPositionId, palletNo, cartonMark, skuCode, inboundCode, availablePackages, pickedPackages]
                   properties:
                     inventoryPositionId: { type: string, description: pick请求提交键，不作为用户展示编号 }
-                    palletNo: { type: string }
+                    palletNo: { type: string, description: Warehouse 权威实物托盘码 }
                     cartonMark: { type: string, nullable: true }
                     skuCode: { type: string }
                     inboundCode: { type: string }