贴标申请，仓储转运

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

@@ -233,13 +233,14 @@ paths:
   /api/platform/v1/last-leg/orders/{id}:
     get:
       summary: 查询尾程订单详情
+      x-return-order-number: RETURN_RELABEL 类型的 order.orderNo 与来源退货单 returnNo 相同；创建时使用同一 RT 单号，退货关联快照 lastlegOrderNo 同步保存该号。
       description: 权限 platform:overseas-warehouse:last-mile-order:list；返回订单、货物、状态历史、费用明细和操作记录。订单中的 containerNode 来自稳定 sourceContainerBookingId 对应的柜级船节点门禁；grossWeightKg/netWeightKg 由头程冻结货物明细聚合。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: id, in: path, required: true, schema: { type: integer, format: int64 } }
         - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
       responses:
-        '200': { description: 统一 ApiResponse 包装的尾程订单详情；order.relabelApplications 返回所有换标子单的独立状态和本次数量 }
+        '200': { description: 统一 ApiResponse 包装的尾程订单详情；order.relabelApplications 返回所有换标子单的独立状态和本次数量。RETURN_RELABEL 订单另返回 returnReceipt，其结构与退货单详情相同，按订单真实客户与 sourceOrderNo 读取签收汇总和 cartons 箱内签收清点快照；其他类型 returnReceipt 为 null }
         '404': { description: 尾程订单不存在或不属于查询客户 }
   /api/platform/v1/last-leg/orders/{id}/relabel-review:
     put:
@@ -1611,7 +1612,7 @@ paths:
         '200': { description: 客户换标申请分页, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelMerchantPageResponse' } } } }
     post:
       summary: 创建客户换标申请
-      description: 权限 merchant:overseas-warehouse:relabel:create；申请创建即冻结对应库存。SKU_LABEL 不要求派送方式；CARTON_LABEL/CARTON_AND_SKU 必须指定 TRUCK、PICKUP 或 EXPRESS。
+      description: 权限 merchant:overseas-warehouse:relabel:create；申请创建即冻结对应库存。一张申请只能选择一种换标类型，所有 items.operationType 必须一致；不同类型混合提交返回业务参数错误且不冻结库存。SKU_LABEL 不要求派送方式；CARTON_LABEL/CARTON_AND_SKU 必须指定 TRUCK、PICKUP 或 EXPRESS。
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/RelabelCreate' } } } }
       responses:
@@ -1721,7 +1722,7 @@ paths:
   /api/merchant/v1/last-leg/return-orders/{returnNo}:
     get:
       summary: 客户查询退货订单与签收批次
-      description: 权限 merchant:overseas-warehouse:return-order:list；返回各 SKU 的预报和实收数量，以及每次 PDA 签收产生的批次号和可选快递单号。
+      description: 权限 merchant:overseas-warehouse:return-order:list；返回各 SKU 的预报和实收数量，以及每次 PDA 签收产生的批次号和可选快递单号。cartons 数组包含 receiptNo、palletCode、cartonMark、countStatus、countedAt、items（skuCode、productNameZh、quantity、boxCount）。CONFIRMED 为签收或清点时不可变箱内快照；PENDING 的 items 为空，不返回预分配平均数；UNRECORDED 表示历史未留存箱内快照，不能以已变化库存冒充签收数量。包裹散件不生成实物箱明细。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: returnNo, in: path, required: true, schema: { type: string } }]
       responses: { '200': { description: 当前客户退货订单详情 }, '404': { description: 当前客户下退货订单不存在 } }

lastleg-service/src/main/resources/openapi/return-carton-counting-v1.yaml

@@ -0,0 +1,93 @@
+openapi: 3.0.3
+info:
+  title: 退货托盘箱内清点
+  version: 1.0.0
+security: [{ bearerAuth: [] }]
+paths:
+  /api/pda/v1/last-leg/return-inventory/counting/current:
+    get:
+      summary: 读取当前登录操作员未完成的清点任务
+      description: 作业会话由数据库保存，退出页面或刷新不释放；只返回本人且绑定仓一致的任务。无任务data为null。
+      responses:
+        '200': { description: COUNTING任务或null }
+        '409': { description: 操作员在其他仓仍有未完成任务或原任务异常 }
+  /api/pda/v1/last-leg/return-inventory/counting/receipts/{receiptNo}/begin:
+    post:
+      summary: 弹窗确认后开始或恢复清点任务
+      description: 按操作员会话行锁和签收批次行锁串行认领，数据库保证一人一任务且一任务一人。同一操作员重复认领当前任务自然幂等；本单状态COUNTING，所有箱仍不可换标或出库。开始另一单或认领他人任务409；退出不释放。
+      parameters: [{ name: receiptNo, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200': { description: 返回COUNTING任务，允许填写真实数量 }
+        '404': { description: 任务不存在或不属于绑定仓 }
+        '409': { description: 已认领其他单、被其他人认领、无需清点或被其他作业占用 }
+  /api/pda/v1/last-leg/return-inventory/counting/scan/{code}:
+    get:
+      summary: 统一扫描箱号或托盘号读取待清点批次
+      description: 仅精确匹配登录绑定仓的箱号或托盘号，仅返回PENDING且AVAILABLE的托盘签收批次。一个托盘多次签收返回多个任务供选择。无待清点箱返回空数组，PDA显示无需清点；权限、网络或服务错误不得当作无需清点。
+      parameters: [{ name: code, in: path, required: true, schema: { type: string, maxLength: 128 } }]
+      responses:
+        '200': { description: data为清点任务数组，无待清点箱返回空数组 }
+        '400': { description: 扫码内容为空或超过128字符 }
+        '403': { description: PDA角色、权限或仓库绑定缺失 }
+  /api/pda/v1/last-leg/return-inventory/counting/tasks:
+    get:
+      summary: 分页查询绑定海外仓的待清点签收批次
+      description: 需要 lastleg:pda:operate 和 ROLE_OVERSEAS_WAREHOUSE_PDA_OPERATOR。仓库来自登录身份；托盘签收按一次签收批次整体清点，待清点箱内 quantity=0，不展示平均分配为实际数量。
+      parameters:
+        - { name: page, in: query, required: true, schema: { type: integer, minimum: 1 } }
+        - { name: size, in: query, required: true, schema: { type: integer, minimum: 1, maximum: 50 } }
+        - { name: keyword, in: query, schema: { type: string, maxLength: 128 }, description: 退货单、托盘或箱号 }
+      responses:
+        '200': { description: code=200，data 为 records/page/size/total/pages 分页信封 }
+        '403': { description: PDA角色、权限或仓库绑定缺失 }
+  /api/pda/v1/last-leg/return-inventory/counting/cartons/{cartonMark}:
+    get:
+      summary: 扫描箱号读取所属托盘签收批次及全部箱子
+      parameters: [{ name: cartonMark, in: path, required: true, schema: { type: string } }]
+      responses:
+        '200': { description: data含receiptNo/returnNo/palletCode/status/expectedItems/boxes，各箱含cartonMark/items }
+        '404': { description: 箱号不存在或不属于绑定仓，不泄露跨仓数据 }
+        '409': { description: 非托盘签收实物箱 }
+  /api/pda/v1/last-leg/return-inventory/counting/receipts/{receiptNo}:
+    post:
+      summary: 提交整个托盘签收批次的真实箱内清点
+      description: 仅本人已认领的COUNTING任务允许提交。所有实物箱各一次，同箱SKU不得重复且数量为正整数；允许不等量和混箱。各箱SKU总量必须等于签收总量。锁定操作员会话、签收批次和各箱，事务内替换明细、整批放行并释放作业会话，不改变SKU总库存。失败不释放会话。未清点箱不得合箱、换标或创建及执行退货出库。幂等键按操作员隔离，同载荷重放确认快照，不同载荷409。错误保留requestId/traceId。
+      parameters: [{ name: receiptNo, in: path, required: true, schema: { type: string } }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/Confirm' }
+      responses:
+        '200': { description: CONFIRMED清点批次，箱明细为真实数量 }
+        '400': { description: 箱号或SKU重复、非本批次、数量无效 }
+        '404': { description: 批次不存在或不属于绑定仓 }
+        '409': { description: 汇总不符、已清点、已占用或幂等键载荷冲突，事务回滚 }
+components:
+  securitySchemes:
+    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
+  schemas:
+    Confirm:
+      type: object
+      required: [idempotencyKey, boxes]
+      properties:
+        idempotencyKey: { type: string, minLength: 1, maxLength: 128 }
+        boxes:
+          type: array
+          minItems: 1
+          maxItems: 500
+          items:
+            type: object
+            required: [cartonMark, items]
+            properties:
+              cartonMark: { type: string, minLength: 1, maxLength: 128 }
+              items:
+                type: array
+                minItems: 1
+                maxItems: 100
+                items:
+                  type: object
+                  required: [skuCode, quantity]
+                  properties:
+                    skuCode: { type: string, minLength: 1, maxLength: 128 }
+                    quantity: { type: integer, format: int64, minimum: 1 }