feat: gate overseas receiving and harden phase4 workflows

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

@@ -6,7 +6,7 @@ paths:
   /api/pda/v1/last-leg/receiving-containers/candidates:
     get:
       summary: 查询当前客户待签收柜号
-      description: 权限 lastleg:pda:operate；仅 PLATFORM WAREHOUSE_PICKER 可用，操作账号从 Token 获取，客户由所选柜业务事实唯一解析，不接收 customerId。
+      description: 权限 lastleg:pda:operate；仅 PLATFORM WAREHOUSE_PICKER 可用；仅返回已单调消费 PICKUP_READY(80) 或更高实际船节点、状态为 RECEIVING_AVAILABLE 的柜，不接收 customerId。
       security: [{ bearerAuth: [] }]
       responses: { '200': { description: 柜号候选及箱数进度, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingCandidateListApiResponse' } } } }, '403': { description: 缺少 PDA 操作权限 } }
   /api/pda/v1/last-leg/receiving-containers/{containerNo}:
@@ -19,7 +19,7 @@ paths:
   /api/pda/v1/last-leg/receiving-containers/{containerNo}/prepare:
     post:
       summary: 选择当前待签收柜号
-      description: 权限 lastleg:pda:operate；建立 WAIT_SIGN 会话并以平台操作账号、柜号全局双唯一键防止切柜或多人同时处理。
+      description: 权限 lastleg:pda:operate；仅 RECEIVING_AVAILABLE 柜可建立 WAIT_SIGN 会话，并以平台操作账号、柜号全局双唯一键防止切柜或多人同时处理。
       security: [{ bearerAuth: [] }]
       parameters: [{ name: containerNo, in: path, required: true, schema: { type: string } }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingAction' } } } }
@@ -86,6 +86,37 @@ paths:
       security: [{ bearerAuth: [] }]
       requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingAction' } } } }
       responses: { '200': { description: COMPLETED 柜号会话, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingSessionApiResponse' } } } }, '409': { description: 数量未核平或状态冲突 } }
+  /api/pda/v1/last-leg/inventory/resolve:
+    post:
+      summary: PDA按SKU、箱唛或入仓码扫码查询库存
+      description: 仅 WAREHOUSE_PICKER + lastleg:pda:operate；海外实际仓只取Token overseasWarehouseId，不接收客户或仓库参数。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PdaWarehouseScan' } } } }
+      responses: { '200': { description: 同仓跨客户库存与物理仓位事实, content: { application/json: { schema: { $ref: '#/components/schemas/PdaInventoryScanApiResponse' } } } }, '404': { description: A0404：当前绑定仓无匹配库存 } }
+  /api/pda/v1/last-leg/locations/resolve:
+    post:
+      summary: PDA查询库位容量、状态与库存占用
+      description: 库位从Warehouse Overseas公共资源解析，并强制匹配Token绑定仓。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PdaWarehouseScan' } } } }
+      responses: { '200': { description: 库位物理事实及Lastleg库存占用汇总, content: { application/json: { schema: { $ref: '#/components/schemas/PdaLocationApiResponse' } } } }, '404': { description: A0404：库位不存在或跨仓 } }
+  /api/pda/v1/last-leg/pallets/resolve:
+    post:
+      summary: PDA查询托盘、库位与绑定库存
+      description: 托盘从Warehouse Overseas公共资源解析；跨Token绑定仓返回A0409。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PdaWarehouseScan' } } } }
+      responses: { '200': { description: 托盘物理事实及Lastleg绑定库存, content: { application/json: { schema: { $ref: '#/components/schemas/PdaPalletApiResponse' } } } }, '409': { description: A0409：托盘属于其他仓 } }
+  /api/pda/v1/last-leg/operations:
+    get:
+      summary: 查询当前PDA账号真实作业历史
+      description: 返回Token绑定仓内当前操作账号的柜号作业及盘点、移库、托盘、换标历史；不含出库或派送。
+      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: operationType, in: query, schema: { type: string } }
+      responses: { '200': { description: 真实作业历史分页, content: { application/json: { schema: { $ref: '#/components/schemas/PdaOperationPageApiResponse' } } } } }
   /api/platform/v1/last-leg/orders:
     get:
       summary: 分页查询尾程订单
@@ -269,14 +300,14 @@ paths:
   /api/platform/v1/last-leg/overseas-procurements/{orderNo}/review:
     post:
       summary: 审核海外采购订单
-      description: 权限 platform:overseas-business:purchase:review。
+      description: 权限 platform:overseas-business:purchase:review；同幂等键同请求重放成功，异请求、旧 version 或终态反向审核返回 A0409。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: orderNo, in: path, required: true, schema: { type: string } }
         - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
       requestBody:
         required: true
-        content: { application/json: { schema: { type: object, required: [decision], properties: { decision: { type: string, enum: [APPROVE, REJECT] }, remark: { type: string, nullable: true, maxLength: 1000 } } } } }
+        content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementReview' } } }
       responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
   /api/merchant/v1/last-leg/overseas-procurements:
     post:
@@ -325,14 +356,24 @@ paths:
       responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
   /api/platform/v1/last-leg/us-truck-orders/{orderNo}/status:
     patch:
-      summary: 推进本土卡车订单状态
-      description: 权限 platform:overseas-business:truck:status；普通编辑接口不能修改状态。
+      summary: 取消未发车的本土卡车订单
+      description: 权限 platform:overseas-business:truck:status；该通用入口只接受 CANCELLED，正向状态必须使用具名命令，不能绕过实收、超托与分配事实。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: orderNo, in: path, required: true, schema: { type: string } }
         - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
-      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, status], properties: { version: { type: integer, format: int64, minimum: 0 }, status: { $ref: '#/components/schemas/TruckStatus' }, remark: { type: string, nullable: true, maxLength: 1000 } } } } } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCancel' } } } }
       responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 }, '409': { description: 非法状态迁移 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/review:
+    parameters: &truckOrderTarget
+      - { name: orderNo, in: path, required: true, schema: { type: string } }
+      - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+    post:
+      summary: 审核本土卡车订单
+      description: 权限 platform:overseas-business:truck:status；PENDING_REVIEW 审核通过进入 WAITING_INBOUND 并生成预期托盘；拒绝进入 REJECTED。幂等键异请求、旧 version 或非法跳转返回 A0409。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckReview' } } } }
+      responses: { '200': { description: 卡车订单详情 }, '409': { description: 版本、状态或幂等冲突 } }
   /api/platform/v1/last-leg/us-truck-orders/{orderNo}/receive-pallets:
     post:
       summary: 记录本土卡车订单实收托盘
@@ -341,7 +382,56 @@ paths:
       parameters:
         - { name: orderNo, in: path, required: true, schema: { type: string } }
         - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckReceivePallets' } } } }
       responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/review-pallet-overage:
+    parameters: *truckOrderTarget
+    post:
+      summary: 审核实收超出申报数的托盘
+      description: 权限 platform:overseas-business:truck:status；APPROVE 将超收托盘纳入本单并进入 WAITING_CONSOLIDATION；REJECT 标记超收托盘拒收并按原申报数继续。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckReviewPalletOverage' } } } }
+      responses: { '200': { description: 卡车订单详情 }, '409': { description: 版本、状态或幂等冲突 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/allocate-pallets:
+    parameters: *truckOrderTarget
+    post:
+      summary: 分配已实收托盘到本土卡车行程
+      description: 权限 platform:overseas-business:truck:status；仅接收本单 RECEIVED 托盘 ID；部分分配进入 PARTIALLY_ALLOCATED，全部分配进入 ALLOCATED。不创建海外仓出库单或扣减库存。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckAllocatePallets' } } } }
+      responses: { '200': { description: 卡车订单详情 }, '409': { description: 托盘归属、状态、版本或幂等冲突 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/prepare-dispatch:
+    parameters: *truckOrderTarget
+    post:
+      summary: 全部托盘分配后准备派车
+      description: 权限 platform:overseas-business:truck:status；旧 version、幂等键异请求或非 ALLOCATED 状态返回 A0409。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 PENDING_DISPATCH } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/dispatch:
+    parameters: *truckOrderTarget
+    post:
+      summary: 确认本土卡车已派车
+      description: 权限 platform:overseas-business:truck:status；本土卡车单自身履约，不创建海外仓排车单、出库单或派送单。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 DISPATCHED } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/start-transit:
+    parameters: *truckOrderTarget
+    post:
+      summary: 确认本土卡车开始运输
+      description: 权限 platform:overseas-business:truck:status；仅 DISPATCHED 可进入 IN_TRANSIT。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 IN_TRANSIT } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/complete:
+    parameters: *truckOrderTarget
+    post:
+      summary: 完成本土卡车订单
+      description: 权限 platform:overseas-business:truck:status；仅 IN_TRANSIT 可进入不可逆 COMPLETED。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 COMPLETED } }
   /api/platform/v1/last-leg/local-looseboard-orders:
     get:
       summary: 分页查询本土散板订单
@@ -373,12 +463,12 @@ paths:
   /api/platform/v1/last-leg/local-looseboard-orders/{orderNo}/status:
     patch:
       summary: 推进或取消本土散板订单
-      description: 权限 platform:overseas-business:looseboard:status；只允许 PENDING_ACCEPTANCE→DISPATCHED→IN_TRANSIT→COMPLETED，未完成节点按规则取消。
+      description: 权限 platform:overseas-business:looseboard:status；只允许 PENDING_ACCEPTANCE→DISPATCHED→IN_TRANSIT→COMPLETED，另建订单可进入 CANCELLED；幂等键异请求、旧 version、非法跳转或终态反向返回 A0409。
       security: [{ bearerAuth: [] }]
       parameters:
         - { name: orderNo, in: path, required: true, schema: { type: string } }
         - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
-      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, status], properties: { version: { type: integer, format: int64, minimum: 0 }, status: { $ref: '#/components/schemas/LooseboardStatus' }, remark: { type: string, nullable: true, maxLength: 1000 } } } } } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardStatusChange' } } } }
       responses: { '200': { description: 统一 ApiResponse 包装的散板订单详情 }, '409': { description: 非法状态迁移 } }
   /api/platform/v1/last-leg/relabel-applications:
     get:
@@ -423,6 +513,101 @@ paths:
       responses: { '200': { description: 统一 ApiResponse 包装的换标单详情 }, '409': { description: 非法状态迁移或关联尾程单缺失 } }
 components:
   schemas:
+    PdaWarehouseScan:
+      type: object
+      required: [code]
+      properties: { code: { type: string, minLength: 1, maxLength: 128 } }
+    PdaInventoryItem:
+      type: object
+      required: [customerId, balanceId, positionId, inboundCode, palletId, palletCode, availablePackages, holdPackages, receivingPackages, status, version]
+      properties:
+        customerId: { type: string }
+        customerName: { type: string, nullable: true }
+        balanceId: { type: integer, format: int64 }
+        positionId: { type: integer, format: int64 }
+        skuCode: { type: string, nullable: true }
+        productName: { type: string, nullable: true }
+        inboundCode: { type: string }
+        cartonMark: { type: string, nullable: true }
+        palletId: { type: integer, format: int64 }
+        palletCode: { type: string }
+        locationId: { type: integer, format: int64, nullable: true }
+        locationCode: { type: string, nullable: true }
+        availablePackages: { type: integer, format: int64, minimum: 0 }
+        holdPackages: { type: integer, format: int64, minimum: 0 }
+        receivingPackages: { type: integer, format: int64, minimum: 0 }
+        status: { type: string }
+        version: { type: integer, format: int64, minimum: 0 }
+    PdaInventoryScan:
+      type: object
+      required: [queryCode, items]
+      properties:
+        queryCode: { type: string }
+        items: { type: array, items: { $ref: '#/components/schemas/PdaInventoryItem' } }
+    PdaLocation:
+      type: object
+      required: [locationId, locationCode, locationType, status, occupiedPackages, inventoryPositionCount]
+      properties:
+        locationId: { type: integer, format: int64 }
+        locationCode: { type: string }
+        locationType: { type: string }
+        maxLoadKg: { type: number, nullable: true }
+        status: { type: string }
+        occupiedPackages: { type: integer, format: int64, minimum: 0 }
+        inventoryPositionCount: { type: integer, minimum: 0 }
+    PdaPallet:
+      type: object
+      required: [palletId, palletCode, status, version, locationId, locationCode, occupiedPackages, inventoryPositionCount, inventory]
+      properties:
+        palletId: { type: integer, format: int64 }
+        palletCode: { type: string }
+        status: { type: string }
+        version: { type: integer, minimum: 0 }
+        locationId: { type: integer, format: int64 }
+        locationCode: { type: string }
+        occupiedPackages: { type: integer, format: int64, minimum: 0 }
+        inventoryPositionCount: { type: integer, minimum: 0 }
+        inventory: { type: array, items: { $ref: '#/components/schemas/PdaInventoryItem' } }
+    PdaOperation:
+      type: object
+      required: [operationId, operationType, businessKey, status, occurredAt]
+      properties:
+        operationId: { type: integer, format: int64 }
+        operationType: { type: string }
+        businessKey: { type: string }
+        status: { type: string }
+        summary: { type: string, nullable: true }
+        customerId: { type: string, nullable: true }
+        occurredAt: { type: string, format: date-time }
+    PdaInventoryScanApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/PdaInventoryScan' } }
+    PdaLocationApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/PdaLocation' } }
+    PdaPalletApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/PdaPallet' } }
+    PdaOperationPageApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties:
+            data:
+              type: object
+              required: [records, page, size, total, pages]
+              properties:
+                records: { type: array, items: { $ref: '#/components/schemas/PdaOperation' } }
+                page: { type: integer }
+                size: { type: integer }
+                total: { type: integer, format: int64 }
+                pages: { type: integer, format: int64 }
     ReceivingAction:
       type: object
       required: [idempotencyKey]
@@ -765,6 +950,14 @@ components:
         status: { $ref: '#/components/schemas/RelabelStatus' }
         remark: { type: string, nullable: true, maxLength: 1000 }
     ProcurementStatus: { type: string, enum: [PENDING_REVIEW, APPROVED, REJECTED] }
+    ProcurementReview:
+      type: object
+      required: [version, decision, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        decision: { type: string, enum: [APPROVE, REJECT] }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     ProcurementCreate:
       type: object
       required: [purchaseCategory, productName, purchaseQuantity, contactName, contactPhone, idempotencyKey]
@@ -812,6 +1005,49 @@ components:
         code: { type: string, enum: ['200'] }
         data: { type: array, items: { type: object, properties: { warehouseId: { type: string }, warehouseCode: { type: string }, warehouseName: { type: string }, countryCode: { type: string } } } }
     TruckStatus: { type: string, enum: [PENDING_REVIEW, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PALLET_OVERAGE_REVIEW, PARTIALLY_ALLOCATED, ALLOCATED, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, REJECTED, CANCELLED] }
+    TruckReview:
+      type: object
+      required: [version, decision, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        decision: { type: string, enum: [APPROVE, REJECT] }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckCancel:
+      type: object
+      required: [version, status, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        status: { type: string, enum: [CANCELLED] }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckReceivePallets:
+      type: object
+      required: [version, actualPalletCount, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        actualPalletCount: { type: integer, minimum: 1 }
+        packageCount: { type: integer, nullable: true, minimum: 0 }
+        palletPackageCounts: { type: array, maxItems: 500, items: { type: integer, minimum: 0 } }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckReviewPalletOverage:
+      allOf: [{ $ref: '#/components/schemas/TruckReview' }]
+    TruckAllocatePallets:
+      type: object
+      required: [version, palletIds, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        palletIds: { type: array, minItems: 1, maxItems: 500, uniqueItems: true, items: { type: integer, format: int64, minimum: 1 } }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckCommand:
+      type: object
+      required: [version, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     TruckCreate:
       type: object
       required: [origin, destination, palletCount, totalWeightKg, totalVolumeCbm, contactName, contactInfo, requestedDate, idempotencyKey]
@@ -855,6 +1091,14 @@ components:
         requestedDate: { type: string, format: date }
         remark: { type: string, nullable: true, maxLength: 1000 }
     LooseboardStatus: { type: string, enum: [PENDING_ACCEPTANCE, DISPATCHED, IN_TRANSIT, COMPLETED, CANCELLED] }
+    LooseboardStatusChange:
+      type: object
+      required: [version, status, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        status: { $ref: '#/components/schemas/LooseboardStatus' }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
     LooseboardCreate:
       type: object
       required: [transportMode, palletRequired, transportType, origin, destination, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]