baiyue-firstleg/firstleg/src/main/resources/openapi/phase3-loading-model-bridge-v1.yaml

openapi: 3.0.3
info:
  title: Phase 3 Preload and Container Loading Bridge API
  version: 1.0.0
  description: The container loading plan is created atomically with the container. Adding an inbound allocation creates its preload aggregate and link in the same transaction while loadingPlan=EDITING or LOADING; plan confirmation remains the gate before PDA task creation.
paths:
  /api/platform/v1/inbounds/{inboundId}/preload/loading-plans:
    get:
      summary: Query all container loading plans linked to one inbound preload
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
      responses:
        '200': {description: Business envelope containing zero or more stable links}
  /api/platform/v1/inbounds/{inboundId}/preload/loading-plans/{loadingPlanId}:
    post:
      summary: Atomically link an inbound preload and a container loading plan
      description: Both optimistic-lock versions must match; either conflict rolls back the whole link operation. This endpoint never permits post-hoc binding after the loading plan enters LOADING.
      parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/LoadingPlanId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/BindRequest'}}
      responses:
        '200': {description: Business envelope containing the persisted link or a business conflict}
  /api/platform/v1/first-leg/smart-loading/plans/{loadingPlanId}/preloads:
    get:
      summary: Query all inbound preloads linked to one container loading plan
      parameters: [{$ref: '#/components/parameters/LoadingPlanId'}]
      responses:
        '200': {description: Business envelope containing links across authorized customers}
components:
  parameters:
    InboundId: {name: inboundId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
    LoadingPlanId: {name: loadingPlanId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
    TenantId: {name: tenantId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
  schemas:
    BindRequest:
      type: object
      required: [expectedPreloadVersion, expectedLoadingPlanVersion]
      properties:
        expectedPreloadVersion: {type: integer, minimum: 0}
        expectedLoadingPlanVersion: {type: integer, minimum: 0}
    Link:
      type: object
      required: [id, tenantId, inboundId, preloadPlanId, preloadStatus, preloadVersion, loadingPlanId, containerBookingId, loadingPlanStatus, loadingPlanVersion, allocatedPackageCount, linkedAt]
      properties:
        id: {type: integer, format: int64}
        tenantId: {type: integer, format: int64}
        inboundId: {type: integer, format: int64}
        preloadPlanId: {type: integer, format: int64}
        preloadStatus: {type: string, enum: [PENDING, CONFIRMING, CONFIRMED]}
        preloadVersion: {type: integer, minimum: 0}
        loadingPlanId: {type: integer, format: int64}
        containerBookingId: {type: integer, format: int64}
        containerNo: {type: string, nullable: true}
        loadingPlanStatus: {type: string, enum: [EDITING, LOADING, COMPLETED]}
        loadingPlanVersion: {type: integer, minimum: 0}
        allocatedPackageCount: {type: integer, minimum: 1}
        linkedAt: {type: string, format: date-time}