优化

2026-09-15 16:10:55 +08:00
parent 506525524b
commit c207a4d3b7
20 changed files with 693 additions and 93 deletions
@@ -83,6 +83,7 @@ CREATE TABLE IF NOT EXISTS ll_order (
  estimated_arrival_at DATETIME(3) COMMENT '预计到港时间',
  actual_arrival_at DATETIME(3) COMMENT '实际到港时间',
  estimated_warehouse_at DATETIME(3) COMMENT '预计到仓时间',
+  arrival_time_version INT NOT NULL DEFAULT 0 COMMENT '柜级预计到仓时间乐观锁版本',
  inbound_order_no VARCHAR(128) COMMENT '入库单号',
  outbound_order_no VARCHAR(128) COMMENT '出库单号',
  delivery_order_no VARCHAR(128) COMMENT '派送单号',
@@ -245,6 +246,20 @@ CREATE TABLE IF NOT EXISTS ll_receiving_warehouse_operation (
  KEY idx_ll_receiving_warehouse_container(source_container_booking_id,created_at)
 ) ENGINE=InnoDB COMMENT='柜级海外接柜仓修改幂等审计记录';

+CREATE TABLE IF NOT EXISTS ll_container_arrival_time_operation (
+  id BIGINT NOT NULL COMMENT '柜级预计到仓时间修改操作ID',
+  source_container_booking_id VARCHAR(128) NOT NULL COMMENT '稳定来源柜预订ID',
+  idempotency_key VARCHAR(255) NOT NULL COMMENT '平台请求幂等键',
+  request_hash VARCHAR(64) NOT NULL COMMENT '规范化修改请求SHA-256摘要',
+  result_version INT NOT NULL COMMENT '修改成功后的柜级时间版本',
+  operator_name VARCHAR(128) NOT NULL COMMENT '平台操作人名称',
+  remark VARCHAR(500) NULL COMMENT '预计到仓时间修改备注',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '操作时间',
+  PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_container_arrival_time_idempotency(idempotency_key),
+  KEY idx_ll_container_arrival_time_container(source_container_booking_id,created_at)
+) ENGINE=InnoDB COMMENT='柜级预计到仓时间修改幂等审计记录';
+
 -- 派送单列表与详情快照、转派送费用及操作记录。
 CREATE TABLE IF NOT EXISTS ll_delivery_order (
  id BIGINT NOT NULL COMMENT '派送单主键ID',
@@ -388,6 +403,8 @@ ALTER TABLE ll_loading_event_inbox COMMENT='头程装柜完成事件接收幂等
 ALTER TABLE ll_order COMMENT='尾程订单主表';
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='source_container_booking_id'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN source_container_booking_id VARCHAR(128) NULL COMMENT ''来源头程货柜预订ID'' AFTER source_loading_plan_id'));
 PREPARE lastleg_order_container_booking_stmt FROM @ddl; EXECUTE lastleg_order_container_booking_stmt; DEALLOCATE PREPARE lastleg_order_container_booking_stmt;
+SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema=DATABASE() AND table_name='ll_order' AND column_name='arrival_time_version'), 'SELECT 1', 'ALTER TABLE ll_order ADD COLUMN arrival_time_version INT NOT NULL DEFAULT 0 COMMENT ''柜级预计到仓时间乐观锁版本'' AFTER estimated_warehouse_at'));
+PREPARE lastleg_order_arrival_time_version_stmt FROM @ddl; EXECUTE lastleg_order_arrival_time_version_stmt; DEALLOCATE PREPARE lastleg_order_arrival_time_version_stmt;
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='ll_order' AND index_name='idx_ll_order_pending_container'), 'ALTER TABLE ll_order DROP INDEX idx_ll_order_pending_container', 'SELECT 1'));
 PREPARE lastleg_order_pending_container_idx_stmt FROM @ddl; EXECUTE lastleg_order_pending_container_idx_stmt; DEALLOCATE PREPARE lastleg_order_pending_container_idx_stmt;
 SET @ddl = (SELECT IF(EXISTS (SELECT 1 FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name='ll_order' AND index_name='idx_ll_order_container_progress'), 'SELECT 1', 'ALTER TABLE ll_order ADD INDEX idx_ll_order_container_progress(source_container_booking_id,estimated_warehouse_at,created_at,id)'));
@@ -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]