优化

2026-09-07 15:07:34 +08:00
parent 693e10188c
commit 1b47158770
37 changed files with 688 additions and 144 deletions
@@ -298,6 +298,23 @@ paths:
                  code: { type: string, enum: ['200'] }
                  data: { $ref: '#/components/schemas/ContainerPlanProgressDetail' }
        '404': { description: 稳定柜 ID 不存在 }
+  /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}/receiving-warehouse:
+    put:
+      summary: 修改整柜海外接柜仓
+      description: 权限 platform:overseas-warehouse:order:edit；目标必须为国内 Warehouse Service 有效 OVERSEAS 仓。使用柜级版本和 Idempotency-Key，事务内原子同步柜内全部尾程订单及已有入库计划；海外PDA一旦建立接柜会话即永久锁定。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ChangeReceivingWarehouseRequest' }
+      responses:
+        '200': { description: 更新后的柜级摘要, content: { application/json: { schema: { type: object, properties: { code: { type: string, enum: ['200'] }, data: { $ref: '#/components/schemas/ContainerPlanProgressSummary' } } } } }
+        '400': { description: 请求无效或目标不是有效 OVERSEAS 仓 }
+        '409': { description: 版本冲突、幂等键冲突或PDA接柜会话已建立 }
  /api/platform/v1/last-leg/orders/{id}/destination:
    put:
      summary: 将单票尾程订单转入 FBA 目的仓
@@ -331,6 +348,39 @@ paths:
        '200': { description: 统一 ApiResponse 包装的更新订单数 }
        '400': { description: 所选FBA仓不存在、已停用、类型错误或字段不一致 }
        '503': { description: 国内FBA仓权威主数据暂不可用，写入失败关闭 }
+  /api/platform/v1/last-leg/inbound-plans:
+    get:
+      summary: 平台分页查询海外入库订单
+      description: 权限 platform:overseas-warehouse:inbound-order:list；列表中的 overseasWarehouseCode/overseasWarehouseName 只取尾程订单预分配接柜仓事实，warehouseCode/warehouseName 仍表示目的仓。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { 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: planNo, in: query, schema: { type: string } }
+        - { name: inboundCode, in: query, schema: { type: string } }
+        - { name: lxCode, in: query, schema: { type: string } }
+        - { name: status, in: query, schema: { type: string } }
+        - { name: overseasWarehouseId, in: query, schema: { type: string } }
+        - { name: destinationWarehouseCode, in: query, schema: { type: string } }
+        - { name: warehouse, in: query, schema: { type: string } }
+        - { name: fbaWarehouseCode, in: query, schema: { type: string } }
+        - { name: appointmentStatus, in: query, schema: { type: string, enum: [UNAPPOINTED, PENDING, SUCCESS, FAILED, CANCELLED] } }
+        - { name: dispatchStatus, in: query, schema: { type: string, enum: [UNSCHEDULED, SCHEDULED] } }
+        - { name: createdFrom, in: query, schema: { type: string, format: date-time } }
+        - { name: createdTo, in: query, schema: { type: string, format: date-time } }
+      responses: { '200': { description: 平台入库订单分页, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanPageResponse' } } } } }
+  /api/platform/v1/last-leg/inbound-plans/{planNo}:
+    get:
+      summary: 平台查询海外入库订单详情
+      description: 权限 platform:overseas-warehouse:inbound-order:list；详情中的 overseasWarehouseCode/overseasWarehouseName 只取当前计划来源尾程订单的预分配接柜仓事实。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: planNo, in: path, required: true, schema: { type: string } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      responses:
+        '200': { description: 平台入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }
+        '404': { description: 入库订单不存在或不属于指定客户 }
  /api/platform/v1/last-leg/inbound-plans/convert:
    post:
      summary: 平台生成入库计划
@@ -811,7 +861,7 @@ paths:
  /api/merchant/v1/last-leg/inbound-plans:
    get:
      summary: 客户分页查询自己的海外入库订单
-      description: 权限 merchant:warehouse:inbound:list；客户范围只取认证 Token，不接收 customerId。
+      description: 权限 merchant:warehouse:inbound:list；客户范围只取认证 Token，不接收 customerId；overseasWarehouseCode/overseasWarehouseName 只取该客户尾程订单预分配接柜仓事实，warehouseCode/warehouseName 仍表示目的仓。
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -829,7 +879,7 @@ paths:
  /api/merchant/v1/last-leg/inbound-plans/{planNo}:
    get:
      summary: 客户查询自己的海外入库订单详情
-      description: 权限 merchant:warehouse:inbound:list；列表权限包含详情只读，不接收 customerId。
+      description: 权限 merchant:warehouse:inbound:list；列表权限包含详情只读，不接收 customerId；overseasWarehouseCode/overseasWarehouseName 只取该计划来源尾程订单的预分配接柜仓事实。
      security: [{ bearerAuth: [] }]
      parameters: [{ name: planNo, in: path, required: true, schema: { type: string } }]
      responses: { '200': { description: 当前客户入库订单详情, content: { application/json: { schema: { $ref: '#/components/schemas/InboundPlanDetailResponse' } } } }, '404': { description: 当前客户下入库订单不存在 } }
@@ -1093,10 +1143,16 @@ components:
              items: { type: string, pattern: '^[1-9][0-9]*$' }
    ContainerPlanProgressSummary:
      type: object
-      required: [sourceContainerBookingId, containerNo, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
+      required: [sourceContainerBookingId, containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, assignmentVersion, canChangeReceivingWarehouse, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
      properties:
        sourceContainerBookingId: { type: string }
        containerNo: { type: string, pattern: '^[A-Z]{3}[UJZ][0-9]{7}$', description: 装柜完成事件非空且通过 ISO 6346 校验位验证的规范化真实集装箱号；不使用 cabinetNo、订单号或内部 ID 回退 }
+        overseasWarehouseId: { type: string, pattern: '^[1-9][0-9]*$', description: 平台预分配的海外接柜仓ID，不是FBA目的仓 }
+        overseasWarehouseCode: { type: string, description: 海外接柜仓业务编码 }
+        overseasWarehouseName: { type: string, description: 海外接柜仓业务名称 }
+        assignmentVersion: { type: integer, minimum: 0, description: 柜级接柜仓乐观锁版本 }
+        canChangeReceivingWarehouse: { type: boolean }
+        receivingWarehouseLockReason: { type: string, nullable: true }
        totalOrderCount: { type: integer, format: int64 }
        inboundCodeCount: { type: integer, format: int64 }
        missingInboundCodeCount: { type: integer, format: int64 }
@@ -1106,6 +1162,13 @@ components:
        plannedArrivalAt: { type: string, format: date-time, nullable: true, description: 仅来源于装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at }
        allPlansReady: { type: boolean, description: 全柜每票均有入仓码且均存在有效独立计划时为 true }
        blockingReason: { type: string, nullable: true }
+    ChangeReceivingWarehouseRequest:
+      type: object
+      required: [overseasWarehouseId, expectedVersion]
+      properties:
+        overseasWarehouseId: { type: integer, format: int64, minimum: 1 }
+        expectedVersion: { type: integer, minimum: 0 }
+        remark: { type: string, maxLength: 500, nullable: true }
    ContainerPlanProgressDetail:
      type: object
      required: [summary, orders]
@@ -1329,10 +1392,12 @@ components:
        warehouseName: { type: string, description: 国内Warehouse Service主档维护的当前中文名称 }
    ReceivingCandidate:
      type: object
-      required: [sourceContainerBookingId, containerNo, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
+      required: [sourceContainerBookingId, containerNo, overseasWarehouseCode, overseasWarehouseName, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
      properties:
        sourceContainerBookingId: { type: string, description: 头程与尾程共享的稳定柜身份 }
        containerNo: { type: string }
+        overseasWarehouseCode: { type: string }
+        overseasWarehouseName: { type: string }
        status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
        totalOrderCount: { type: integer, minimum: 1 }
        missingInboundCodeCount: { type: integer, minimum: 0 }
@@ -1351,10 +1416,11 @@ components:
        currentAccount: { type: boolean }
    ReceivingSession:
      type: object
-      required: [containerNo, overseasWarehouseId, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, inbounds]
+      required: [containerNo, overseasWarehouseId, overseasWarehouseCode, overseasWarehouseName, status, version, photos, totalPackages, receivedPackages, pendingPackages, inbounds]
      properties:
        containerNo: { type: string }
-        overseasWarehouseId: { type: string, pattern: '^\d+$', description: PDA Token绑定并在认领柜号时冻结的共享实际海外收货仓ID }
+        overseasWarehouseId: { type: string, pattern: '^\d+$', description: 平台预分配并与PDA Token匹配的海外接柜仓ID }
+        overseasWarehouseCode: { type: string, description: 海外接柜仓业务编码快照 }
        overseasWarehouseName: { type: string, description: Warehouse Overseas服务校验后的共享实际海外收货仓名称快照 }
        status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
        operatorName: { type: string, nullable: true }
@@ -1911,7 +1977,7 @@ components:
          properties: { records: { type: array, items: { $ref: '#/components/schemas/InboundPlanSummary' } } }
    InboundPlanSummary:
      type: object
-      required: [lineId, planId, planNo, customerId, orderId, inboundCode, packageCount, pickedPackageCount, palletCount, status, createdAt, version]
+      required: [lineId, planId, planNo, customerId, orderId, inboundCode, overseasWarehouseCode, overseasWarehouseName, packageCount, pickedPackageCount, palletCount, status, createdAt, version]
      properties:
        lineId: { type: string, pattern: '^[0-9]+$' }
        planId: { type: string, pattern: '^[0-9]+$' }
@@ -1920,6 +1986,8 @@ components:
        orderId: { type: string, pattern: '^[0-9]+$' }
        inboundCode: { type: string }
        orderType: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, description: 接柜仓编码，取自尾程订单预分配接收仓事实 }
+        overseasWarehouseName: { type: string, description: 接柜仓名称，取自尾程订单预分配接收仓事实 }
        warehouseId: { type: string, nullable: true }
        warehouseCode: { type: string, nullable: true }
        warehouseName: { type: string, nullable: true }
@@ -1939,13 +2007,15 @@ components:
        version: { type: integer }
    InboundPlanDetail:
      type: object
-      required: [id, planNo, customerId, status, lineCount, palletCount, totalVolumeCbm, expectedPackageCount, pickedPackageCount, lines, pallets, allocations, version]
+      required: [id, planNo, customerId, overseasWarehouseCode, overseasWarehouseName, status, lineCount, palletCount, totalVolumeCbm, expectedPackageCount, pickedPackageCount, lines, pallets, allocations, version]
      properties:
        id: { type: string, pattern: '^[0-9]+$' }
        planNo: { type: string }
        customerId: { type: string }
        sourceOrderId: { type: string, pattern: '^[0-9]+$', nullable: true }
        containerNo: { type: string, nullable: true }
+        overseasWarehouseCode: { type: string, description: 接柜仓编码，取自尾程订单预分配接收仓事实 }
+        overseasWarehouseName: { type: string, description: 接柜仓名称，取自尾程订单预分配接收仓事实 }
        status: { type: string }
        lineCount: { type: integer }
        palletCount: { type: integer }