修改提交

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

@@ -1018,8 +1018,174 @@ paths:
         - { 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/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, idempotencyKey, items]
+      properties:
+        overseasWarehouseId: { type: string, maxLength: 128 }
+        customerReferenceNo: { type: string, maxLength: 128 }
+        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, exclusiveMinimum: 0, description: '箱长，CM' }
+        width: { type: number, exclusiveMinimum: 0, description: '箱宽，CM' }
+        height: { type: number, exclusiveMinimum: 0, description: '箱高，CM' }
+        weight: { type: number, exclusiveMinimum: 0, description: '箱重，KG' }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
     InboundCodeRelationship:
       type: object
       required: [inboundCode, found, taillegOrders, inboundPlans, palletCodes, inventory]
@@ -1645,7 +1811,7 @@ components:
       required: [customerOrderNo, labelDeadline, contactName, contactPhone, chargeAmount, idempotencyKey, items]
       properties:
         customerOrderNo: { type: string, maxLength: 128 }
-        overseasWarehouseId: { type: string, nullable: true, maxLength: 128, description: 统一目的海外仓；明细未填写目的仓时使用 }
+        operationWarehouseId: { type: string, maxLength: 128, description: 换标操作所在海外中转仓，和FBA目的仓分离 }
         labelDeadline: { type: string, format: date-time }
         contactName: { type: string, maxLength: 128 }
         contactPhone: { type: string, maxLength: 64 }
@@ -1655,8 +1821,11 @@ components:
         items: { type: array, minItems: 1, maxItems: 500, items: { $ref: '#/components/schemas/RelabelItem' } }
     RelabelItem:
       type: object
-      required: [productNameZh, totalPackageCount, notifiedPackageCount, shipmentNo, newSkuCode, cartonMark, fbaCartonMark]
+      required: [sourceInventoryBalanceId, sourceInventoryPositionId, sourceInboundOrderId, productNameZh, totalPackageCount, notifiedPackageCount, shipmentNo, cartonMark]
       properties:
+        sourceInventoryBalanceId: { type: string, pattern: '^[0-9]+$', description: 来源库存余额ID }
+        sourceInventoryPositionId: { type: string, pattern: '^[0-9]+$', description: 来源库存仓位ID；同箱任务唯一冻结依据 }
+        sourceInboundOrderId: { type: string, pattern: '^[0-9]+$', description: 来源历史入仓单ID }
         skuCode: { type: string, nullable: true, maxLength: 128, description: 商品 SKU（选填） }
         productImageFileId: { type: string, nullable: true, maxLength: 128 }
         productImageFileName: { type: string, nullable: true, maxLength: 255 }
@@ -1666,14 +1835,24 @@ components:
         notifiedPackageCount: { type: integer, minimum: 1 }
         shipmentNo: { type: string, maxLength: 128 }
         trackingCode: { type: string, nullable: true, maxLength: 255 }
-        newSkuCode: { type: string, maxLength: 128 }
+        newSkuCode: { type: string, nullable: true, maxLength: 128, description: 箱唛换标时的单个新SKU兼容字段 }
         labelRequirement: { type: string, nullable: true, maxLength: 1000 }
         relabelFileId: { type: string, nullable: true, maxLength: 128 }
         relabelFileName: { type: string, nullable: true, maxLength: 255 }
         relabelFileUrl: { type: string, nullable: true, maxLength: 1000 }
-        cartonMark: { type: string, maxLength: 255, description: 客户自有箱唛（不在编辑列表展示） }
-        fbaCartonMark: { type: string, maxLength: 255, description: 关联 FBA 箱唛 }
-        destinationWarehouseId: { type: string, nullable: true, maxLength: 128, description: 该箱目的海外仓；为空时使用申请统一目的仓 }
+        cartonMark: { type: string, maxLength: 255, description: 我方箱唛；同一申请内不可重复，整箱库存只冻结一次 }
+        fbaCartonMark: { type: string, nullable: true, maxLength: 255, description: 新FBA箱唛；箱唛或组合换标必填 }
+        destinationFbaWarehouseCode: { type: string, nullable: true, maxLength: 128, description: FBA目的仓编码；箱唛或组合换标必填 }
+        operationType: { type: string, enum: [CARTON_LABEL, SKU_LABEL, CARTON_AND_SKU], description: 箱唛换标、SKU换标或组合换标 }
+        skuItems: { type: array, maxItems: 100, description: 同一箱唛内SKU换标子明细，数量按件；SKU或组合换标必填, items: { $ref: '#/components/schemas/RelabelSkuItem' } }
+    RelabelSkuItem:
+      type: object
+      required: [skuCode, newSkuCode, quantity]
+      properties:
+        skuCode: { type: string, maxLength: 128, description: 原SKU }
+        newSkuCode: { type: string, maxLength: 128, description: 换标后SKU }
+        quantity: { type: integer, minimum: 1, description: 换标件数 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     RelabelStatusChange:
       type: object
       required: [status]

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

@@ -185,7 +185,7 @@ paths:
       responses: { '200': { description: 已认领任务, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelDetailResponse' } } } }, '409': { description: 仓库、状态或幂等冲突 } }
   /api/pda/v1/last-leg/relabel-tasks/{relabelNo}/units:
     post:
-      summary: 登记一件正常换标事实
+      summary: 扫描我方箱唛并登记整箱正常换标事实；可只传oldLabel由服务端定位箱唛任务
       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: 旧标重复、新标不符或版本冲突 } }
@@ -485,10 +485,22 @@ components:
         relabelFileId: { type: string, nullable: true }
         relabelFileName: { type: string, nullable: true }
         relabelFileUrl: { type: string, nullable: true }
+        cartonMark: { type: string, nullable: true, description: 我方箱唛 }
+        fbaCartonMark: { type: string, nullable: true, description: 新FBA箱唛 }
+        operationType: { type: string, enum: [CARTON_LABEL, SKU_LABEL, CARTON_AND_SKU] }
+        skuItems: { type: array, items: { $ref: '#/components/schemas/RelabelSkuItem' } }
         expectedPackages: { type: integer }
         relabelledPackages: { type: integer }
         skippedPackages: { type: integer }
         exceptionPackages: { type: integer }
+    RelabelSkuItem:
+      type: object
+      required: [skuCode, newSkuCode, quantity]
+      properties:
+        skuCode: { type: string }
+        newSkuCode: { type: string }
+        quantity: { type: integer, description: 换标件数 }
+        remark: { type: string, nullable: true }
     RelabelUnitFact:
       type: object
       properties: