feat: enforce canonical container identity across regions

2026-08-31 12:13:20 +08:00
parent b386f35ab4
commit 942dbace19
78 changed files with 1203 additions and 730 deletions
@@ -7,11 +7,11 @@ components:
  schemas:
    FirstLegLoadingPlanCompletedV2:
      type: object
-      required: [loadingPlanId, containerBookingId, estimatedPortArrivalAt, actualPortArrivalAt, estimatedWarehouseArrivalAt, orders]
+      required: [loadingPlanId, sourceContainerBookingId, containerNo, estimatedPortArrivalAt, actualPortArrivalAt, estimatedWarehouseArrivalAt, orders]
      properties:
        loadingPlanId: {type: string}
-        containerBookingId: {type: string}
-        containerNo: {type: string}
+        sourceContainerBookingId: {type: string, minLength: 1, description: Immutable Firstleg container booking identity}
+        containerNo: {type: string, minLength: 1, description: Uppercase normalized physical container number frozen before loading completion publication}
        cabinetNo: {type: string}
        warehouseId: {type: string}
        warehouseName: {type: string}
@@ -40,3 +40,29 @@ components:
        orderType: {type: string, enum: [FIRST_LEG, ONE_CLICK_DROPSHIP]}
        pallets: {type: array, items: {type: object}}
        destinationType: {type: string, enum: [FBA, OVERSEAS]}
+    FirstLegContainerShippingNodeRecordedV1:
+      type: object
+      required: [queryId, customerId, oceanBookingId, sourceContainerBookingId, containerNo, standardNode, nodeSequence, observedAt, actualAt, providerCode, providerEventId, providerNodeCode, rawPayloadHash]
+      properties:
+        queryId: {type: string}
+        customerId: {type: string}
+        oceanBookingId: {type: string}
+        sourceContainerBookingId: {type: string, minLength: 1}
+        containerNo: {type: string, minLength: 1, description: Uppercase normalized physical container number; never cabinetNo or a technical identity}
+        standardNode: {type: string}
+        nodeSequence: {type: integer}
+        observedAt: {type: string, format: date-time}
+        actualAt: {type: string, format: date-time}
+        providerCode: {type: string}
+        providerEventId: {type: string}
+        providerNodeCode: {type: string}
+        rawPayloadHash: {type: string, pattern: '^[0-9a-fA-F]{64}$'}
+    OverseasContainerUnloadedV1:
+      type: object
+      required: [sourceContainerBookingId, containerNo, unloadingCompletedAt, unloadingPhotoUploadedAt]
+      properties:
+        sourceContainerBookingId: {type: string, minLength: 1}
+        containerNo: {type: string, minLength: 1, description: Must equal the immutable normalized Firstleg container number; the CN consumer never overwrites it}
+        unloadingCompletedAt: {type: string, format: date-time}
+        unloadingPhotoUploadedAt: {type: string, format: date-time}
+        actualEmptyReportedAt: {type: [string, 'null'], format: date-time}