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

openapi: 3.1.0
info:
  title: Baiyue Cross-region Event Contracts
  version: 1.0.0
paths: {}
components:
  schemas:
    FirstLegLoadingPlanCompletedV2:
      type: object
      required: [loadingPlanId, sourceContainerBookingId, containerNo, estimatedPortArrivalAt, actualPortArrivalAt, estimatedWarehouseArrivalAt, orders]
      properties:
        loadingPlanId: {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}
        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, palletCount, packageCount, productQuantity, volumeCbm, volumeWeightKg, items, orderType, pallets, destinationType]
      properties:
        sourceInboundId: {type: string}
        sourceOrderId: {type: string}
        sourceOrderNo: {type: string}
        inboundCode: {type: string}
        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}}
        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}