openapi: 3.0.3
info:
  title: Phase 3 Domestic Outbound Dispatch API
  version: 1.0.0
paths:
  /api/platform/v1/first-leg/outbound-dispatches:
    get:
      summary: Query outbound aggregates by order, inbound or container
      parameters:
        - {$ref: '#/components/parameters/OrderId'}
        - {$ref: '#/components/parameters/InboundId'}
        - {$ref: '#/components/parameters/ContainerBookingId'}
      responses:
        '200':
          description: Business envelope containing matching aggregates, each with stable cabinetNo and real containerNo
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: {type: array, items: {$ref: '#/components/schemas/Aggregate'}}
  /api/platform/v1/first-leg/outbound-dispatches/detail:
    get:
      summary: Query one aggregate and its unified timeline
      parameters:
        - {$ref: '#/components/parameters/OrderId'}
        - {$ref: '#/components/parameters/InboundId'}
        - {$ref: '#/components/parameters/ContainerBookingId'}
      responses:
        '200':
          description: Business envelope containing aggregate detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      aggregate: {$ref: '#/components/schemas/Aggregate'}
  /api/platform/v1/first-leg/outbound-dispatches/check-gate:
    get:
      summary: Evaluate the fail-closed domestic outbound gate
      parameters:
        - {$ref: '#/components/parameters/OrderId'}
        - {$ref: '#/components/parameters/InboundId'}
        - {$ref: '#/components/parameters/ContainerBookingId'}
      responses:
        '200': {description: Business envelope containing every gate item}
  /api/platform/v1/first-leg/outbound-dispatches/confirm-dispatch:
    post:
      summary: Confirm domestic dispatch and enter WAITING_FOR_LOADING
      parameters:
        - {$ref: '#/components/parameters/IdempotencyKey'}
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}
      responses:
        '200': {description: Business envelope; gate or version failures use business error code}
  /api/platform/v1/first-leg/outbound-dispatches/reverse-dispatch:
    post:
      summary: Reverse WAITING_FOR_LOADING only before maritime tracking starts
      description: Once an actual DEPARTED_WAREHOUSE node exists, reversal is rejected with business code A0409 so READY_FOR_DISPATCH cannot coexist with maritime tracking.
      parameters:
        - {$ref: '#/components/parameters/IdempotencyKey'}
      requestBody:
        required: true
        content:
          application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}
      responses:
        '200': {description: Business envelope containing reverted aggregate}
components:
  parameters:
    OrderId: {name: orderId, in: query, schema: {type: integer, format: int64, minimum: 1}}
    InboundId: {name: inboundId, in: query, schema: {type: integer, format: int64, minimum: 1}}
    ContainerBookingId: {name: containerBookingId, in: query, schema: {type: integer, format: int64, minimum: 1}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
  schemas:
    Aggregate:
      type: object
      required: [orderId, orderNo, inboundId, inboundCode, tenantId, inboundStatus, containerBookingId, cabinetNo, loadingPlanId, loadingPlanStatus, dispatchStatus, version, gate]
      properties:
        orderId: {type: integer, format: int64}
        orderNo: {type: string}
        inboundId: {type: integer, format: int64}
        inboundCode: {type: string}
        tenantId: {type: integer, format: int64}
        customerId: {type: integer, format: int64, nullable: true}
        customerName: {type: string, nullable: true}
        inboundStatus: {type: string}
        containerBookingId: {type: integer, format: int64}
        cabinetNo: {type: string, description: 稳定柜次号}
        containerNo: {type: string, nullable: true, description: 真实集装箱号}
        loadingPlanId: {type: integer, format: int64}
        loadingPlanStatus: {type: string}
        pickTaskId: {type: integer, format: int64, nullable: true}
        pickTaskStatus: {type: string, nullable: true}
        oceanBookingId: {type: integer, format: int64, nullable: true}
        oceanBookingStatus: {type: string, nullable: true}
        truckAppointmentId: {type: integer, format: int64, nullable: true}
        truckAppointmentStatus: {type: string, nullable: true}
        dispatchStatus: {type: string}
        version: {type: integer, minimum: 0}
        gate: {type: object}
    ActionRequest:
      type: object
      required: [inboundId, containerBookingId, expectedVersion]
      properties:
        inboundId: {type: integer, format: int64, minimum: 1}
        containerBookingId: {type: integer, format: int64, minimum: 1}
        expectedVersion: {type: integer, minimum: 0}
        remark: {type: string, maxLength: 500}