贴标申请，仓储转运

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

@@ -1310,7 +1310,7 @@ paths:
   /api/merchant/v1/last-leg/relabel-applications/inventory-candidates:
     get:
       summary: 查询客户可换标库存候选
-      description: 权限 merchant:warehouse:relabel；仅返回当前客户在指定海外中转仓仍有可用箱数的历史入仓单和库位摘要。候选按客户 Token 隔离，不接收 customerId；inboundCode 可选精确筛选。
+      description: 权限 merchant:warehouse:relabel；返回当前客户在指定海外中转仓仍有可用箱数的历史入仓库存，以及仓库合箱后生成的可用退货箱库存。候选按客户 Token 隔离，不接收 customerId；inboundCode 可按入仓码、退货单号或仓库唛头模糊筛选。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: operationWarehouseId, in: query, required: true, schema: { type: string, maxLength: 128 } }
@@ -2531,6 +2531,19 @@ components:
         availablePackages: { type: integer, format: int64 }
         version: { type: integer, format: int64 }
         positions: { type: array, items: { $ref: '#/components/schemas/RelabelInventoryPosition' } }
+        sourceType: { type: string, enum: [INBOUND, RETURN_CARTON] }
+        returnCartonId: { type: string, nullable: true, description: 退货合箱库存主键；sourceType=RETURN_CARTON 时提供 }
+        cartonMark: { type: string, nullable: true, description: 仓库合箱后打印并贴箱的仓库唛头 }
+        skuItems:
+          type: array
+          description: 退货箱内 SKU 与件数
+          items:
+            type: object
+            properties:
+              skuCode: { type: string }
+              newSkuCode: { type: string, nullable: true }
+              quantity: { type: integer, minimum: 1 }
+              remark: { type: string, nullable: true }
     RelabelInventoryPosition:
       type: object
       properties:
@@ -2559,10 +2572,10 @@ components:
         remark: { type: string, nullable: true, maxLength: 1000 }
     RelabelCreate:
       type: object
-      required: [customerOrderNo, labelDeadline, contactName, contactPhone, idempotencyKey, items]
+      required: [customerOrderNo, operationWarehouseId, labelDeadline, contactName, contactPhone, idempotencyKey, items]
       properties:
         customerOrderNo: { type: string, maxLength: 128 }
-        overseasWarehouseId: { type: string, nullable: true, maxLength: 128, description: 统一目的海外仓；明细未填写目的仓时使用 }
+        operationWarehouseId: { type: string, maxLength: 128, description: 当前库存所在海外操作仓 }
         labelDeadline: { type: string, format: date-time }
         contactName: { type: string, maxLength: 128 }
         contactPhone: { type: string, maxLength: 64 }
@@ -2576,6 +2589,10 @@ components:
       type: object
       required: [productNameZh, totalPackageCount, notifiedPackageCount, shipmentNo, newSkuCode, cartonMark, fbaCartonMark]
       properties:
+        sourceInventoryBalanceId: { type: string, nullable: true, description: 普通入仓库存来源；与 returnCartonId 二选一 }
+        sourceInventoryPositionId: { type: string, nullable: true, description: 普通入仓库存仓位；与 returnCartonId 二选一 }
+        sourceInboundOrderId: { type: string, nullable: true, description: 普通入仓单；与 returnCartonId 二选一 }
+        returnCartonId: { type: string, nullable: true, description: 仓库合箱产生的退货箱库存；与普通入仓库存字段二选一 }
         skuCode: { type: string, nullable: true, maxLength: 128, description: 商品 SKU（选填） }
         productImageFileId: { type: string, nullable: true, maxLength: 128 }
         productImageFileName: { type: string, nullable: true, maxLength: 255 }

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

@@ -163,12 +163,32 @@ paths:
       summary: 扫码查询托盘及库存内容
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ScanCode' } } } }
       responses: { '200': { description: Token绑定仓托盘内容 }, '404': { description: 托盘不存在（统一响应实际 HTTP 200，body.code=A0404）, content: { application/json: { schema: { $ref: '#/components/schemas/ApiResponse' } } } } }
+  /api/pda/v1/last-leg/pallet-operations/relabel-sources:
+    post:
+      summary: 查询换标原入仓单在各托盘上的库存数量
+      description: 范围取Token冻结仓和换标单客户；返回库存组成而非历史箱唛定位。movablePackages不包括其他单据冻结、已分配或已拣货箱数。cartonMarks为同来源库存池候选，不代表这些箱历史上位于该托盘。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { type: object, required: [relabelNo], properties: { relabelNo: { type: string, maxLength: 64 } } }
+      responses:
+        '200':
+          description: 原入仓单托盘组成
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string }
+                  data: { type: array, items: { $ref: '#/components/schemas/RelabelSource' } }
+        '409': { description: 状态、认领人或仓库不符 }
   /api/pda/v1/last-leg/pallet-operations/relabel-pallet-label:
     post:
       summary: 为换标拆托幂等生成并返回可打印的新托盘标签
       description: 返回空托盘编码、初始版本和打印HTML；随后可将该托盘作为relabel-disassemble的target。库存移入后仍继承原库存余额对应的客户和入库单。
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/NewRelabelPallet' } } } }
-      responses: { '200': { description: 新托盘及可打印标签 }, '409': { description: 换标单未确认或不属于Token绑定仓 } }
+      responses: { '200': { description: 新托盘及可打印标签，已认领处理中无需客户确认即可创建 }, '409': { description: 状态、认领人或Token绑定仓不符 } }
   /api/pda/v1/last-leg/pallet-operations/assemble:
     post:
       summary: 将多个来源托盘的指定库存行组到目标托盘
@@ -182,7 +202,7 @@ paths:
   /api/pda/v1/last-leg/pallet-operations/relabel-disassemble:
     post:
       summary: 按换标箱唛拆托并绑定目标托盘
-      description: PDA先扫描原托盘，再扫描换标单指定箱唛；服务端按换标单库存快照解析仓位，在同一事务中扣减原托盘并绑定目标托盘。目标托盘须先由仓储服务创建后扫码确认。
+      description: PDA选择原入仓单库存行并扫描实际来源托盘，输入拆出箱数，核对本批cartonMarks后扫描目标托盘。传actualSource时以其数量和版本为准，同入仓余额及批次内原子调整本单冻结记账位置，再移动冻结库存和换标明细；不新增入库、不改变库存归属、不占用其他单据冻结量。每次一个来源库存行，可分批处理多个托盘。已有出库单时不允许此数量重分配。未传actualSource的箱唛模式仍要求已有来源仓位一致。
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelPalletDisassemble' } } } }
       responses: { '200': { description: 箱唛级拆托绑定结果 }, '409': { description: 箱唛、库存或托盘版本冲突 } }
   /api/pda/v1/last-leg/pallet-operations/swap:
@@ -218,6 +238,27 @@ paths:
       parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelUnit' } } } }
       responses: { '200': { description: 更新后的任务, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelDetailResponse' } } } }, '409': { description: 旧标重复、新标不符或版本冲突 } }
+  /api/pda/v1/last-leg/relabel-tasks/{relabelNo}/skus/scan:
+    post:
+      summary: 仅扫描旧SKU完成当前箱的一条SKU换标明细
+      description: itemId与skuIndex精确指定一条明细，服务端验证旧SKU并读取已批准的新SKU及件数；同旧SKU多箱由PDA选择目标，不批量隐式完成。逐条写SKU_SCAN历史并按轮次防重，全部SKU处理后完成SKU阶段，混合单仍须完成箱唛阶段。响应history包含旧新SKU、件数及索引，供提示与隐藏已处理明细。
+      parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string } }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [itemId, skuIndex, oldSku, expectedVersion, idempotencyKey]
+              properties:
+                itemId: { type: string, pattern: '^[0-9]+$' }
+                skuIndex: { type: integer, minimum: 0 }
+                oldSku: { type: string, maxLength: 255 }
+                expectedVersion: { type: integer, minimum: 0 }
+                idempotencyKey: { type: string, maxLength: 255 }
+      responses:
+        '200': { description: 更新后的任务, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelDetailResponse' } } } }
+        '409': { description: 已处理、映射不符、认领人或版本冲突 }
   /api/pda/v1/last-leg/relabel-tasks/{relabelNo}/units/skip:
     post:
       summary: 登记一件有原因的跳过事实
@@ -260,6 +301,107 @@ paths:
       parameters: [{ name: relabelNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelReview' } } } }
       responses: { '200': { description: COMPLETED或PROCESSING任务, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelDetailResponse' } } } }, '409': { description: 状态或版本冲突 } }
+  /api/pda/v1/last-leg/warehouse-transfers/candidates:
+    get:
+      summary: 查询Token绑定仓待测量的仓储转运单
+      description: 仅返回当前PDA冻结海外仓内已审核且等待测量打托的转运单；不接收customerId或warehouseId。
+      responses:
+        '200':
+          description: 待测量转运单列表
+          content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferSummaryListResponse' } } }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}:
+    get:
+      summary: 查询当前仓仓储转运测量详情
+      parameters: [{ name: transferNo, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200':
+          description: 转运申报、已生成的新托盘及测量照片；items仅为服务端自动分摊结果，PDA不提交每托SKU。
+          content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferDetailResponse' } } }
+        '404': { description: 当前Token绑定仓无此转运单 }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/measurement-photos/files:
+    get:
+      summary: 查询当前转运单已上传的测量现场照片
+      parameters: [{ name: transferNo, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200': { description: 照片元数据列表 }
+    post:
+      summary: 上传仓储转运测量现场照片
+      parameters: [{ name: transferNo, 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: 已绑定当前转运单的照片元数据 }
+        '404': { description: 当前Token绑定仓无此转运单 }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/measurement-photos/files/{fileId}/download:
+    get:
+      summary: 鉴权下载仓储转运测量现场照片
+      parameters:
+        - { name: transferNo, in: path, required: true, schema: { type: string } }
+        - { name: fileId, in: path, required: true, schema: { type: integer, format: int64 } }
+      responses:
+        '200': { description: 照片内容, content: { 'image/*': { schema: { type: string, format: binary } } } }
+        '404': { description: 照片不属于当前转运单或绑定仓 }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/palletize:
+    post:
+      summary: 完成仓储转运整单测量打托
+      description: 只提交当前转运单照片和整单幂等键；所有托盘必须已逐托生成并扫码绑定，箱数必须核平。此接口不接收测量字段、托盘码或每托SKU，也绝不再次生成托盘。
+      parameters: [{ name: transferNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferPalletize' } } } }
+      responses:
+        '200':
+          description: WAIT_CUSTOMER_CONFIRMATION详情
+          content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferDetailResponse' } } }
+        '409': { description: 状态、照片归属、箱数核平或幂等冲突 }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/pallets/drafts:
+    post:
+      summary: 新建或更新一个转运测量托盘草稿
+      description: palletId为空时创建DRAFT；传入既有DRAFT的palletId时更新。GENERATED及以后测量字段锁定，必须拒绝修改。
+      parameters: [{ name: transferNo, in: path, required: true, schema: { type: string } }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferPalletDraft' } } } }
+      responses: { '200': { description: 包含持久化草稿的最新整单详情 }, '409': { description: 草稿已生成、状态或幂等冲突 } }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/pallets/{palletId}:
+    delete:
+      summary: 删除未生成的转运托盘草稿
+      description: 只允许删除DRAFT；GENERATED、BOUND和COMPLETED不得删除。
+      parameters:
+        - { name: transferNo, in: path, required: true, schema: { type: string } }
+        - { name: palletId, in: path, required: true, schema: { type: integer, format: int64 } }
+      responses: { '200': { description: 删除后的整单详情 }, '409': { description: 本托已经生成真实托盘 } }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/pallets/{palletId}/generate:
+    post:
+      summary: 为测量草稿生成一个全新实物托盘
+      description: 只允许DRAFT调用一次；服务端始终向Warehouse Overseas传空palletCode，不能复用已有托盘。有FBA则写入目的仓，无FBA则标签显示“目的仓待定”。成功后实测字段锁定且可立即下载PDF标签。
+      parameters:
+        - { name: transferNo, in: path, required: true, schema: { type: string } }
+        - { name: palletId, in: path, required: true, schema: { type: integer, format: int64 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferPalletAction' } } } }
+      responses: { '200': { description: 包含GENERATED新托盘号和标签路径的最新详情 }, '409': { description: 已生成或资源生成冲突 } }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/pallets/{palletId}/bind:
+    post:
+      summary: 扫描并确认本托新生成的托盘码
+      description: 扫描码必须精确等于本草稿服务端生成码，同时验证Warehouse Overseas物理托盘ID和Token冻结仓一致；其他已有托盘不得冒充。
+      parameters:
+        - { name: transferNo, in: path, required: true, schema: { type: string } }
+        - { name: palletId, in: path, required: true, schema: { type: integer, format: int64 } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/WarehouseTransferPalletBind' } } } }
+      responses: { '200': { description: 包含BOUND事实和boundAt的最新详情 }, '409': { description: 扫描码、归属、仓库或状态不匹配 } }
+  /api/pda/v1/last-leg/warehouse-transfers/{transferNo}/pallets/{warehousePalletId}/label:
+    get:
+      summary: 下载仓储转运实物托盘PDF标签
+      description: 校验Token冻结仓、转运单和托盘归属后，代理Warehouse Overseas使用统一托盘标签打印服务生成真实PDF。已知FBA显示目的仓编码，未知FBA显示“目的仓待定”。
+      parameters:
+        - { name: transferNo, in: path, required: true, schema: { type: string } }
+        - { name: warehousePalletId, in: path, required: true, schema: { type: integer, format: int64 } }
+        - { name: X-Request-Id, in: header, required: false, schema: { type: string } }
+      responses:
+        '200': { description: 托盘标签PDF, content: { application/pdf: { schema: { type: string, format: binary } } } }
+        '404': { description: 转运单或托盘不属于当前Token绑定仓 }
 components:
   securitySchemes:
     bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
@@ -274,6 +416,107 @@ components:
         requestId: { type: string, nullable: true }
         traceId: { type: string, nullable: true }
         timestamp: { type: string, format: date-time, nullable: true }
+    WarehouseTransferSummaryListResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ApiResponse' }
+        - type: object
+          properties:
+            data: { type: array, items: { $ref: '#/components/schemas/WarehouseTransferSummary' } }
+    WarehouseTransferDetailResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ApiResponse' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/WarehouseTransferDetail' } }
+    WarehouseTransferSummary:
+      type: object
+      required: [id, transferNo, operatingWarehouseId, packageCount, deliveryMethod, needRelabel, status]
+      properties:
+        id: { type: integer, format: int64 }
+        transferNo: { type: string }
+        inboundCode: { type: string, nullable: true }
+        operatingWarehouseId: { type: string }
+        fbaWarehouseCode: { type: string, nullable: true, description: 为空表示目的仓待定 }
+        packageCount: { type: integer, minimum: 1 }
+        deliveryMethod: { type: string }
+        needRelabel: { type: boolean }
+        relabelNo: { type: string, nullable: true }
+        status: { type: string }
+        estimatedArrivalAt: { type: string, format: date-time, nullable: true }
+        createdAt: { type: string, format: date-time, nullable: true }
+    WarehouseTransferDetail:
+      type: object
+      required: [id, transferNo, operatingWarehouseId, packageCount, status, pallets, measurementPhotos]
+      properties:
+        id: { type: integer, format: int64 }
+        transferNo: { type: string }
+        operatingWarehouseId: { type: string }
+        fbaWarehouseCode: { type: string, nullable: true, description: 为空表示目的仓待定 }
+        pickupContactName: { type: string, nullable: true }
+        pickupContactPhone: { type: string, nullable: true }
+        packageCount: { type: integer, minimum: 1 }
+        status: { type: string }
+        pallets: { type: array, items: { $ref: '#/components/schemas/WarehouseTransferPallet' } }
+        measurementPhotos: { type: array, items: { $ref: '#/components/schemas/WarehouseTransferMeasurementPhoto' } }
+    WarehouseTransferPalletize:
+      type: object
+      required: [idempotencyKey, photoFileIds]
+      properties:
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        photoFileIds:
+          type: array
+          minItems: 1
+          maxItems: 20
+          uniqueItems: true
+          items: { type: integer, format: int64, minimum: 1 }
+    WarehouseTransferPalletDraft:
+      type: object
+      required: [idempotencyKey, cartonCount, lengthCm, widthCm, heightCm, volumeCbm, grossWeightKg]
+      properties:
+        palletId: { type: integer, format: int64, nullable: true, description: 更新现有DRAFT时传入；创建时不传 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        cartonCount: { type: integer, minimum: 1 }
+        lengthCm: { type: number, format: double, minimum: 0.01 }
+        widthCm: { type: number, format: double, minimum: 0.01 }
+        heightCm: { type: number, format: double, minimum: 0.01 }
+        volumeCbm: { type: number, format: double, minimum: 0.000001 }
+        grossWeightKg: { type: number, format: double, minimum: 0.01 }
+    WarehouseTransferPalletAction:
+      type: object
+      required: [idempotencyKey]
+      properties: { idempotencyKey: { type: string, minLength: 1, maxLength: 255 } }
+    WarehouseTransferPalletBind:
+      type: object
+      required: [palletCode, idempotencyKey]
+      properties:
+        palletCode: { type: string, minLength: 1, maxLength: 128 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+    WarehouseTransferPallet:
+      type: object
+      required: [id, sequenceNo, cartonCount, lengthCm, widthCm, heightCm, volumeCbm, grossWeightKg, status]
+      properties:
+        id: { type: integer, format: int64 }
+        sequenceNo: { type: integer, minimum: 1 }
+        warehousePalletId: { type: integer, format: int64, nullable: true }
+        palletNo: { type: string, nullable: true, description: GENERATED后由Warehouse Overseas为本次测量新生成 }
+        cartonCount: { type: integer, minimum: 1 }
+        lengthCm: { type: number, format: double }
+        widthCm: { type: number, format: double }
+        heightCm: { type: number, format: double }
+        volumeCbm: { type: number, format: double }
+        grossWeightKg: { type: number, format: double }
+        status: { type: string, enum: [DRAFT, GENERATED, BOUND, COMPLETED] }
+        fbaWarehouseCode: { type: string, nullable: true, description: 为空时标签显示目的仓待定 }
+        labelDownloadPath: { type: string, nullable: true, description: GENERATED后返回当前PDA鉴权下的真实PDF下载路径 }
+        boundAt: { type: string, format: date-time, nullable: true }
+    WarehouseTransferMeasurementPhoto:
+      type: object
+      required: [fileId, sizeBytes, uploadedAt]
+      properties:
+        fileId: { type: integer, format: int64 }
+        fileName: { type: string, nullable: true }
+        contentType: { type: string, nullable: true }
+        sizeBytes: { type: integer, format: int64, minimum: 0 }
+        uploadedAt: { type: string, format: date-time }
     StocktakeSummaryPageResponse:
       allOf:
         - { $ref: '#/components/schemas/ApiResponse' }
@@ -732,7 +975,19 @@ components:
         source: { $ref: '#/components/schemas/PalletExpectation' }
         target: { $ref: '#/components/schemas/PalletExpectation' }
         cartonMarks: { type: array, minItems: 1, maxItems: 500, uniqueItems: true, items: { type: string, maxLength: 255 } }
+        actualSource: { $ref: '#/components/schemas/PalletMoveLine' }
         reason: { type: string, maxLength: 500 }
+    RelabelSource:
+      type: object
+      properties:
+        positionId: { type: string, pattern: '^[0-9]+$' }
+        positionVersion: { type: integer, format: int64 }
+        palletCode: { type: string }
+        locationCode: { type: string, nullable: true }
+        inboundCode: { type: string }
+        stockPackages: { type: integer, format: int64 }
+        movablePackages: { type: integer, format: int64 }
+        cartonMarks: { type: array, items: { type: string } }
     PalletSwap:
       type: object
       required: [idempotencyKey, source, target]