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

lastleg-service/src/main/resources/openapi/delivery-documents-v1.yaml

@@ -5,7 +5,7 @@ info:
   description: |
     所有入口只允许平台，customerId 必须为真实派送所属客户；不得按 BOL 文本查找或复用其他客户/派送单文件。
     GET /delivery-orders 及 GET /delivery-orders/{deliveryNo} 的 order 行新增 bolNo 和 documentSummary，version/allowedActions 保持原契约。
-    状态 PUT /delivery-orders/{deliveryNo}/status 请求保持 {status,expectedVersion,remark}，expectedVersion 必传。
+    RECEIPT 签收文件只有在 PUT 保存进入权威资料快照后才自动完成当前派送单；仅上传未保存不会完成。allowedActions 不再返回人工 COMPLETE_DELIVERY。
     START_DELIVERY=DELIVERING（派送中）；COMPLETE_DELIVERY=DELIVERED（完成并记录签收时间、生成待回访）。同状态重放不重复副作用。
     资料不设必传门禁，不以三类齐全作为派送完成条件。业务失败使用统一 ApiResponse（A0422参数、A0409冲突），通常HTTP200。
 security: [{ bearerAuth: [] }]

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

@@ -80,6 +80,22 @@ paths:
             application/octet-stream: { schema: { type: string, format: binary } }
         '403': { description: fileId 未绑定到当前操作员的当前柜会话三类签收照片 }
         '404': { description: 当前柜会话或照片不存在 }
+  /api/pda/v1/last-leg/receiving-containers/current/domestic-loading-photos/{evidenceType}/content:
+    get:
+      summary: 查看当前柜国内装柜照片
+      description: 权限 lastleg:pda:operate；只按当前操作员已锁定的物理柜读取国内装柜完成快照，不返回客户或内部文件ID，加载失败不改变拆柜状态。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: evidenceType, in: path, required: true, schema: { type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL] } }
+      responses:
+        '200':
+          description: 国内装柜照片字节流；禁止缓存。
+          content:
+            image/jpeg: { schema: { type: string, format: binary } }
+            image/png: { schema: { type: string, format: binary } }
+            application/octet-stream: { schema: { type: string, format: binary } }
+        '404': { description: 当前柜或指定类型照片不存在 }
+        '503': { description: 国内照片服务暂不可用 }
   /api/pda/v1/last-leg/receiving-containers/current/sign:
     post:
       summary: 签收当前柜
@@ -434,7 +450,7 @@ paths:
   /api/platform/v1/last-leg/inbound-plans/manual:
     post:
       summary: 平台按单票手工生成入库计划
-      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、暂扣状态、真实入仓码、客户归属及有效公共接柜仓。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
+      description: 权限 platform:overseas-warehouse:inbound-order:create；按 customerId 与 orderId 锁定单票，校验订单版本、状态、暂扣状态、真实入仓码、客户归属及有效公共接柜仓。预计到仓日期由服务端锁定读取来源柜全部订单的 estimatedWarehouseAt，缺失或同柜不一致时拒绝生成，不接受调用方提交。一次只生成当前票的独立计划，不改变同柜其他订单；命令原子且幂等。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
@@ -446,7 +462,7 @@ paths:
       responses:
         '200': { description: 统一 ApiResponse 包装的入库计划详情 }
         '400': { description: 客户、入仓码、仓库主数据或请求字段无效 }
-        '409': { description: 订单版本、状态、暂扣状态、重复计划或幂等键冲突 }
+        '409': { description: 订单版本、状态、暂扣状态、柜级预计到仓时间、重复计划或幂等键冲突 }
   /api/platform/v1/last-leg/inbound-plans/convert-container:
     post:
       summary: 按整柜批量生成剩余入库计划
@@ -620,11 +636,11 @@ paths:
   /api/platform/v1/last-leg/dispatches/{dispatchNo}/transfer-delivery:
     post:
       summary: 排车转出库与派送单
-      description: 权限 platform:overseas-warehouse:dispatch:transfer-delivery；只按全局唯一 dispatchNo 锁定记录并从记录解析客户范围，不接收 customerId；同一幂等键或已转换排车重复调用返回既有单据。
+      description: 权限 platform:overseas-warehouse:dispatch:transfer-delivery；只按全局唯一 dispatchNo 锁定记录并从记录解析客户范围，不接收 customerId；一个排车仍生成一张出库单，并按目的FBA仓分别生成派送单，返回 deliveries 数组；同一幂等键或已转换排车重复调用返回全部既有单据。派送费用只发布一次，避免按拆分派送单重复计费。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: dispatchNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryTransfer' } } } }
-      responses: { '200': { description: 出库与派送单转换结果 }, '404': { description: 排车单不存在 }, '409': { description: 状态、托盘或幂等冲突 } }
+      responses: { '200': { description: 一张出库单与按目的FBA仓拆分的派送单转换结果 }, '404': { description: 排车单不存在 }, '409': { description: 状态、托盘、目的FBA仓或幂等冲突 } }
   /api/platform/v1/last-leg/outbound-orders:
     get:
       summary: 分页查询出库单
@@ -649,10 +665,10 @@ paths:
   /api/platform/v1/last-leg/outbound-orders/one-click-dropship/candidates:
     get:
       summary: 查询一件代发出库候选库存
-      description: 权限 platform:overseas-warehouse:outbound:create；按客户及可选海外仓一次查询服务端权威候选，仅返回 ACTIVE 一件代发档案、OCCUPIED 正可用库存、AVAILABLE 箱唛与 SKU 余额共同覆盖且未被排车、转仓或待执行出库占用的维度。创建命令会再次校验，不信任前端候选快照。
+      description: 权限 platform:overseas-warehouse:outbound:create；仅平台身份可查询，customerId 为可选客户筛选条件，未传时跨客户查询，可按海外仓筛选。仅返回 ACTIVE 一件代发档案、OCCUPIED 正可用库存、AVAILABLE 箱唛与 SKU 余额共同覆盖且未被排车、转仓或待执行出库占用的维度。创建命令仍必须指定唯一客户并再次校验客户与仓库，不信任前端候选快照。
       security: [{ bearerAuth: [] }]
       parameters:
-        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
         - { name: warehouseId, in: query, required: false, schema: { type: string } }
       responses:
         '200':
@@ -664,7 +680,7 @@ paths:
       description: 权限 platform:overseas-warehouse:outbound:list；只按全局唯一 outboundNo 定位并从记录解析客户范围，不接收 customerId。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: outboundNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: '出库单、出库托盘及关联派送单详情；一件代发等独立出库无派送单时 delivery 为 null，排车转派送必须存在派送单；pallets[].palletNo 为 Warehouse 权威实物托盘码' }, '404': { description: 出库单不存在 } }
+      responses: { '200': { description: '出库单、出库托盘及关联 deliveries 派送单数组；一件代发等独立出库时数组为空，排车转派送按目的FBA仓返回一项或多项；pallets[].palletNo 为 Warehouse 权威实物托盘码' }, '404': { description: 出库单不存在 } }
   /api/platform/v1/last-leg/outbound-orders/{outboundNo}/cancel:
     post:
       summary: 取消未执行出库单
@@ -676,7 +692,7 @@ paths:
   /api/platform/v1/last-leg/delivery-orders:
     get:
       summary: 分页查询平台派送单
-      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。每行返回服务端计算的 allowedActions，页面不得自行推导状态门禁。
+      description: 权限 platform:overseas-warehouse:delivery:list；customerId 仅为可选平台筛选条件。同一排车按目的FBA仓显示为不同派送单，每行返回目的仓快照和服务端计算的 allowedActions，页面不得自行推导状态门禁；完成动作不再由人工触发。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 派送单分页 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}:
@@ -685,7 +701,7 @@ paths:
       description: 权限 platform:overseas-warehouse:delivery:list；列表权限包含详情只读；order.allowedActions 为当前可执行动作。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      responses: { '200': { description: 派送单详情 }, '404': { description: 派送单不存在 } }
+      responses: { '200': { description: 派送单详情，SKU与BOL打印数据只包含当前派送单目的FBA仓 }, '404': { description: 派送单不存在 } }
   /api/platform/v1/last-leg/exception-orders:
     get:
       summary: 分页查询异常订单
@@ -762,18 +778,10 @@ paths:
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryMarkReturn' } } } }
       responses: { '200': { description: 已创建退回异常单 } }
-  /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/complete:
-    post:
-      summary: 标记派送完成并生成回访记录
-      description: 权限 platform:overseas-warehouse:delivery:status。仅 WAIT_DELIVERY/DELIVERING 可完成；DELIVERED 同状态重放成功，其他终态或倒退返回 409。
-      security: [{ bearerAuth: [] }]
-      parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
-      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
-      responses: { '200': { description: 派送状态与回访记录 }, '409': { description: 版本或状态冲突 } }
   /api/platform/v1/last-leg/delivery-orders/{deliveryNo}/status:
     put:
       summary: 更新派送状态
-      description: 权限 platform:overseas-warehouse:delivery:status。只允许 WAIT_DELIVERY→DELIVERING/DELIVERED/REJECTED/CANCELLED、DELIVERING→DELIVERED/REJECTED；同状态幂等，终态不可倒退。
+      description: 权限 platform:overseas-warehouse:delivery:status。人工只允许 WAIT_DELIVERY→DELIVERING/REJECTED/CANCELLED、DELIVERING→REJECTED；DELIVERED 仅由签收资料保存成功自动触发，同状态幂等，终态不可倒退。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: deliveryNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/DeliveryStatusChange' } } } }
@@ -1949,7 +1957,7 @@ components:
         currentAccount: { type: boolean }
     ReceivingSession:
       type: object
-      required: [containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, hasDifference, inbounds]
+      required: [containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, status, version, photos, domesticLoadingPhotos, totalPackages, receivedPackages, pendingPackages, hasDifference, inbounds]
       properties:
         containerNo: { type: string }
         overseasWarehouseId: { type: string, pattern: '^\d+$', description: 平台预分配并与PDA Token匹配的海外接柜仓ID }
@@ -1959,6 +1967,7 @@ components:
         operatorName: { type: string, nullable: true }
         version: { type: integer }
         photos: { type: array, maxItems: 3, items: { $ref: '#/components/schemas/ReceivingSignedSessionPhoto' } }
+        domesticLoadingPhotos: { type: array, maxItems: 5, items: { $ref: '#/components/schemas/DomesticLoadingPhoto' }, description: 当前物理柜国内装柜五类只读照片，不含客户信息与内部文件ID }
         preparedAt: { type: string, format: date-time, nullable: true }
         signedAt: { type: string, format: date-time, nullable: true }
         receivingAt: { type: string, format: date-time, nullable: true }
@@ -1976,6 +1985,13 @@ components:
         fileName: { type: string }
         contentType: { type: string }
         sizeBytes: { type: integer, format: int64 }
+    DomesticLoadingPhoto:
+      type: object
+      required: [evidenceType, label, downloadPath]
+      properties:
+        evidenceType: { type: string, enum: [PHOTO_STEP_1, PHOTO_STEP_2, PHOTO_STEP_3, PHOTO_STEP_4, SEAL] }
+        label: { type: string, enum: [空仓, 半仓, 满仓, 锁仓, 带锁码] }
+        downloadPath: { type: string, description: 当前接柜会话鉴权下载路径 }
     ReceivingCartonResolved:
       allOf:
         - { $ref: '#/components/schemas/ReceivingInbound' }
@@ -2097,7 +2113,6 @@ components:
       required: [planPalletIds]
       properties:
         planPalletIds: { type: array, minItems: 1, maxItems: 500, uniqueItems: true, items: { type: string } }
-        route: { type: string, nullable: true, maxLength: 255 }
         fbaAppointmentNo: { type: string, nullable: true, maxLength: 64 }
         fbaAppointmentStatus: { type: string, nullable: true, maxLength: 32, default: PENDING }
         vehicleAppointmentStatus: { type: string, nullable: true, maxLength: 32, default: PENDING }
@@ -2126,7 +2141,7 @@ components:
       required: [draftToken, capacity]
       properties:
         draftToken: { type: string, minLength: 1, maxLength: 64 }
-        capacity: { type: integer, minimum: 1, maximum: 500 }
+        capacity: { type: integer, enum: [15, 30] }
     SmartDispatchDraft:
       type: object
       required: [draftToken, containers]
@@ -2144,13 +2159,12 @@ components:
         palletIds: { type: array, items: { type: string } }
     DispatchUpdate:
       type: object
-      description: 普通编辑字段；不包含 status 或 departAt。
+      description: 普通编辑字段；不包含 status、departAt 或路线，路线由已排托盘关联的 FBA 仓自动汇总。
       properties:
         vehiclePlate: { type: string, nullable: true, maxLength: 64 }
         driverName: { type: string, nullable: true, maxLength: 128 }
         driverPhone: { type: string, nullable: true, maxLength: 64 }
         carrierName: { type: string, nullable: true, maxLength: 255 }
-        route: { type: string, nullable: true, maxLength: 255 }
         fbaAppointmentNo: { type: string, nullable: true, maxLength: 64 }
         fbaAppointmentStatus: { type: string, nullable: true, maxLength: 32 }
         vehicleAppointmentStatus: { type: string, nullable: true, maxLength: 32 }
@@ -2167,7 +2181,7 @@ components:
         pickupMethod: { type: string, maxLength: 64 }
         loadingType: { type: string, maxLength: 64 }
         vehicleType: { type: string, nullable: true, maxLength: 64 }
-        vehicleSize: { type: string, nullable: true, maxLength: 64 }
+        vehicleSize: { type: string, nullable: true, enum: [15托, 30托] }
         driverName: { type: string, nullable: true, maxLength: 128 }
         driverPhone: { type: string, nullable: true, maxLength: 64 }
         vehiclePlate: { type: string, nullable: true, maxLength: 64 }
@@ -2179,13 +2193,13 @@ components:
       type: object
       required: [status, expectedVersion]
       properties:
-        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, DELIVERED, REJECTED, CANCELLED] }
+        status: { type: string, enum: [WAIT_DELIVERY, DELIVERING, REJECTED, CANCELLED] }
         expectedVersion: { type: integer, format: int64, minimum: 0 }
         remark: { type: string, nullable: true, maxLength: 500 }
     DeliveryAllowedAction:
       type: string
-      enum: [START_DELIVERY, COMPLETE_DELIVERY, REJECT_DELIVERY, CANCEL_DELIVERY, MARK_RETURN]
-      description: START/COMPLETE/REJECT/CANCEL 使用通用 status 接口；MARK_RETURN 使用 mark-return 接口。
+      enum: [START_DELIVERY, REJECT_DELIVERY, CANCEL_DELIVERY, MARK_RETURN]
+      description: START/REJECT/CANCEL 使用通用 status 接口；MARK_RETURN 使用 mark-return 接口；派送完成由签收资料保存成功自动触发。
     DeliveryMarkReturn:
       type: object
       required: [inboundOrderId, reason, returnDirection, items, idempotencyKey]
@@ -2266,6 +2280,7 @@ components:
         remark: { type: string, nullable: true, maxLength: 500 }
     OneClickOutboundCreate:
       type: object
+      description: 同一幂等键只重放相同请求；收件人、明细、箱唛或备注变化返回 A0409。
       required: [recipient, items, idempotencyKey]
       properties:
         recipient: { type: string, maxLength: 1000 }
@@ -2282,6 +2297,11 @@ components:
               inventoryPositionId: { type: string, pattern: '^[1-9][0-9]*$' }
               packages: { type: integer, format: int64, minimum: 1 }
               sku: { type: string, maxLength: 128 }
+              cartonMarks:
+                type: array
+                maxItems: 200
+                description: 指定出库箱唛，提供时必须唯一且与箱数一致。
+                items: { type: string, minLength: 1, maxLength: 128 }
     OneClickOutboundCandidate:
       type: object
       required: [inventoryPositionId, overseasWarehouseId, palletNo, skuCode, availablePackages]
@@ -2608,13 +2628,12 @@ components:
           items: { $ref: '#/components/schemas/LastlegOrderManualNode' }
     ManualInboundPlanRequest:
       type: object
-      description: 单票人工计划只能使用所属柜已冻结的接柜仓；接柜仓变更必须通过柜级接口完成。
-      required: [customerId, orderId, expectedOrderVersion, plannedArrivalDate, palletCount, palletType, assigned, mergeRequired, urgent]
+      description: 单票人工计划只能使用所属柜已冻结的接柜仓；接柜仓变更必须通过柜级接口完成。预计到仓日期由服务端读取来源柜冻结的 estimatedWarehouseArrivalAt，同柜所有计划保持一致，不接受人工提交。
+      required: [customerId, orderId, expectedOrderVersion, palletCount, palletType, assigned, mergeRequired, urgent]
       properties:
         customerId: { type: string, pattern: '^[1-9][0-9]*$' }
         orderId: { type: integer, format: int64, minimum: 1 }
         expectedOrderVersion: { type: integer, minimum: 0 }
-        plannedArrivalDate: { type: string, format: date }
         palletCount: { type: integer, minimum: 1, maximum: 999 }
         palletType: { type: string, minLength: 1, maxLength: 64 }
         assigned: { type: boolean }
@@ -2704,7 +2723,7 @@ components:
         transportType: { type: string, nullable: true }
         origin: { type: string }
         destination: { type: string }
-        containerType: { type: string, nullable: true }
+        containerType: { type: string, enum: [40GP, 40HQ, 45HQ], description: 平台统一柜型 }
         palletCount: { type: integer }
         packageCount: { type: integer }
         receivedPalletCount: { type: integer }
@@ -2760,7 +2779,7 @@ components:
         transportType: { type: string }
         origin: { type: string }
         destination: { type: string }
-        containerType: { type: string, nullable: true }
+        containerType: { type: string, enum: [40GP, 40HQ, 45HQ], description: 平台统一柜型 }
         packageCount: { type: integer }
         totalWeightKg: { type: number }
         totalVolumeCbm: { type: number }
@@ -3101,7 +3120,7 @@ components:
         originAddress: { type: string, nullable: true, maxLength: 500 }
         destination: { type: string, maxLength: 255 }
         destinationAddress: { type: string, nullable: true, maxLength: 500 }
-        containerType: { type: string, nullable: true, maxLength: 32 }
+        containerType: { type: string, enum: [40GP, 40HQ, 45HQ], default: 40HQ, maxLength: 32 }
         palletCount: { type: integer, minimum: 1 }
         packageCount: { type: integer, nullable: true, minimum: 0 }
         totalWeightKg: { type: number, minimum: 0 }
@@ -3123,7 +3142,7 @@ components:
         originAddress: { type: string, nullable: true, maxLength: 500 }
         destination: { type: string, maxLength: 255 }
         destinationAddress: { type: string, nullable: true, maxLength: 500 }
-        containerType: { type: string, nullable: true, maxLength: 32 }
+        containerType: { type: string, enum: [40GP, 40HQ, 45HQ], maxLength: 32 }
         palletCount: { type: integer, minimum: 1 }
         packageCount: { type: integer, minimum: 0 }
         totalWeightKg: { type: number, minimum: 0 }
@@ -3154,7 +3173,7 @@ components:
         originAddress: { type: string, nullable: true, maxLength: 500 }
         destination: { type: string, maxLength: 255 }
         destinationAddress: { type: string, nullable: true, maxLength: 500 }
-        containerType: { type: string, nullable: true, maxLength: 32 }
+        containerType: { type: string, enum: [40GP, 40HQ, 45HQ], default: 40HQ, maxLength: 32 }
         packageCount: { type: integer, minimum: 0 }
         totalWeightKg: { type: number, minimum: 0 }
         totalVolumeCbm: { type: number, minimum: 0 }
@@ -3177,7 +3196,7 @@ components:
         originAddress: { type: string, nullable: true, maxLength: 500 }
         destination: { type: string, maxLength: 255 }
         destinationAddress: { type: string, nullable: true, maxLength: 500 }
-        containerType: { type: string, nullable: true, maxLength: 32 }
+        containerType: { type: string, enum: [40GP, 40HQ, 45HQ], maxLength: 32 }
         packageCount: { type: integer, minimum: 0 }
         totalWeightKg: { type: number, minimum: 0 }
         totalVolumeCbm: { type: number, minimum: 0 }

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

@@ -603,6 +603,11 @@ components:
         inventoryPositionId: { type: string, pattern: '^[0-9]+$' }
         packages: { type: integer, format: int64, minimum: 1 }
         idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        cartonMarks:
+          type: array
+          maxItems: 500
+          description: 本次实际扫描的箱唛。一件代发指定箱唛任务分批拣货时必须提交本次子集，数量与 packages 一致；换标任务仍须提交全部指定箱唛。
+          items: { type: string, minLength: 1, maxLength: 255 }
     PdaOutboundTaskDetail:
       type: object
       required: [task, items]