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

# Conflicts: # lastleg-service/src/main/resources/openapi/overseas-business-v1.yaml
2026-10-09 16:13:28 +08:00
parent 3b5454fb99 bac7e0b214
commit c1aaaf207a
39 changed files with 990 additions and 53 deletions
@@ -3160,3 +3160,37 @@ SET @return_outbound_ddl = IF(EXISTS(SELECT 1 FROM information_schema.columns WH
 PREPARE return_outbound_stmt FROM @return_outbound_ddl;
 EXECUTE return_outbound_stmt;
 DEALLOCATE PREPARE return_outbound_stmt;
+
+-- 退货托盘签收箱内清点；MySQL 8；仅在目标尾程库执行，可重复运行。
+USE baiyue_lastleg;
+SET @rc_count_ddl = IF(EXISTS(SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_return_inventory_carton' AND column_name='count_status'),'SELECT 1','ALTER TABLE ll_return_inventory_carton ADD COLUMN count_status VARCHAR(16) NOT NULL DEFAULT ''CONFIRMED'' COMMENT ''箱内清点状态 PENDING待清点 CONFIRMED已确认''');
+PREPARE rc_count_stmt FROM @rc_count_ddl; EXECUTE rc_count_stmt; DEALLOCATE PREPARE rc_count_stmt;
+SET @rc_count_ddl = IF(EXISTS(SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_return_inventory_carton' AND column_name='counted_at'),'SELECT 1','ALTER TABLE ll_return_inventory_carton ADD COLUMN counted_at DATETIME(3) NULL COMMENT ''箱内清点确认时间''');
+PREPARE rc_count_stmt FROM @rc_count_ddl; EXECUTE rc_count_stmt; DEALLOCATE PREPARE rc_count_stmt;
+SET @rc_count_ddl = IF(EXISTS(SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_return_inventory_carton' AND column_name='counted_by'),'SELECT 1','ALTER TABLE ll_return_inventory_carton ADD COLUMN counted_by VARCHAR(128) NULL COMMENT ''箱内清点确认操作人''');
+PREPARE rc_count_stmt FROM @rc_count_ddl; EXECUTE rc_count_stmt; DEALLOCATE PREPARE rc_count_stmt;
+SET @rc_count_ddl = IF(EXISTS(SELECT 1 FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='ll_return_inventory_carton' AND index_name='idx_ll_return_count'),'SELECT 1','CREATE INDEX idx_ll_return_count ON ll_return_inventory_carton(overseas_warehouse_id,count_status,status,source_receipt_id)');
+PREPARE rc_count_stmt FROM @rc_count_ddl; EXECUTE rc_count_stmt; DEALLOCATE PREPARE rc_count_stmt;
+-- 历史箱：只迁移整批仍可用、没有换标/合箱占用、未确认清点的托盘签收箱。
+-- 已进入履约或合箱的批次不回退；后续需要逐批人工核实。
+UPDATE ll_return_inventory_carton c
+JOIN (SELECT source_receipt_id FROM (SELECT a.source_receipt_id
+      FROM ll_return_inventory_carton a WHERE a.source_receipt_id IS NOT NULL AND a.source_unit_type='PALLET'
+      GROUP BY a.source_receipt_id
+      HAVING SUM(a.status<>'AVAILABLE' OR a.relabel_application_id IS NOT NULL OR a.relabel_no IS NOT NULL OR a.counted_at IS NOT NULL)=0
+      AND SUM(EXISTS(SELECT 1 FROM ll_return_inventory_carton_item i WHERE i.carton_id=a.id AND COALESCE(i.packing_reserved_quantity,0)>0))=0
+      AND SUM(EXISTS(SELECT 1 FROM ll_return_packing_trace t WHERE t.source_carton_mark=a.carton_mark OR t.target_carton_mark=a.carton_mark))=0
+) pending) p ON p.source_receipt_id=c.source_receipt_id
+SET c.count_status='PENDING' WHERE c.source_unit_type='PALLET' AND c.counted_at IS NULL;
+
+-- 退货箱内清点作业会话：每位操作员只能认领一个批次，每个批次只能被一人认领。
+CREATE TABLE IF NOT EXISTS ll_return_carton_count_session (
+  operator_id VARCHAR(128) NOT NULL COMMENT '平台PDA操作员标识',
+  warehouse_id VARCHAR(128) NOT NULL COMMENT '认领时绑定海外仓标识',
+  receipt_id BIGINT NULL COMMENT '正在清点的签收批次，完成后释放为NULL',
+  started_at DATETIME(3) NULL COMMENT '本次开始清点时间',
+  created_at DATETIME(3) NOT NULL COMMENT '会话创建时间',
+  updated_at DATETIME(3) NOT NULL COMMENT '会话更新时间',
+  PRIMARY KEY(operator_id),
+  UNIQUE KEY uk_ll_return_count_session_receipt(receipt_id)
+) ENGINE=InnoDB COMMENT='退货箱内清点单人单任务持久会话';
@@ -236,13 +236,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 由头程冻结货物明细聚合。businessSource 返回 businessType、label、businessOrderNo、externalBookingNo；商业类型优先取同客户同尾程单的池来源桥，独立散板取自身来源单号，普通转运不推断为散板。orderType 保留履约类型；无关联单号为空。
      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:
@@ -1617,7 +1618,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:
@@ -1727,7 +1728,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: 当前客户下退货订单不存在 } }
@@ -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 }