优化

2026-09-15 16:10:55 +08:00
parent 506525524b
commit c207a4d3b7
20 changed files with 693 additions and 93 deletions
@@ -311,7 +311,7 @@ paths:
  /api/platform/v1/last-leg/orders/container-summaries:
    get:
      summary: 分页查询柜级入库计划进度
-      description: 权限 platform:overseas-warehouse:last-mile-order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响，返回全部稳定来源柜；全部入仓码均已生成有效独立计划的柜仍保留，供柜级接柜仓查询与修改，生成计划动作由 allPlansReady/pendingPlanCount 控制。containerNo 只返回装柜完成事件携带并规范化冻结的真实集装箱号，不从 cabinetNo、订单号或内部 ID 推导。plannedArrivalAt 仅来自装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at；按该时间升序、null 最后、稳定柜 ID 升序。
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；平台跨客户按稳定 sourceContainerBookingId 服务端聚合，不受订单分页影响，返回全部稳定来源柜；全部入仓码均已生成有效独立计划的柜仍保留，供柜级接柜仓查询与修改，生成计划动作由 allPlansReady/pendingPlanCount 控制。containerNo 只返回装柜完成事件携带并规范化冻结的真实集装箱号，不从 cabinetNo、订单号或内部 ID 推导。plannedArrivalAt 取 ll_order.estimated_warehouse_at，可由装柜完成事件初始化，并在入库计划生成前由平台按整柜人工修正；按该时间升序、null 最后、稳定柜 ID 升序。
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
@@ -381,6 +381,52 @@ paths:
                  data: { $ref: '#/components/schemas/ContainerPlanProgressSummary' }
        '400': { description: 请求无效或目标不是有效 OVERSEAS 仓 }
        '409': { description: 版本冲突、幂等键冲突或PDA接柜会话已建立 }
+  /api/platform/v1/last-leg/orders/container-arrival-times/query:
+    post:
+      summary: 批量查询整柜预计与实际到仓时间
+      description: 权限 platform:overseas-warehouse:last-mile-order:list；预计到仓取整柜人工冻结值，实际到仓取海外 PDA 首次开始收货时间。
+      security: [{ bearerAuth: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ContainerArrivalTimeQuery' }
+      responses:
+        '200':
+          description: 柜级到仓时间列表
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string, enum: ['200'] }
+                  data:
+                    type: array
+                    items: { $ref: '#/components/schemas/ContainerArrivalTimeView' }
+  /api/platform/v1/last-leg/orders/container-summaries/{sourceContainerBookingId}/expected-arrival:
+    put:
+      summary: 修改整柜预计到仓时间
+      description: 权限 platform:overseas-warehouse:last-mile-order:edit；使用柜级时间版本与 Idempotency-Key，在入库计划生成前原子更新柜内全部尾程订单。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: sourceContainerBookingId, in: path, required: true, schema: { type: string } }
+        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 1, maxLength: 255 } }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ChangeExpectedWarehouseArrivalRequest' }
+      responses:
+        '200':
+          description: 更新后的柜级到仓时间
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  code: { type: string, enum: ['200'] }
+                  data: { $ref: '#/components/schemas/ContainerArrivalTimeView' }
+        '409': { description: 已生成入库计划、版本冲突或幂等键冲突 }
  /api/platform/v1/last-leg/orders/{id}/destination:
    put:
      summary: 将单票尾程订单转入 FBA 目的仓
@@ -1669,7 +1715,7 @@ components:
        plannedInboundCodeCount: { type: integer, format: int64 }
        pendingPlanCount: { type: integer, format: int64, description: 尚未生成有效计划的尾程订单数，即未操作数 }
        resourcePendingPlanCount: { type: integer, format: int64, description: 已有有效计划但尚未完整绑定海外仓真实托盘的订单数 }
-        plannedArrivalAt: { type: string, format: date-time, nullable: true, description: 仅来源于装柜完成事件 estimatedWarehouseArrivalAt 冻结的 ll_order.estimated_warehouse_at }
+        plannedArrivalAt: { type: string, format: date-time, nullable: true, description: 整柜一致的 ll_order.estimated_warehouse_at，可由装柜事件初始化并在计划生成前人工维护 }
        allPlansReady: { type: boolean, description: 全柜每票均有入仓码且均存在有效独立计划时为 true }
        blockingReason: { type: string, nullable: true }
    ChangeReceivingWarehouseRequest:
@@ -1679,6 +1725,31 @@ components:
        overseasWarehouseId: { type: integer, format: int64, minimum: 1 }
        expectedVersion: { type: integer, minimum: 0 }
        remark: { type: string, maxLength: 500, nullable: true }
+    ContainerArrivalTimeQuery:
+      type: object
+      required: [sourceContainerBookingIds]
+      properties:
+        sourceContainerBookingIds:
+          type: array
+          minItems: 1
+          maxItems: 200
+          uniqueItems: true
+          items: { type: string, minLength: 1, maxLength: 128 }
+    ChangeExpectedWarehouseArrivalRequest:
+      type: object
+      required: [estimatedWarehouseArrivalAt, expectedVersion]
+      properties:
+        estimatedWarehouseArrivalAt: { type: string, format: date-time }
+        expectedVersion: { type: integer, minimum: 0 }
+        remark: { type: string, maxLength: 500, nullable: true }
+    ContainerArrivalTimeView:
+      type: object
+      required: [sourceContainerBookingId, version]
+      properties:
+        sourceContainerBookingId: { type: string }
+        estimatedWarehouseArrivalAt: { type: string, format: date-time, nullable: true }
+        actualWarehouseArrivalAt: { type: string, format: date-time, nullable: true, description: 海外 PDA 首次开始收货时间 }
+        version: { type: integer, minimum: 0 }
    ContainerPlanProgressDetail:
      type: object
      required: [summary, orders]