优化

common-event-contract/src/main/java/com/baiyue/common/event/FirstLegLoadingPlanCompletedV1.java

@@ -7,7 +7,14 @@ import java.util.List;
 public record FirstLegLoadingPlanCompletedV1(
         String loadingPlanId, String planNo, String containerBookingId,
         String containerNo, String cabinetNo, String warehouseId, String warehouseName,
+        String estimatedPortArrivalAt, String actualPortArrivalAt, String estimatedWarehouseArrivalAt,
         List<Order> orders) {
+    public FirstLegLoadingPlanCompletedV1(String loadingPlanId, String planNo, String containerBookingId,
+                                          String containerNo, String cabinetNo, String warehouseId,
+                                          String warehouseName, List<Order> orders) {
+        this(loadingPlanId, planNo, containerBookingId, containerNo, cabinetNo, warehouseId,
+            warehouseName, null, null, null, orders);
+    }
 
     public record Order(
             String sourceInboundId, String rootInboundId,
@@ -16,6 +23,7 @@ public record FirstLegLoadingPlanCompletedV1(
             String destinationWarehouseCode, String destinationWarehouseName,
             int packageCount, Integer productQuantity, Integer palletCount,
             BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
+            BigDecimal volumeWeightKg,
             List<Item> items, String customerId, String customerName, String orderType, List<PalletSnapshot> pallets,
             String destinationType) {
         public Order {
@@ -40,9 +48,23 @@ public record FirstLegLoadingPlanCompletedV1(
             this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
                 inboundCode, destinationWarehouseId, destinationWarehouseCode,
                 destinationWarehouseName, packageCount, productQuantity, palletCount,
-                grossWeightKg, netWeightKg, volumeCbm, items, customerId, customerName,
+                grossWeightKg, netWeightKg, volumeCbm, null, items, customerId, customerName,
                 orderType, pallets, null);
         }
+        public Order(String sourceInboundId, String rootInboundId,
+                     String sourceOrderId, String sourceOrderNo, String rootOrderId,
+                     String inboundCode, String destinationWarehouseId,
+                     String destinationWarehouseCode, String destinationWarehouseName,
+                     int packageCount, Integer productQuantity, Integer palletCount,
+                     BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
+                     List<Item> items, String customerId, String customerName,
+                     String orderType, List<PalletSnapshot> pallets, String destinationType) {
+            this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
+                inboundCode, destinationWarehouseId, destinationWarehouseCode,
+                destinationWarehouseName, packageCount, productQuantity, palletCount,
+                grossWeightKg, netWeightKg, volumeCbm, null, items, customerId, customerName,
+                orderType, pallets, destinationType);
+        }
     }
 
     public record Item(

common-event-contract/src/main/java/com/baiyue/common/event/FirstLegLoadingPlanCompletedV2.java

@@ -7,7 +7,15 @@ import java.util.List;
 public record FirstLegLoadingPlanCompletedV2(
         String loadingPlanId, String planNo, String containerBookingId,
         String containerNo, String cabinetNo, String warehouseId, String warehouseName,
+        String estimatedPortArrivalAt, String actualPortArrivalAt, String estimatedWarehouseArrivalAt,
         List<Order> orders) {
+    public FirstLegLoadingPlanCompletedV2(String loadingPlanId, String planNo, String containerBookingId,
+                                          String containerNo, String cabinetNo, String warehouseId,
+                                          String warehouseName, List<Order> orders) {
+        this(loadingPlanId, planNo, containerBookingId, containerNo, cabinetNo, warehouseId,
+            warehouseName, null, null, null, orders);
+    }
+
     public record Order(
             String sourceInboundId, String rootInboundId,
             String sourceOrderId, String sourceOrderNo, String rootOrderId,
@@ -15,6 +23,7 @@ public record FirstLegLoadingPlanCompletedV2(
             String destinationWarehouseCode, String destinationWarehouseName,
             int packageCount, Integer productQuantity, Integer palletCount,
             BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
+            BigDecimal volumeWeightKg,
             List<Item> items, String customerId, String customerName, String orderType, List<PalletSnapshot> pallets,
             /** 目的类型：FBA 可按箱数收货，OVERSEAS 必须逐箱扫码。 */
             String destinationType) {
@@ -41,9 +50,24 @@ public record FirstLegLoadingPlanCompletedV2(
             this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
                 inboundCode, destinationWarehouseId, destinationWarehouseCode,
                 destinationWarehouseName, packageCount, productQuantity, palletCount,
-                grossWeightKg, netWeightKg, volumeCbm, items, customerId, customerName,
+                grossWeightKg, netWeightKg, volumeCbm, null, items, customerId, customerName,
                 orderType, pallets, null);
         }
+
+        public Order(String sourceInboundId, String rootInboundId,
+                     String sourceOrderId, String sourceOrderNo, String rootOrderId,
+                     String inboundCode, String destinationWarehouseId,
+                     String destinationWarehouseCode, String destinationWarehouseName,
+                     int packageCount, Integer productQuantity, Integer palletCount,
+                     BigDecimal grossWeightKg, BigDecimal netWeightKg, BigDecimal volumeCbm,
+                     List<Item> items, String customerId, String customerName,
+                     String orderType, List<PalletSnapshot> pallets, String destinationType) {
+            this(sourceInboundId, rootInboundId, sourceOrderId, sourceOrderNo, rootOrderId,
+                inboundCode, destinationWarehouseId, destinationWarehouseCode,
+                destinationWarehouseName, packageCount, productQuantity, palletCount,
+                grossWeightKg, netWeightKg, volumeCbm, null, items, customerId, customerName,
+                orderType, pallets, destinationType);
+        }
     }
 
     public record Item(

common-event-contract/src/main/resources/openapi/cross-region-events-v1.yaml

@@ -7,7 +7,7 @@ components:
   schemas:
     FirstLegLoadingPlanCompletedV2:
       type: object
-      required: [loadingPlanId, containerBookingId, orders]
+      required: [loadingPlanId, containerBookingId, estimatedPortArrivalAt, actualPortArrivalAt, estimatedWarehouseArrivalAt, orders]
       properties:
         loadingPlanId: {type: string}
         containerBookingId: {type: string}
@@ -15,12 +15,15 @@ components:
         cabinetNo: {type: string}
         warehouseId: {type: string}
         warehouseName: {type: string}
+        estimatedPortArrivalAt: {type: [string, 'null'], format: local-date-time, description: Frozen source-local estimated port arrival; null when Firstleg has no fact}
+        actualPortArrivalAt: {type: [string, 'null'], format: local-date-time, description: Frozen source-local actual port arrival; never copied from an estimate}
+        estimatedWarehouseArrivalAt: {type: [string, 'null'], format: local-date-time, description: Frozen source-local estimated warehouse arrival; null when Firstleg has no fact}
         orders:
           type: array
           items: {$ref: '#/components/schemas/FirstLegLoadingPlanCompletedOrderV2'}
     FirstLegLoadingPlanCompletedOrderV2:
       type: object
-      required: [sourceInboundId, customerId, customerName, packageCount, items, orderType, pallets, destinationType]
+      required: [sourceInboundId, customerId, customerName, palletCount, packageCount, productQuantity, volumeCbm, volumeWeightKg, items, orderType, pallets, destinationType]
       properties:
         sourceInboundId: {type: string}
         sourceOrderId: {type: string}
@@ -29,6 +32,10 @@ components:
         customerId: {type: string, minLength: 1, description: Trusted customer identity frozen by Firstleg}
         customerName: {type: string, minLength: 1, maxLength: 128, description: Immutable trusted container/customer name snapshot; consumers must not query domestic IAM}
         packageCount: {type: integer, minimum: 1}
+        productQuantity: {type: [integer, 'null'], minimum: 0, description: Final loaded product quantity; null when unavailable}
+        palletCount: {type: [integer, 'null'], minimum: 1, description: Distinct physical pallet count from Firstleg allocation pallet identity; never a planned zero placeholder}
+        volumeCbm: {type: [number, 'null'], minimum: 0, description: Final loaded volume in cubic metres}
+        volumeWeightKg: {type: [number, 'null'], minimum: 0, description: Sum of final loaded item dimensional weight facts; null when unavailable}
         items: {type: array, items: {type: object}}
         orderType: {type: string, enum: [FIRST_LEG, ONE_CLICK_DROPSHIP]}
         pallets: {type: array, items: {type: object}}

common-event-contract/src/test/java/com/baiyue/common/event/FirstLegLoadingPlanCompletedV1Test.java

@@ -52,13 +52,20 @@ class FirstLegLoadingPlanCompletedV1Test {
     void legacyParserRetainsDestinationTypeWhenV2OrderCarriesIt() throws Exception {
         String json = """
             {"loadingPlanId":"1","planNo":"LP-1","containerBookingId":"2","containerNo":"CONT-1",
-             "warehouseId":"3","warehouseName":"海外仓","orders":[{"sourceInboundId":"100",
-             "destinationWarehouseId":"3","packageCount":1,"items":[],"customerId":"9001",
+             "warehouseId":"3","warehouseName":"海外仓","estimatedPortArrivalAt":"2026-09-30T12:00",
+             "actualPortArrivalAt":null,"estimatedWarehouseArrivalAt":"2026-10-03T09:00",
+             "orders":[{"sourceInboundId":"100","destinationWarehouseId":"3","packageCount":1,
+             "palletCount":2,"volumeWeightKg":12.500,"items":[],"customerId":"9001",
              "customerName":"客户甲","destinationType":"OVERSEAS"}]}
             """;
 
         FirstLegLoadingPlanCompletedV1 restored = mapper.readValue(json, FirstLegLoadingPlanCompletedV1.class);
 
         assertThat(restored.orders().get(0).destinationType()).isEqualTo("OVERSEAS");
+        assertThat(restored.estimatedPortArrivalAt()).isEqualTo("2026-09-30T12:00");
+        assertThat(restored.actualPortArrivalAt()).isNull();
+        assertThat(restored.estimatedWarehouseArrivalAt()).isEqualTo("2026-10-03T09:00");
+        assertThat(restored.orders().get(0).palletCount()).isEqualTo(2);
+        assertThat(restored.orders().get(0).volumeWeightKg()).isEqualByComparingTo("12.500");
     }
 }

common-event-contract/src/test/java/com/baiyue/common/event/FirstLegLoadingPlanCompletedV2Test.java

@@ -4,12 +4,35 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.Test;
 
 import java.util.List;
+import java.math.BigDecimal;
 import java.nio.charset.StandardCharsets;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 class FirstLegLoadingPlanCompletedV2Test {
+    @Test
+    void carriesOnlyFrozenContainerTimesAndActualOrderAggregates() {
+        var order = new FirstLegLoadingPlanCompletedV2.Order(
+            "2", "2", "3", "ORD", "3", "RK", null, "ONT8", "ONT8",
+            12, 120, 3, null, null, new BigDecimal("2.500"), new BigDecimal("18.750"),
+            List.of(), "11", "客户甲", "FIRST_LEG", List.of(), "OVERSEAS");
+        var payload = new FirstLegLoadingPlanCompletedV2(
+            "4", "P", "5", "CONT", "CAB", "6", "WH",
+            "2026-09-30T12:00", null, "2026-10-03T09:00", List.of(order));
+
+        var json = new ObjectMapper().valueToTree(payload);
+
+        assertThat(json.at("/estimatedPortArrivalAt").asText()).isEqualTo("2026-09-30T12:00");
+        assertThat(json.at("/actualPortArrivalAt").isNull()).isTrue();
+        assertThat(json.at("/estimatedWarehouseArrivalAt").asText()).isEqualTo("2026-10-03T09:00");
+        assertThat(json.at("/orders/0/palletCount").asInt()).isEqualTo(3);
+        assertThat(json.at("/orders/0/packageCount").asInt()).isEqualTo(12);
+        assertThat(json.at("/orders/0/productQuantity").asInt()).isEqualTo(120);
+        assertThat(json.at("/orders/0/volumeCbm").decimalValue()).isEqualByComparingTo("2.500");
+        assertThat(json.at("/orders/0/volumeWeightKg").decimalValue()).isEqualByComparingTo("18.750");
+    }
+
     @Test
     void carriesTheThreeItemRemarks() throws Exception {
         var item = new FirstLegLoadingPlanCompletedV2.Item("1", "SKU", "中文", "EN", 1,
@@ -92,6 +115,8 @@ class FirstLegLoadingPlanCompletedV2Test {
             .contains("required: [sourceInboundId, customerId, customerName")
             .contains("customerId: {type: string, minLength: 1")
             .contains("customerName: {type: string, minLength: 1, maxLength: 128")
-            .contains("consumers must not query domestic IAM");
+            .contains("consumers must not query domestic IAM")
+            .contains("estimatedPortArrivalAt", "actualPortArrivalAt", "estimatedWarehouseArrivalAt")
+            .contains("palletCount", "volumeWeightKg", "never a planned zero placeholder");
     }
 }