Merge branch 'test' of http://8.163.30.128:10082/java-project/baiyue-firstleg into test

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

@@ -126,21 +126,21 @@ paths:
   /api/pda/v1/last-leg/receiving-containers/current/receipts/bulk:
     post:
       summary: FBA 入仓码按箱数收货
-      description: 权限 lastleg:pda:operate；只允许普通 FBA。packageCount 是该托现场累计箱数，服务端按当前柜+FBA目的仓稳定分摊到全部关联入仓码；超出计划部分只记差异，不生成可用库存。
+      description: 权限 lastleg:pda:operate；只允许普通 FBA。packageCount 是该托现场累计箱数，单托最多 66 箱；服务端按当前柜+FBA目的仓稳定分摊到全部关联入仓码；超出计划但未超出单托上限的部分只记差异，不生成可用库存。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingBulk' } } } }
-      responses: { '200': { description: 本次与累计实收进度，超收返回 DIFFERENCE_RECORDED, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingReceiptApiResponse' } } } }, '409': { description: 非普通FBA、累计数回退、版本变化或托盘不匹配 } }
+      responses: { '200': { description: 本次与累计实收进度，超收返回 DIFFERENCE_RECORDED, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingReceiptApiResponse' } } } }, '409': { description: 非普通FBA、累计数回退、单托超过66箱、版本变化或托盘不匹配 } }
   /api/pda/v1/last-leg/receiving-containers/current/receipts/carton:
     post:
       summary: 海外仓入仓码逐箱收货
-      description: 权限 lastleg:pda:operate；只允许 destinationType=OVERSEAS，拒绝跨柜、重复箱和不匹配托盘。
+      description: 权限 lastleg:pda:operate；只允许 destinationType=OVERSEAS，单托最多 66 箱，拒绝跨柜、重复箱和不匹配托盘。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingCarton' } } } }
       responses: { '200': { description: 本次与累计实收进度, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingReceiptApiResponse' } } } }, '409': { description: FBA逐箱、跨柜、重复箱或托盘不匹配 } }
   /api/pda/v1/last-leg/receiving-containers/current/receipts/pallet:
     post:
       summary: 一件代发按完整来源托盘收货
-      description: 权限 lastleg:pda:operate；只允许 ONE_CLICK_DROPSHIP，扫描 DP 或该托任一箱码，一次接收跨客户完整 DP；所有客户事件分片清单一致且齐全后才允许收货。
+      description: 权限 lastleg:pda:operate；只允许 ONE_CLICK_DROPSHIP，扫描 DP 或该托任一箱码，一次接收跨客户完整 DP；单托最多 66 箱，所有客户事件分片清单一致且齐全后才允许收货。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingWholePallet' } } } }
       responses: { '200': { description: 本次与累计实收进度, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingReceiptApiResponse' } } } }, '404': { description: 来源托盘不属于当前柜 }, '409': { description: 非一件代发、来源托盘重复或已操作 } }
@@ -232,7 +232,7 @@ paths:
   /api/platform/v1/last-leg/orders/{id}/hold:
     put:
       summary: 设置或解除尾程订单暂扣
-      description: 权限 platform:overseas-warehouse:last-mile-order:edit；使用订单版本和 Idempotency-Key 原子写入计费标记、原因及不可变历史。已进入出库流程的订单不得新增暂扣；暂扣只作用于当前票，不影响同柜其他订单。
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；使用订单版本和 Idempotency-Key 原子写入计费标记、原因及不可变历史。仅完成入库且尚未进入出库流程的订单允许新增暂扣；解除暂扣不受该状态限制。暂扣只作用于当前票并仅阻断排车和出库，不影响入库计划或同柜其他订单。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
@@ -245,7 +245,7 @@ paths:
             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: 版本冲突、幂等键冲突、重复状态或订单已进入出库流程 }
+        '409': { description: 版本冲突、幂等键冲突、重复状态、尚未完成入库或订单已进入出库流程 }
   /api/platform/v1/last-leg/orders/{id}/manual-nodes:
     get:
       summary: 查询尾程订单人工展示节点
@@ -496,7 +496,7 @@ paths:
   /api/platform/v1/last-leg/inbound-plans/manual:
     post:
       summary: 平台按单票手工生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、暂扣状态、真实入仓码、客户归属及有效公共接柜仓。预计到仓日期由服务端锁定读取来源柜全部订单的 estimatedWarehouseAt，缺失或同柜不一致时拒绝生成，不接受调用方提交。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
+      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、真实入仓码、客户归属及有效公共接柜仓。暂扣只限制排车和出库，不阻断入库计划。预计到仓日期由服务端锁定读取来源柜全部订单的 estimatedWarehouseAt，缺失或同柜不一致时拒绝生成，不接受调用方提交。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
@@ -508,7 +508,7 @@ paths:
       responses:
         '200': { description: 统一 ApiResponse 包装的入库计划详情 }
         '400': { description: 客户、入仓码、仓库主数据或请求字段无效 }
-        '409': { description: 订单版本、状态、暂扣状态、柜级预计到仓时间、重复计划或幂等键冲突 }
+        '409': { description: 订单版本、状态、柜级预计到仓时间、重复计划或幂等键冲突 }
   /api/platform/v1/last-leg/inbound-plans/convert-container:
     post:
       summary: 按整柜批量生成剩余入库计划
@@ -959,16 +959,85 @@ paths:
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 当前客户派送单详情 }, '403': { description: 缺少客户派送查看权限 }, '404': { description: 当前客户下派送单不存在 } }
+  /api/merchant/v1/last-leg/orders:
+    get:
+      summary: 客户分页查询自己的海外尾程订单
+      description: 权限 merchant:overseas-warehouse:last-mile-order:list；列表权限包含详情只读，客户范围只取认证 Token。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 当前客户海外尾程订单分页 }, '403': { description: 缺少海外尾程订单查看权限 } }
+  /api/merchant/v1/last-leg/orders/{id}:
+    get:
+      summary: 客户查询自己的海外尾程订单详情
+      description: 权限 merchant:overseas-warehouse:last-mile-order:list；不泄露其他客户订单。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: id, in: path, required: true, schema: { type: integer, format: int64 } }]
+      responses: { '200': { description: 当前客户海外尾程订单详情 }, '403': { description: 缺少海外尾程订单查看权限 }, '404': { description: 当前客户下订单不存在 } }
+  /api/merchant/v1/last-leg/warehouse-transfers:
+    get:
+      summary: 客户分页查询自己的仓储转运单
+      description: 权限 merchant:overseas-warehouse:transfer:list；列表权限包含详情只读。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 当前客户仓储转运单分页 }, '403': { description: 缺少仓储转运查看权限 } }
+    post:
+      summary: 客户创建仓储转运单
+      description: 权限 merchant:overseas-warehouse:transfer:create；客户范围只取认证 Token。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 创建后的仓储转运单 }, '403': { description: 缺少仓储转运创建权限 }, '409': { description: 幂等、库存或状态冲突 } }
+  /api/merchant/v1/last-leg/warehouse-transfers/{transferNo}:
+    get:
+      summary: 客户查询自己的仓储转运单详情
+      description: 权限 merchant:overseas-warehouse:transfer:list；不泄露其他客户订单。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: transferNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 当前客户仓储转运单详情 }, '403': { description: 缺少仓储转运查看权限 }, '404': { description: 当前客户下转运单不存在 } }
+  /api/merchant/v1/last-leg/warehouse-transfers/{transferNo}/confirm-measurement:
+    post:
+      summary: 客户确认仓储转运实测数据
+      description: 权限 merchant:overseas-warehouse:transfer:confirm；仅当前客户满足状态门禁的转运单可确认。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: transferNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 确认后的仓储转运单 }, '403': { description: 缺少实测确认权限 }, '409': { description: 状态或版本冲突 } }
+  /api/merchant/v1/last-leg/cargo-discards:
+    get:
+      summary: 客户分页查询自己的货物废弃申请
+      description: 权限 merchant:overseas-warehouse:discard:list；列表权限包含详情和库存候选只读。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 当前客户货物废弃申请分页 }, '403': { description: 缺少货物废弃查看权限 } }
+    post:
+      summary: 客户创建货物废弃申请
+      description: 权限 merchant:overseas-warehouse:discard:create；客户范围只取认证 Token。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 创建后的货物废弃申请 }, '403': { description: 缺少货物废弃创建权限 }, '409': { description: 库存或状态冲突 } }
+  /api/merchant/v1/last-leg/cargo-discards/inventory-candidates:
+    get:
+      summary: 查询当前客户可废弃库存候选
+      description: 权限 merchant:overseas-warehouse:discard:list；候选按认证客户隔离。
+      security: [{ bearerAuth: [] }]
+      responses: { '200': { description: 可废弃库存候选 }, '403': { description: 缺少货物废弃查看权限 } }
+  /api/merchant/v1/last-leg/cargo-discards/{discardNo}:
+    get:
+      summary: 客户查询自己的货物废弃申请详情
+      description: 权限 merchant:overseas-warehouse:discard:list；不泄露其他客户申请。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: discardNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 当前客户货物废弃申请详情 }, '403': { description: 缺少货物废弃查看权限 }, '404': { description: 当前客户下申请不存在 } }
+  /api/merchant/v1/last-leg/cargo-discards/{discardNo}/cancel:
+    post:
+      summary: 客户取消自己的货物废弃申请
+      description: 权限 merchant:overseas-warehouse:discard:cancel；仅满足状态门禁的申请可取消。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: discardNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 取消后的货物废弃申请 }, '403': { description: 缺少货物废弃取消权限 }, '409': { description: 状态冲突 } }
   /api/merchant/v1/last-leg/overseas-procurements:
     post:
       summary: 客户创建海外采购订单
-      description: 权限 merchant:cross-border:procurement；客户 ID 只取认证身份且不接收 customerId；新单固定进入 PENDING_REVIEW。同幂等键同请求返回既有订单，异请求返回 A0409。
+      description: 权限 merchant:cross-border:procurement:create；客户 ID 只取认证身份且不接收 customerId；新单固定进入 PENDING_REVIEW。同幂等键同请求返回既有订单，异请求返回 A0409。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementCreate' } } } }
       responses: { '200': { description: 采购订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementDetailResponse' } } } }, '409': { description: 幂等冲突 } }
     get:
       summary: 客户分页查询自己的海外采购订单
-      description: 权限 merchant:cross-border:procurement；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:cross-border:procurement:list；客户范围只取认证 Token，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -984,14 +1053,14 @@ paths:
   /api/merchant/v1/last-leg/overseas-procurements/{orderNo}:
     get:
       summary: 客户查询自己的海外采购订单详情及流水
-      description: 权限 merchant:cross-border:procurement；列表权限包含详情只读，客户范围只取认证 Token。
+      description: 权限 merchant:cross-border:procurement:list；列表权限包含详情只读，客户范围只取认证 Token。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: orderNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 当前客户采购订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementDetailResponse' } } } }, '404': { description: 当前客户下订单不存在 } }
   /api/merchant/v1/last-leg/us-truck-orders:
     get:
       summary: 客户分页查询自己的美国本土卡订单
-      description: 权限 merchant:cross-border:domestic-trucking；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:cross-border:domestic-trucking:list；客户范围只取认证 Token，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -1005,7 +1074,7 @@ paths:
       responses: { '200': { description: 当前客户本土卡订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/TruckPageResponse' } } } } }
     post:
       summary: 客户创建美国本土卡订单
-      description: 权限 merchant:cross-border:domestic-trucking；新单固定进入 PENDING_REVIEW，客户不能调用平台审核或状态推进端点。
+      description: 权限 merchant:cross-border:domestic-trucking:create；新单固定进入 PENDING_REVIEW，客户不能调用平台审核或状态推进端点。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCreate' } } } }
       responses: { '200': { description: 本土卡订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/TruckDetailResponse' } } } }, '409': { description: 幂等冲突 } }
@@ -1013,19 +1082,19 @@ paths:
     parameters: [{ name: orderNo, in: path, required: true, schema: { type: string } }]
     get:
       summary: 客户查询自己的美国本土卡订单详情
-      description: 权限 merchant:cross-border:domestic-trucking；不泄露其他客户订单。
+      description: 权限 merchant:cross-border:domestic-trucking:list；不泄露其他客户订单。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 当前客户本土卡订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/TruckDetailResponse' } } } }, '404': { description: 当前客户下订单不存在 } }
     patch:
       summary: 客户编辑待审核的美国本土卡订单
-      description: 权限 merchant:cross-border:domestic-trucking；仅 PENDING_REVIEW 可编辑，version 必填；不能修改状态。
+      description: 权限 merchant:cross-border:domestic-trucking:edit；仅 PENDING_REVIEW 可编辑，version 必填；不能修改状态。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckUpdate' } } } }
       responses: { '200': { description: 更新后的订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/TruckDetailResponse' } } } }, '409': { description: 版本或状态冲突 } }
   /api/merchant/v1/last-leg/local-looseboard-orders:
     get:
       summary: 客户分页查询自己的本土散板订单
-      description: 权限 merchant:cross-border:pallet-shipping；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:cross-border:pallet-shipping:list；客户范围只取认证 Token，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -1039,7 +1108,7 @@ paths:
       responses: { '200': { description: 当前客户本土散板订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardPageResponse' } } } } }
     post:
       summary: 客户创建本土散板订单
-      description: 权限 merchant:cross-border:pallet-shipping；新单固定进入 PENDING_ACCEPTANCE，客户不能调用平台状态推进端点。
+      description: 权限 merchant:cross-border:pallet-shipping:create；新单固定进入 PENDING_ACCEPTANCE，客户不能调用平台状态推进端点。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardCreate' } } } }
       responses: { '200': { description: 本土散板订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardDetailResponse' } } } }, '409': { description: 幂等冲突 } }
@@ -1047,12 +1116,12 @@ paths:
     parameters: [{ name: orderNo, in: path, required: true, schema: { type: string } }]
     get:
       summary: 客户查询自己的本土散板订单详情
-      description: 权限 merchant:cross-border:pallet-shipping；不泄露其他客户订单。
+      description: 权限 merchant:cross-border:pallet-shipping:list；不泄露其他客户订单。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 当前客户本土散板订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardDetailResponse' } } } }, '404': { description: 当前客户下订单不存在 } }
     put:
       summary: 客户编辑待接单的本土散板订单
-      description: 权限 merchant:cross-border:pallet-shipping；仅 PENDING_ACCEPTANCE 可编辑，version 必填；不能修改状态。
+      description: 权限 merchant:cross-border:pallet-shipping:edit；仅 PENDING_ACCEPTANCE 可编辑，version 必填；不能修改状态。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardUpdate' } } } }
       responses: { '200': { description: 更新后的订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardDetailResponse' } } } }, '409': { description: 版本或状态冲突 } }
@@ -1310,7 +1379,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications/inventory-candidates:
     get:
       summary: 查询客户可换标库存候选
-      description: 权限 merchant:warehouse:relabel；返回当前客户在指定海外中转仓仍有可用箱数的历史入仓库存，以及仓库合箱后生成的可用退货箱库存。候选按客户 Token 隔离，不接收 customerId；inboundCode 可按入仓码、退货单号或仓库唛头模糊筛选。
+      description: 权限 merchant:overseas-warehouse:relabel:list；返回当前客户在指定海外中转仓仍有可用箱数的历史入仓库存，以及仓库合箱后生成的可用退货箱库存。候选按客户 Token 隔离，不接收 customerId；inboundCode 可按入仓码、退货单号或仓库唛头模糊筛选。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: operationWarehouseId, in: query, required: true, schema: { type: string, maxLength: 128 } }
@@ -1321,7 +1390,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications:
     get:
       summary: 分页查询客户换标申请
-      description: 权限 merchant:warehouse:relabel；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:overseas-warehouse:relabel:list；客户范围只取认证 Token，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -1337,7 +1406,7 @@ paths:
         '200': { description: 客户换标申请分页, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantPageResponse' } } } }
     post:
       summary: 创建客户换标申请
-      description: 权限 merchant:warehouse:relabel；申请创建即冻结对应库存。SKU_LABEL 不要求派送方式；CARTON_LABEL/CARTON_AND_SKU 必须指定 TRUCK、PICKUP 或 EXPRESS。
+      description: 权限 merchant:overseas-warehouse:relabel:create；申请创建即冻结对应库存。SKU_LABEL 不要求派送方式；CARTON_LABEL/CARTON_AND_SKU 必须指定 TRUCK、PICKUP 或 EXPRESS。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelCreate' } } } }
       responses:
@@ -1357,7 +1426,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications/{relabelNo}:
     get:
       summary: 查询客户换标申请详情
-      description: 权限 merchant:warehouse:relabel；客户范围只取认证 Token。
+      description: 权限 merchant:overseas-warehouse:relabel:list；客户范围只取认证 Token。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }]
       responses:
@@ -1366,7 +1435,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/shipping-label:
     post:
       summary: 上传换标快递面单
-      description: 权限 merchant:warehouse:relabel；仅 EXPRESS 且申请尚未客户确认时允许上传，文件由服务端绑定到申请单。
+      description: 权限 merchant:overseas-warehouse:relabel:files；仅 EXPRESS 且申请尚未客户确认时允许上传，文件由服务端绑定到申请单。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }]
       requestBody: { required: true, content: { multipart/form-data: { schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } } } } }
@@ -1374,10 +1443,21 @@ paths:
         '200': { description: 更新后的换标详情, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantDetailResponse' } } } }
         '400': { description: 文件类型或大小不合法 }
         '409': { description: 当前状态不允许上传 }
+  /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/files:
+    post:
+      summary: 上传客户换标总文件或明细文件
+      description: 权限 merchant:overseas-warehouse:relabel:files；文件只能绑定到当前客户的换标申请。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }
+        - { name: scope, in: query, required: true, schema: { type: string, enum: [CARTON_TOTAL, SKU_TOTAL, ITEM] } }
+        - { name: itemId, in: query, required: false, schema: { type: integer, format: int64 } }
+      requestBody: { required: true, content: { multipart/form-data: { schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } } } } }
+      responses: { '200': { description: 更新后的换标详情 }, '403': { description: 缺少换标文件维护权限 }, '409': { description: 状态或归属冲突 } }
   /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/shipping-label/{fileId}/download:
     get:
       summary: 下载换标快递面单
-      description: 权限 merchant:warehouse:relabel；仅允许下载当前申请已绑定的面单文件。
+      description: 权限 merchant:overseas-warehouse:relabel:list；仅允许下载当前申请已绑定的面单文件。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }
@@ -1388,7 +1468,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/completion-photos/{fileId}/download:
     get:
       summary: 下载换标完成照片
-      description: 权限 merchant:warehouse:relabel；仅允许下载该申请 PDA 完工证据中的照片。
+      description: 权限 merchant:overseas-warehouse:relabel:list；仅允许下载该申请 PDA 完工证据中的照片。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }
@@ -1399,7 +1479,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/confirm-completion:
     post:
       summary: 客户确认换标完成
-      description: 权限 merchant:warehouse:relabel；仅 CUSTOMER_CONFIRM_PENDING 可确认。TRUCK 进入 WAIT_PRE_DISPATCH，PICKUP/EXPRESS 幂等生成 RELABEL_OUTBOUND 出库单；EXPRESS 且要求打印面单时必须先上传面单。
+      description: 权限 merchant:overseas-warehouse:relabel:confirm；仅 CUSTOMER_CONFIRM_PENDING 可确认。TRUCK 进入 WAIT_PRE_DISPATCH，PICKUP/EXPRESS 幂等生成 RELABEL_OUTBOUND 出库单；EXPRESS 且要求打印面单时必须先上传面单。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelCustomerConfirm' } } } }
@@ -1409,7 +1489,7 @@ paths:
   /api/merchant/v1/last-leg/return-orders:
     get:
       summary: 客户分页查询退货签收订单
-      description: 客户范围只取认证 Token。可按退货单号、快递单号、SKU 和签收状态过滤；实收数量以仓库 PDA 签收为准。
+      description: 权限 merchant:overseas-warehouse:return-order:list；客户范围只取认证 Token。可按退货单号、快递单号、SKU 和签收状态过滤；实收数量以仓库 PDA 签收为准。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -1421,17 +1501,31 @@ paths:
       responses: { '200': { description: 当前客户退货订单分页 } }
     post:
       summary: 客户创建退货预报订单
-      description: 客户只预报不重复的 SKU 和预计数量，不要求提前知道快递单号；仓库 PDA 实收数量才是实际入库事实。系统退货编号由业务前缀和25位大写Base36完整随机UUID编码组成，退货单RT、签收单RR、批次RB、箱唛RC及退货主单RETU均独立生成，不编码内部ID、仓库或日期。幂等重放返回已保存的编号，不重新生成。
+      description: 权限 merchant:overseas-warehouse:return-order:create；客户只预报不重复的 SKU 和预计数量，不要求提前知道快递单号；仓库 PDA 实收数量才是实际入库事实。系统退货编号由业务前缀和25位大写Base36完整随机UUID编码组成，退货单RT、签收单RR、批次RB、箱唛RC及退货主单RETU均独立生成，不编码内部ID、仓库或日期。幂等重放返回已保存的编号，不重新生成。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReturnOrderCreate' } } } }
       responses: { '200': { description: 创建后的退货订单详情 }, '409': { description: 幂等键冲突 } }
   /api/merchant/v1/last-leg/return-orders/{returnNo}:
     get:
       summary: 客户查询退货订单与签收批次
-      description: 返回各 SKU 的预报和实收数量，以及每次 PDA 签收产生的批次号和可选快递单号。
+      description: 权限 merchant:overseas-warehouse:return-order:list；返回各 SKU 的预报和实收数量，以及每次 PDA 签收产生的批次号和可选快递单号。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: returnNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 当前客户退货订单详情 }, '404': { description: 当前客户下退货订单不存在 } }
+  /api/merchant/v1/last-leg/return-orders/{returnNo}/relabel-candidates:
+    get:
+      summary: 查询退货单可转换标候选
+      description: 权限 merchant:overseas-warehouse:return-order:relabel；只返回当前客户退货单的可转换标明细。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: returnNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 可转换标候选 }, '403': { description: 缺少退货转换标权限 }, '404': { description: 当前客户下退货单不存在 } }
+  /api/merchant/v1/last-leg/return-orders/{returnNo}/relabel:
+    post:
+      summary: 将退货库存转换为换标申请
+      description: 权限 merchant:overseas-warehouse:return-order:relabel；只能处理当前客户且满足状态门禁的退货库存。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: returnNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 创建后的换标申请 }, '403': { description: 缺少退货转换标权限 }, '409': { description: 状态、库存或幂等冲突 } }
   /api/pda/v1/last-leg/return-receipts/start:
     post:
       summary: PDA 以退件单号开始签收
@@ -1950,7 +2044,7 @@ components:
       properties:
         inboundCode: { type: string, minLength: 1 }
         palletCode: { type: string, minLength: 1 }
-        packageCount: { type: integer, minimum: 1 }
+        packageCount: { type: integer, minimum: 1, maximum: 66 }
         expectedPalletVersion: { type: integer, minimum: 0, nullable: true }
         idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
     ReceivingCarton: