fix: complete October 22 workflow feedback and request failure recovery

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

@@ -3229,6 +3229,13 @@ paths:
       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/cartons/merge-boxes:
+    post:
+      summary: PDA 按实物来源箱合箱
+      description: 同一客户、当前绑定仓内合箱；新请求必须携带扫码时全部来源箱 SKU 数量，在来源行锁内校验，过期返回冲突，重新扫描后操作。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReturnInventoryBoxMerge' } } } }
+      responses: { '200': { description: 合箱实物箱号与标签 }, '400': { description: 缺少或无效来源库存快照 }, '409': { description: 来源库存或资格已变化，或幂等键冲突 } }
   /api/pda/v1/last-leg/return-inventory/packing/orders:
     get:
       summary: PDA 查询可合箱退货单和 SKU 库存
@@ -3426,8 +3433,9 @@ components:
               expectedQuantity: { type: integer, minimum: 1 }
     ReturnReceiptConfirm:
       type: object
-      required: [returnNo, startedBy, items, idempotencyKey]
+      required: [returnNo, startedBy, items, idempotencyKey, expectedReceivedQuantity]
       properties:
+        expectedReceivedQuantity: { type: integer, format: int64, minimum: 0, description: '提交前退货单全部 SKU 的累计实收数量；在订单锁内校验，过期返回冲突，刷新后重新操作' }
         returnNo: { type: string, maxLength: 128 }
         trackingNo: { type: string, nullable: true, maxLength: 128, description: '本次签收包裹有快递面单时扫描绑定；没有时为空' }
         startedBy: { type: string, enum: [RETURN_NO, SKU], description: '本次通过退货单号查询或 SKU 候选开始签收' }
@@ -3450,6 +3458,39 @@ components:
               skuCode: { type: string, maxLength: 128 }
               receivedQuantity: { type: integer, minimum: 1 }
               boxCount: { type: integer, nullable: true, minimum: 1, description: 托盘或箱子签收时该 SKU 对应箱数，包裹签收不填 }
+    ReturnInventoryBoxMerge:
+      type: object
+      required: [sourceCartonMarks, idempotencyKey, expectedSourceQuantities]
+      properties:
+        sourceCartonMarks: { type: array, minItems: 1, maxItems: 100, items: { type: string } }
+        targetCartonMark: { type: string, nullable: true, description: 不填时生成新箱 }
+        idempotencyKey: { type: string, maxLength: 255 }
+        expectedSourceQuantities:
+          type: array
+          minItems: 1
+          maxItems: 1000
+          description: 扫码时全部来源箱各 SKU 的数量，必须完整且不能重复
+          items:
+            type: object
+            required: [cartonMark, skuCode, quantity]
+            properties:
+              cartonMark: { type: string }
+              skuCode: { type: string }
+              quantity: { type: integer, format: int64, minimum: 0 }
+        sourceDeductions:
+          type: array
+          maxItems: 1000
+          items:
+            type: object
+            required: [cartonMark, skuCode, quantity]
+            properties:
+              cartonMark: { type: string }
+              skuCode: { type: string }
+              quantity: { type: integer, format: int64, minimum: 1 }
+        length: { type: number, minimum: 0, exclusiveMinimum: true }
+        width: { type: number, minimum: 0, exclusiveMinimum: true }
+        height: { type: number, minimum: 0, exclusiveMinimum: true }
+        weight: { type: number, minimum: 0, exclusiveMinimum: true }
     ReturnInventoryMerge:
       type: object
       required: [returnNos, items, length, width, height, weight, idempotencyKey]
@@ -5447,7 +5488,7 @@ components:
     DispatchMaintenance:
       type: object
       x-java-record: DispatchContracts.Maintenance
-      description: 保存于排车resourcesJson.maintenance的唯一正式资料结构，不新增费用金额或审核门禁。
+      description: 保存于排车resourcesJson.maintenance；预约按本车目的仓登记，保存可暂缺，提交审核及后续执行须填写完整。
       properties:
         plannedDeliveryDate:
           type: string
@@ -5477,10 +5518,18 @@ components:
           type: string
           maxLength: 128
           nullable: true
-        appointmentNo:
-          type: string
-          maxLength: 128
-          nullable: true
+        destinationAppointments:
+          type: array
+          maxItems: 500
+          items: { $ref: '#/components/schemas/DispatchDestinationAppointment' }
+    DispatchDestinationAppointment:
+      type: object
+      x-java-record: DispatchContracts.DestinationAppointment
+      description: 同一排车同一FBA目的仓仅一个预约号，空白可暂存。
+      required: [destinationKey, appointmentNo]
+      properties:
+        destinationKey: { type: string, pattern: '^FBA:.+', maxLength: 256 }
+        appointmentNo: { type: string, maxLength: 128, nullable: true }
     DispatchResources:
       type: object
       x-java-record: DispatchContracts.Resources
@@ -6363,6 +6412,14 @@ components:
       type: object
       x-java-record: DispatchViews.ListRow
       properties:
+        createdAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: 排车单真实创建时间，取原排车主单created_at。
+        fbaAppointments:
+          type: array
+          items: { $ref: '#/components/schemas/DispatchFbaAppointment' }
         dispatchNo:
           type: string
           nullable: true
@@ -6424,6 +6481,7 @@ components:
             $ref: '#/components/schemas/DispatchGate'
           nullable: true
       required:
+      - createdAt
       - dispatchNo
       - status
       - stage
@@ -6440,6 +6498,7 @@ components:
       - pickingReconciled
       - arranged
       - actions
+      - fbaAppointments
     DispatchVehicleInfo:
       type: object
       x-java-record: DispatchViews.VehicleInfo
@@ -6463,7 +6522,14 @@ components:
     DispatchFbaAppointment:
       type: object
       x-java-record: DispatchViews.FbaAppointment
+      description: 按本车目的仓汇总的预约；唯一已约编号自动带入，人工登记不冒充正式确认时间。批次及客户在目的仓汇总行为空。
       properties:
+        customerId:
+          type: string
+          nullable: true
+        shipmentNumbers:
+          type: array
+          items: { type: string }
         batchKey:
           type: string
           nullable: true
@@ -6498,6 +6564,8 @@ components:
       - status
       - confirmedAt
       - blockReason
+      - customerId
+      - shipmentNumbers
     DispatchDispatchInfo:
       type: object
       x-java-record: DispatchViews.DispatchInfo

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

@@ -116,6 +116,7 @@ paths:
         - { name: ownership, in: query, schema: { $ref: '#/components/schemas/VehicleOwnership' } }
         - { name: region, in: query, schema: { $ref: '#/components/schemas/VehicleRegion' } }
         - { name: status, in: query, schema: { $ref: '#/components/schemas/VehicleStatus' } }
+        - { name: dispatchNo, in: query, description: 排车维护候选，分页前排除其他车次实际占用，保留本车资源, schema: { type: string, maxLength: 64 } }
       responses: { '200': { description: 业务响应，data为PageResult<Vehicle> } }
     post:
       summary: 创建车辆主数据