优化

2026-08-28 13:54:32 +08:00
parent fe68551124
commit 6b5f2f0565
29 changed files with 959 additions and 178 deletions
@@ -158,8 +158,8 @@ paths:
      responses: { '200': { description: 统一 ApiResponse 包装的尾程订单分页；列表行 destinationType 为 FBA 或 OVERSEAS } }
  /api/platform/v1/last-leg/orders/container-summaries:
    get:
-      summary: 分页查询待分配柜级摘要
-      description: 权限 platform:overseas-warehouse:order:list；平台跨客户按稳定 sourceContainerBookingId 聚合。仅返回至少有一票待分配的柜；eligible=false 表示柜内状态或柜号不一致，禁止转换。
+      summary: 分页查询柜级入库计划进度
+      description: 权限 platform:overseas-warehouse:order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响。plannedArrivalAt 仅来自装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at；按该时间升序、null 最后、稳定柜 ID 升序。
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -185,7 +185,58 @@ paths:
                      pages: { type: integer, format: int64 }
                      records:
                        type: array
-                        items: { $ref: '#/components/schemas/PendingContainerSummary' }
+                        items: { $ref: '#/components/schemas/ContainerPlanProgressSummary' }
+  /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}:
+    get:
+      summary: 查询柜级入库计划进度详情
+      description: 权限 platform:overseas-warehouse:order:list；按稳定柜 ID 返回柜内全部尾程订单、入仓码及各自计划状态，不受订单分页截断。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string, minLength: 1, maxLength: 128 } }
+      responses:
+        '200':
+          description: 统一 ApiResponse 包装的柜级进度详情
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string, enum: ['200'] }
+                  data: { $ref: '#/components/schemas/ContainerPlanProgressDetail' }
+        '404': { description: 稳定柜 ID 不存在 }
+  /api/platform/v1/last-leg/orders/{id}/destination:
+    put:
+      summary: 将单票尾程订单转入 FBA 目的仓
+      description: 权限 platform:overseas-warehouse:order:edit；目标必须来自国内 Warehouse Service 平台公共 ACTIVE FBA 主档，warehouseId/warehouseCode/warehouseName 必须与权威记录一致。实际海外收货仓、普通国内中转仓、停用仓或伪造字段均返回 A0400“所选FBA仓不存在或已停用”。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: id, in: path, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/FbaTransferDestination' }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的更新订单数 }
+        '400': { description: 所选FBA仓不存在、已停用、类型错误或字段不一致 }
+        '503': { description: 国内FBA仓权威主数据暂不可用，写入失败关闭 }
+  /api/platform/v1/last-leg/orders/destination:
+    put:
+      summary: 批量将尾程订单转入 FBA 目的仓
+      description: 权限 platform:overseas-warehouse:order:edit；一次校验国内 Warehouse Service 权威 FBA 主档后，在 Lastleg 事务内更新所选订单及冻结明细。目标仓必须为平台公共 ACTIVE FBA 且 ID/编码/名称完全一致。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: customerId, in: query, required: false, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/FbaBatchTransferDestination' }
+      responses:
+        '200': { description: 统一 ApiResponse 包装的更新订单数 }
+        '400': { description: 所选FBA仓不存在、已停用、类型错误或字段不一致 }
+        '503': { description: 国内FBA仓权威主数据暂不可用，写入失败关闭 }
  /api/platform/v1/last-leg/inbound-plans/convert:
    post:
      summary: 平台生成入库计划
@@ -592,20 +643,63 @@ paths:
      responses: { '200': { description: 统一 ApiResponse 包装的换标单详情 }, '409': { description: 非法状态迁移或关联尾程单缺失 } }
 components:
  schemas:
-    PendingContainerSummary:
+    FbaTransferDestination:
      type: object
-      required: [sourceContainerBookingId, orderCount, inboundCodeCount, customerCount, totalPackageCount, totalPalletCount, totalVolumeCbm, eligible]
+      required: [warehouseId, warehouseCode, warehouseName]
+      properties:
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$', description: 国内 Warehouse Service 平台公共 FBA 仓 ID }
+        warehouseCode: { type: string, minLength: 1, maxLength: 128 }
+        warehouseName: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 500 }
+    FbaBatchTransferDestination:
+      allOf:
+        - { $ref: '#/components/schemas/FbaTransferDestination' }
+        - type: object
+          required: [orderIds]
+          properties:
+            orderIds:
+              type: array
+              minItems: 1
+              maxItems: 200
+              uniqueItems: true
+              items: { type: string, pattern: '^[1-9][0-9]*$' }
+    ContainerPlanProgressSummary:
+      type: object
+      required: [sourceContainerBookingId, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, allPlansReady]
      properties:
        sourceContainerBookingId: { type: string }
        containerNo: { type: string, nullable: true }
-        orderCount: { type: integer, format: int64 }
+        totalOrderCount: { type: integer, format: int64 }
        inboundCodeCount: { type: integer, format: int64 }
-        customerCount: { type: integer, format: int64 }
-        totalPackageCount: { type: integer, format: int64 }
-        totalPalletCount: { type: integer, format: int64 }
-        totalVolumeCbm: { type: number }
-        eligible: { type: boolean }
-        ineligibleReason: { type: string, nullable: true }
+        missingInboundCodeCount: { type: integer, format: int64 }
+        planCount: { type: integer, format: int64 }
+        plannedInboundCodeCount: { type: integer, format: int64 }
+        pendingPlanCount: { type: integer, format: int64, description: 尚未生成有效计划的尾程订单数，即未操作数 }
+        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 }
+    ContainerPlanProgressDetail:
+      type: object
+      required: [summary, orders]
+      properties:
+        summary: { $ref: '#/components/schemas/ContainerPlanProgressSummary' }
+        orders:
+          type: array
+          items: { $ref: '#/components/schemas/ContainerPlanProgressItem' }
+    ContainerPlanProgressItem:
+      type: object
+      required: [orderId, customerId, orderStatus, planValid]
+      properties:
+        orderId: { type: string, pattern: '^[1-9][0-9]*$' }
+        customerId: { type: string }
+        orderNo: { type: string, nullable: true }
+        inboundCode: { type: string, nullable: true }
+        orderStatus: { type: string }
+        planId: { type: string, nullable: true, pattern: '^[1-9][0-9]*$' }
+        planNo: { type: string, nullable: true }
+        planStatus: { type: string, nullable: true }
+        planValid: { type: boolean }
+        plannedArrivalAt: { type: string, format: date-time, nullable: true, description: ll_order.estimated_warehouse_at }
    PdaWarehouseScan:
      type: object
      required: [code]
@@ -773,16 +867,25 @@ components:
        warehouseName: { type: string, description: 国内Warehouse Service主档维护的当前中文名称 }
    ReceivingCandidate:
      type: object
-      required: [containerNo, status, planCount, inboundCodeCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, currentAccount]
+      required: [sourceContainerBookingId, containerNo, status, totalOrderCount, inboundCodeCount, missingInboundCodeCount, planCount, plannedInboundCodeCount, pendingPlanCount, destinationCodes, plannedPalletCount, totalPackages, receivedPackages, operable, allPlansReady, currentAccount]
      properties:
+        sourceContainerBookingId: { type: string, description: 头程与尾程共享的稳定柜身份 }
        containerNo: { type: string }
        status: { type: string, enum: [WAIT_SIGN, SIGNED, RECEIVING, COMPLETED] }
+        totalOrderCount: { type: integer, minimum: 1 }
+        missingInboundCodeCount: { type: integer, minimum: 0 }
        planCount: { type: integer }
        inboundCodeCount: { type: integer }
+        plannedInboundCodeCount: { type: integer, minimum: 0 }
+        pendingPlanCount: { type: integer, minimum: 0 }
        destinationCodes: { type: array, uniqueItems: true, items: { type: string } }
        plannedPalletCount: { type: integer }
        totalPackages: { type: integer }
        receivedPackages: { type: integer }
+        operable: { type: boolean }
+        allPlansReady: { type: boolean }
+        blockReason: { type: string, nullable: true }
+        plannedArrivalAt: { type: string, format: date-time, nullable: true }
        currentAccount: { type: boolean }
    ReceivingSession:
      type: object