Merge remote-tracking branch 'origin/dev' into dev

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

@@ -1182,14 +1182,303 @@ paths:
   /api/platform/v1/last-leg/relabel-applications/{relabelNo}/status:
     put:
       summary: 变更海外换标单状态
-      description: 权限 platform:overseas-warehouse:relabel-order:status；状态按 PENDING_PROCESSING→PROCESSING→COMPLETED/REJECTED/CANCELLED 流转。
+      description: 权限 platform:overseas-warehouse:relabel-order:status；PDA复核通过后进入CUSTOMER_CONFIRM_PENDING，客户确认后进入READY_FOR_OUTBOUND，再由排车或直接出库履约。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelStatusChange' } } } }
       responses: { '200': { description: 统一 ApiResponse 包装的换标单详情 }, '409': { description: 非法状态迁移或关联尾程单缺失 } }
+  /api/platform/v1/last-leg/relabel-applications/{relabelNo}/files:
+    post:
+      summary: 上传总换标PDF或明细换标PDF
+      description: 权限 platform:overseas-warehouse:relabel-order:create。仅PENDING_PROCESSING/PROCESSING可替换，PDF内容且不超过10MiB。客户从申请单解析，ITEM必须属于该申请单同客户。File类别分别为OVERSEAS_RELABEL_TOTAL_DOCUMENT（application.id）及OVERSEAS_RELABEL_ITEM_DOCUMENT（item.id）。成功保存File返回的资料元数据，旧资料不再允许通过当前绑定下载。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: relabelNo, in: path, required: true, schema: { type: string } }
+        - { name: scope, in: query, required: true, schema: { type: string, enum: [TOTAL, ITEM] } }
+        - { name: itemId, in: query, description: ITEM必填，TOTAL不得传入, schema: { type: integer, format: int64, minimum: 1 } }
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema: { type: object, required: [file], properties: { file: { type: string, format: binary } } }
+      responses:
+        '200': { description: 换标详情；application包含totalFileId/totalFileName/totalFileUrl，items包含relabelFileId/relabelFileName/relabelFileUrl。URL为受权下载路径，文件ID按字符串返回 }
+        '400': { description: 非PDF、超限或资料范围无效 }
+        '404': { description: 申请或明细不属于当前客户 }
+        '409': { description: 换标状态不允许修改资料 }
+  /api/platform/v1/last-leg/relabel-applications/{relabelNo}/files/{fileId}/download:
+    get:
+      summary: 读取当前绑定的换标PDF
+      description: 权限 platform:overseas-warehouse:relabel-order:list；按申请单客户、资料类别、application.id或item.id及fileId精确授权。仅当前已保存资料可读，未绑定或替换的文件拒绝。响应Cache-Control为no-store。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: relabelNo, in: path, required: true, schema: { type: string } }
+        - { name: fileId, in: path, required: true, schema: { type: integer, format: int64, minimum: 1 } }
+        - { name: scope, in: query, required: true, schema: { type: string, enum: [TOTAL, ITEM] } }
+        - { name: itemId, in: query, schema: { type: integer, format: int64, minimum: 1 } }
+      responses:
+        '200': { description: PDF字节, content: { application/pdf: { schema: { type: string, format: binary } } } }
+        '404': { description: 资料未绑定或归属不匹配 }
+  /api/merchant/v1/last-leg/relabel-applications/inventory-candidates:
+    get:
+      summary: 查询客户可换标库存候选
+      description: 权限 merchant:warehouse:relabel；仅返回当前客户在指定海外中转仓仍有可用箱数的历史入仓单和库位摘要。候选按客户 Token 隔离，不接收 customerId；inboundCode 可选精确筛选。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: operationWarehouseId, in: query, required: true, schema: { type: string, maxLength: 128 } }
+        - { name: inboundCode, in: query, required: false, schema: { type: string, maxLength: 128 } }
+      responses:
+        '200': { description: 可换标库存候选, content: { application/json: { schema: { type: object, properties: { code: { type: string, example: '200' }, data: { type: array, items: { $ref: '#/components/schemas/RelabelInventoryCandidate' } } } } } } }
+        '403': { description: 缺少客户换标权限 }
+  /api/merchant/v1/last-leg/relabel-applications:
+    get:
+      summary: 分页查询客户换标申请
+      description: 权限 merchant:warehouse:relabel；客户范围只取认证 Token，不接收 customerId。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { 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: relabelNo, in: query, schema: { type: string, maxLength: 64 } }
+        - { name: customerOrderNo, in: query, schema: { type: string, maxLength: 128 } }
+        - { name: skuCode, in: query, schema: { type: string, maxLength: 128 } }
+        - { name: status, in: query, schema: { $ref: '#/components/schemas/RelabelStatus' } }
+        - { name: overseasWarehouseId, in: query, schema: { type: string, maxLength: 128 } }
+        - { 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/RelabelMerchantPageResponse' } } } }
+    post:
+      summary: 创建客户换标申请
+      description: 权限 merchant:warehouse:relabel；申请创建即冻结对应库存。SKU_LABEL 不要求派送方式；CARTON_LABEL/CARTON_AND_SKU 必须指定 TRUCK、PICKUP 或 EXPRESS。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelCreate' } } } }
+      responses:
+        '200': { description: 换标申请详情, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantDetailResponse' } } } }
+        '409': { description: 幂等键、库存或状态冲突 }
+  /api/merchant/v1/last-leg/relabel-applications/{relabelNo}:
+    get:
+      summary: 查询客户换标申请详情
+      description: 权限 merchant:warehouse:relabel；客户范围只取认证 Token。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }]
+      responses:
+        '200': { description: 换标申请详情, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantDetailResponse' } } } }
+        '404': { description: 申请不存在或不属于当前客户 }
+  /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/shipping-label:
+    post:
+      summary: 上传换标快递面单
+      description: 权限 merchant:warehouse:relabel；仅 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 } } } } } }
+      responses:
+        '200': { description: 更新后的换标详情, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantDetailResponse' } } } }
+        '400': { description: 文件类型或大小不合法 }
+        '409': { description: 当前状态不允许上传 }
+  /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/shipping-label/{fileId}/download:
+    get:
+      summary: 下载换标快递面单
+      description: 权限 merchant:warehouse:relabel；仅允许下载当前申请已绑定的面单文件。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }
+        - { name: fileId, in: path, required: true, schema: { type: integer, format: int64, minimum: 1 } }
+      responses:
+        '200': { description: 面单文件, content: { application/pdf: { schema: { type: string, format: binary } }, image/jpeg: { schema: { type: string, format: binary } }, image/png: { schema: { type: string, format: binary } } } }
+        '404': { description: 文件未绑定或不属于当前客户 }
+  /api/merchant/v1/last-leg/relabel-applications/{relabelNo}/completion-photos/{fileId}/download:
+    get:
+      summary: 下载换标完成照片
+      description: 权限 merchant:warehouse:relabel；仅允许下载该申请 PDA 完工证据中的照片。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: relabelNo, in: path, required: true, schema: { type: string, maxLength: 64 } }
+        - { name: fileId, in: path, required: true, schema: { type: integer, format: int64, minimum: 1 } }
+      responses:
+        '200': { description: 完工照片, content: { image/jpeg: { schema: { type: string, format: binary } }, image/png: { schema: { type: string, format: binary } } } }
+        '404': { description: 照片不存在或不属于当前客户 }
+  /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 且要求打印面单时必须先上传面单。
+      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' } } } }
+      responses:
+        '200': { description: 更新后的换标详情, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantDetailResponse' } } } }
+        '409': { description: 状态、面单、库存或幂等冲突 }
+  /api/merchant/v1/last-leg/return-orders:
+    get:
+      summary: 客户分页查询退货签收订单
+      description: 客户范围只取认证 Token。可按退货单号、快递单号、SKU 和签收状态过滤；实收数量以仓库 PDA 签收为准。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { 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: returnNo, in: query, schema: { type: string } }
+        - { name: trackingNo, in: query, schema: { type: string } }
+        - { name: skuCode, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string, enum: [PENDING_RECEIPT, PARTIALLY_RECEIVED, COMPLETED] } }
+      responses: { '200': { description: 当前客户退货订单分页 } }
+    post:
+      summary: 客户创建退货预报订单
+      description: 客户只预报不重复的 SKU 和预计数量，不要求提前知道快递单号；仓库 PDA 实收数量才是实际入库事实。
+      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 签收产生的批次号和可选快递单号。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: returnNo, in: path, required: true, schema: { type: string } }]
+      responses: { '200': { description: 当前客户退货订单详情 }, '404': { description: 当前客户下退货订单不存在 } }
+  /api/pda/v1/last-leg/return-receipts/start:
+    post:
+      summary: PDA 以退件单号开始签收
+      description: 仓库先从包裹收件信息取得客户填写的退件单号。仅当前绑定仓的 PENDING_RECEIPT（待签收）和 PARTIALLY_RECEIVED（签收中）退货单可开始签收，并返回该单尚未签收的 SKU 明细。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [returnNo], properties: { returnNo: { type: string, maxLength: 128 } } } } } }
+      responses: { '200': { description: 可开始签收的退货单及未签收 SKU 明细 }, '404': { description: 当前仓没有待签收或签收中的退货单 } }
+  /api/pda/v1/last-leg/return-receipts/sku-candidates:
+    post:
+      summary: PDA 扫描 SKU 查询候选退货单
+      description: 仅查询当前 PDA 绑定仓内待签收或签收中的退货单，最多返回 50 个候选。仓库人员根据退货单号、客户和数量选择后，再调用 start 进入统一签收流程。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [skuCode], properties: { skuCode: { type: string, maxLength: 128 } } } } } }
+      responses: { '200': { description: SKU 及候选退货单列表；没有匹配时 candidates 为空数组 } }
+  /api/pda/v1/last-leg/return-receipts/confirm:
+    post:
+      summary: PDA 确认退货签收
+      description: PDA 仅能操作绑定海外仓。startedBy 记录通过退货单号或 SKU 候选进入；trackingNo 为本次包裹可选快递单号。按预报可签收数量校验、禁止超收；每次成功确认创建唯一签收单及仓储计费批次。全部预报 SKU 数量吻合时自动 COMPLETED。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReturnReceiptConfirm' } } } }
+      responses: { '200': { description: 签收结果及自动完成状态 }, '409': { description: 超收、错绑或幂等键冲突 } }
+  /api/merchant/v1/last-leg/return-inventory:
+    get:
+      summary: 客户查询退货库存
+      description: 客户范围只取认证 Token。库存按客户、海外仓、SKU 和箱号查询，数量以仓库 PDA 实收上架数量为准。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { 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: overseasWarehouseId, in: query, schema: { type: string, maxLength: 128 } }
+        - { name: skuCode, in: query, schema: { type: string, maxLength: 128 } }
+        - { name: cartonMark, in: query, schema: { type: string, maxLength: 128 } }
+      responses: { '200': { description: 当前客户退货库存分页 } }
+  /api/merchant/v1/last-leg/return-inventory/summary:
+    get:
+      summary: 客户查询退货库存 SKU 汇总
+      description: 客户范围只取认证 Token。按海外仓和 SKU 汇总 PDA 实收上架数量及可用箱数。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { 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: overseasWarehouseId, in: query, schema: { type: string, maxLength: 128 } }
+        - { name: skuCode, in: query, schema: { type: string, maxLength: 128 } }
+      responses: { '200': { description: 当前客户 SKU 汇总库存分页 } }
+  /api/merchant/v1/last-leg/return-inventory/cartons/{cartonMark}:
+    get:
+      summary: 客户查询退货箱明细
+      description: 仅返回当前客户的箱号、签收批次和箱内 SKU 数量。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: cartonMark, in: path, required: true, schema: { type: string, maxLength: 128 } }]
+      responses: { '200': { description: 当前客户退货箱明细 }, '404': { description: 当前客户下退货箱不存在 } }
+  /api/merchant/v1/last-leg/return-inventory/cartons/{cartonMark}/label:
+    get:
+      summary: 客户获取退货箱唛
+      description: 返回当前客户退货箱的可打印标签及 SKU 数量，客户可据此打印或复核箱唛。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: cartonMark, in: path, required: true, schema: { type: string, maxLength: 128 } }]
+      responses: { '200': { description: 当前客户退货箱唛 }, '404': { description: 当前客户下退货箱不存在 } }
+  /api/pda/v1/last-leg/return-inventory/cartons/merge:
+    post:
+      summary: PDA 合并退货箱
+      description: 仅当前 PDA 绑定海外仓可操作。选择同一客户的已完成退货单，按查询出的 SKU 填写本箱数量并录入箱规；系统扣减可用库存并生成合箱箱号。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReturnInventoryMerge' } } } }
+      responses: { '200': { description: 新箱号、SKU 汇总数量及可打印箱唛 }, '409': { description: 箱状态、客户或 SKU 不满足合箱条件，或幂等键冲突 } }
+  /api/pda/v1/last-leg/return-inventory/packing/orders:
+    get:
+      summary: PDA 查询可合箱退货单和 SKU 库存
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: returnNo, in: query, required: false, schema: { type: string, maxLength: 128 } }]
+      responses: { '200': { description: 当前仓已完成签收退货单及可用 SKU 数量 } }
+  /api/pda/v1/last-leg/return-inventory/cartons/{cartonMark}/label:
+    get:
+      summary: PDA 获取退货箱唛
+      description: 返回当前绑定仓退货箱的结构化数据及 100mm x 150mm 可打印 HTML，包含箱号、仓库、客户、签收批次及 SKU 数量。
+      security: [{ bearerAuth: [] }]
+      parameters: [{ name: cartonMark, in: path, required: true, schema: { type: string, maxLength: 128 } }]
+      responses: { '200': { description: 退货箱唛打印数据 }, '404': { description: 当前仓没有该退货箱 } }
 components:
   schemas:
+    ReturnOrderCreate:
+      type: object
+      required: [overseasWarehouseId, needRelabel, idempotencyKey, items]
+      properties:
+        overseasWarehouseId: { type: string, maxLength: 128 }
+        warehouseContactName: { type: string, maxLength: 128, description: 中转仓联系人快照；仓库未维护时可由客户填写 }
+        warehouseContactPhone: { type: string, maxLength: 64, description: 中转仓联系电话快照；仓库未维护时可由客户填写 }
+        customerReferenceNo: { type: string, maxLength: 128 }
+        needRelabel: { type: boolean, default: false, description: 是否需要换标 }
+        remark: { type: string, maxLength: 1000 }
+        idempotencyKey: { type: string, maxLength: 255 }
+        items:
+          type: array
+          minItems: 1
+          maxItems: 500
+          items:
+            type: object
+            required: [skuCode, expectedQuantity]
+            properties:
+              skuCode: { type: string, maxLength: 128 }
+              productNameZh: { type: string, maxLength: 255 }
+              expectedQuantity: { type: integer, minimum: 1 }
+    ReturnReceiptConfirm:
+      type: object
+      required: [returnNo, startedBy, items, idempotencyKey]
+      properties:
+        returnNo: { type: string, maxLength: 128 }
+        trackingNo: { type: string, nullable: true, maxLength: 128, description: '本次签收包裹有快递面单时扫描绑定；没有时为空' }
+        startedBy: { type: string, enum: [RETURN_NO, SKU], description: '本次通过退货单号查询或 SKU 候选开始签收' }
+        cartonMark: { type: string, nullable: true, maxLength: 128, description: PDA 实际绑定的箱号；不传时由系统生成 }
+        idempotencyKey: { type: string, maxLength: 255 }
+        items:
+          type: array
+          minItems: 1
+          maxItems: 500
+          items:
+            type: object
+            required: [skuCode, receivedQuantity]
+            properties:
+              skuCode: { type: string, maxLength: 128 }
+              receivedQuantity: { type: integer, minimum: 1 }
+    ReturnInventoryMerge:
+      type: object
+      required: [returnNos, items, length, width, height, weight, idempotencyKey]
+      properties:
+        returnNos:
+          type: array
+          minItems: 1
+          maxItems: 100
+          items: { type: string, minLength: 1, maxLength: 128 }
+        items:
+          type: array
+          minItems: 1
+          maxItems: 500
+          items:
+            type: object
+            required: [skuCode, quantity]
+            properties:
+              skuCode: { type: string, maxLength: 128 }
+              quantity: { type: integer, minimum: 1 }
+        length: { type: number, minimum: 0, exclusiveMinimum: true, description: '箱长，CM' }
+        width: { type: number, minimum: 0, exclusiveMinimum: true, description: '箱宽，CM' }
+        height: { type: number, minimum: 0, exclusiveMinimum: true, description: '箱高，CM' }
+        weight: { type: number, minimum: 0, exclusiveMinimum: true, description: '箱重，KG' }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
     InventoryBalance:
       type: object
       required: [id, customerId, totalPackages, availablePackages, holdPackages, allocatedPackages, pickedPackages, inTransitPackages, receivingPackages, procurementPackages]
@@ -1980,7 +2269,101 @@ components:
         packageCount: { type: integer }
         volumeCbm: { type: number }
         sourceStage: { type: string, enum: [PLAN, RECEIVED] }
-    RelabelStatus: { type: string, enum: [PENDING_PROCESSING, PROCESSING, COMPLETED, REJECTED, CANCELLED] }
+    RelabelStatus: { type: string, enum: [PENDING_PROCESSING, PROCESSING, CUSTOMER_CONFIRM_PENDING, READY_FOR_OUTBOUND, COMPLETED, REJECTED, CANCELLED] }
+    RelabelMerchantPageResponse:
+      allOf:
+        - { $ref: '#/components/schemas/MerchantApiResponse' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/RelabelMerchantPage' } }
+    RelabelMerchantPage:
+      type: object
+      properties:
+        page: { type: integer }
+        size: { type: integer }
+        total: { type: integer, format: int64 }
+        records: { type: array, items: { $ref: '#/components/schemas/RelabelSummary' } }
+    RelabelMerchantDetailResponse:
+      allOf:
+        - { $ref: '#/components/schemas/MerchantApiResponse' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/RelabelDetail' } }
+    RelabelSummary:
+      type: object
+      properties:
+        id: { type: string }
+        relabelNo: { type: string }
+        lastlegOrderNo: { type: string, nullable: true }
+        customerOrderNo: { type: string }
+        overseasWarehouseId: { type: string }
+        labelDeadline: { type: string, format: date-time }
+        status: { $ref: '#/components/schemas/RelabelStatus' }
+        itemCount: { type: integer }
+        totalPackageCount: { type: integer }
+        notifiedPackageCount: { type: integer }
+        deliveryMethod: { type: string, nullable: true, enum: [TRUCK, PICKUP, EXPRESS] }
+        printShippingLabel: { type: boolean }
+        shippingLabelFileId: { type: string, nullable: true }
+        fulfillmentStatus: { type: string, nullable: true, enum: [WAIT_RELABEL, WAIT_PRE_DISPATCH, READY_FOR_OUTBOUND, OUTBOUND_CREATED, COMPLETED] }
+        outboundOrderNo: { type: string, nullable: true }
+        customerConfirmedAt: { type: string, format: date-time, nullable: true }
+        createdAt: { type: string, format: date-time }
+    RelabelDetail:
+      type: object
+      properties:
+        application: { $ref: '#/components/schemas/RelabelSummary' }
+        remark: { type: string, nullable: true }
+        items: { type: array, items: { $ref: '#/components/schemas/RelabelItem' } }
+        history: { type: array, items: { $ref: '#/components/schemas/RelabelHistory' } }
+        completionEvidence: { $ref: '#/components/schemas/RelabelCompletionEvidence' }
+    RelabelHistory:
+      type: object
+      properties:
+        fromStatus: { type: string, nullable: true }
+        toStatus: { type: string }
+        operatorId: { type: string }
+        remark: { type: string, nullable: true }
+        createdAt: { type: string, format: date-time }
+    RelabelCompletionEvidence:
+      type: object
+      nullable: true
+      properties:
+        taskId: { type: string, nullable: true }
+        photoFileIds: { type: array, items: { type: string } }
+        completionRemark: { type: string, nullable: true }
+        reviewerName: { type: string, nullable: true }
+        reviewRemark: { type: string, nullable: true }
+        completedAt: { type: string, format: date-time, nullable: true }
+    RelabelInventoryCandidate:
+      type: object
+      properties:
+        inventoryBalanceId: { type: string }
+        inboundOrderId: { type: string }
+        inboundOrderNo: { type: string }
+        inboundCode: { type: string }
+        overseasWarehouseId: { type: string }
+        overseasWarehouseCode: { type: string }
+        overseasWarehouseName: { type: string }
+        destinationFbaWarehouseCode: { type: string, nullable: true }
+        destinationFbaWarehouseName: { type: string, nullable: true }
+        skuCode: { type: string, nullable: true }
+        productNameZh: { type: string }
+        availablePackages: { type: integer, format: int64 }
+        version: { type: integer, format: int64 }
+        positions: { type: array, items: { $ref: '#/components/schemas/RelabelInventoryPosition' } }
+    RelabelInventoryPosition:
+      type: object
+      properties:
+        positionId: { type: string }
+        palletNo: { type: string, nullable: true }
+        batchNo: { type: string, nullable: true }
+        warehouseLocationCode: { type: string, nullable: true }
+        availablePackages: { type: integer, format: int64 }
+    RelabelCustomerConfirm:
+      type: object
+      required: [idempotencyKey]
+      properties:
+        idempotencyKey: { type: string, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     RelabelCreate:
       type: object
       required: [customerOrderNo, labelDeadline, contactName, contactPhone, chargeAmount, idempotencyKey, items]
@@ -1993,6 +2376,8 @@ components:
         chargeAmount: { type: number, minimum: 0.01, description: 本次贴标费用（CNY） }
         remark: { type: string, nullable: true, maxLength: 1000 }
         idempotencyKey: { type: string, maxLength: 255 }
+        deliveryMethod: { type: string, nullable: true, enum: [TRUCK, EXPRESS, TRUCK_PICKUP, EXPRESS_PICKUP, PICKUP], description: 只换箱唛或SKU与箱唛同时换时必填；只换SKU时不传 }
+        printShippingLabel: { type: boolean, default: false, description: 仅快递派送可选，客户确认前必须已上传面单 }
         items: { type: array, minItems: 1, maxItems: 500, items: { $ref: '#/components/schemas/RelabelItem' } }
     RelabelItem:
       type: object

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

@@ -164,6 +164,12 @@ paths:
       summary: 将来源托盘库存拆到一个或多个目标托盘
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PalletDisassemble' } } } }
       responses: { '200': { description: 拆托结果 }, '409': { description: 库存或资源版本冲突 } }
+  /api/pda/v1/last-leg/pallet-operations/relabel-disassemble:
+    post:
+      summary: 按换标箱唛拆托并绑定目标托盘
+      description: PDA先扫描原托盘，再扫描换标单指定箱唛；服务端按换标单库存快照解析仓位，在同一事务中扣减原托盘并绑定目标托盘。目标托盘须先由仓储服务创建后扫码确认。
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelPalletDisassemble' } } } }
+      responses: { '200': { description: 箱唛级拆托绑定结果 }, '409': { description: 箱唛、库存或托盘版本冲突 } }
   /api/pda/v1/last-leg/pallet-operations/swap:
     post:
       summary: 将整托库存更换到空目标托盘
@@ -675,6 +681,16 @@ components:
         source: { $ref: '#/components/schemas/PalletExpectation' }
         targets: { type: array, minItems: 1, maxItems: 20, items: { $ref: '#/components/schemas/PalletTargetMove' } }
         reason: { type: string, maxLength: 500 }
+    RelabelPalletDisassemble:
+      type: object
+      required: [idempotencyKey, relabelNo, source, target, cartonMarks]
+      properties:
+        idempotencyKey: { type: string, maxLength: 128 }
+        relabelNo: { type: string, maxLength: 64 }
+        source: { $ref: '#/components/schemas/PalletExpectation' }
+        target: { $ref: '#/components/schemas/PalletExpectation' }
+        cartonMarks: { type: array, minItems: 1, maxItems: 500, uniqueItems: true, items: { type: string, maxLength: 255 } }
+        reason: { type: string, maxLength: 500 }
     PalletSwap:
       type: object
       required: [idempotencyKey, source, target]