openapi: 3.0.3
info:
  title: Truck Appointment API
  version: 1.1.0
paths:
  /api/platform/v1/truck-appointments:
    get:
      summary: Query truck appointments
      responses:
        '200': {description: Paged truck appointments}
    post:
      summary: Create a truck appointment linked to a released ocean booking
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SaveRequest'}
      responses:
        '200': {description: Created appointment}
  /api/platform/v1/truck-appointments/{id}:
    parameters: [{$ref: '#/components/parameters/AppointmentId'}]
    get:
      summary: Query a truck appointment
      responses:
        '200': {description: Appointment detail}
    put:
      summary: Update an editable truck appointment with optimistic locking
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SaveRequest'}
      responses:
        '200': {description: Updated appointment}
  /api/platform/v1/truck-appointments/{id}/{action}:
    parameters:
      - {$ref: '#/components/parameters/AppointmentId'}
      - {$ref: '#/components/parameters/Action'}
      - {$ref: '#/components/parameters/IdempotencyKey'}
      - {$ref: '#/components/parameters/RequestHash'}
    post:
      summary: Apply an idempotent appointment lifecycle action
      description: ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ActionRequest'}
      responses:
        '200': {description: Updated or replayed appointment}
  /api/platform/v1/truck-appointments/{id}/reschedule:
    parameters:
      - {$ref: '#/components/parameters/AppointmentId'}
      - {$ref: '#/components/parameters/IdempotencyKey'}
      - {$ref: '#/components/parameters/RequestHash'}
      - name: plannedLoadingAt
        in: query
        required: true
        schema: {type: string, format: date-time}
    post:
      summary: Idempotently reschedule an appointment
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ActionRequest'}
      responses:
        '200': {description: Rescheduled or replayed appointment}
  /api/platform/v1/truck-appointments/{id}/history:
    parameters: [{$ref: '#/components/parameters/AppointmentId'}]
    get:
      summary: Query immutable appointment status history
      responses:
        '200': {description: History entries including action, from/to status, operator, reason and time}
  /api/platform/v1/truck-appointments/{id}/attachments:
    parameters: [{$ref: '#/components/parameters/AppointmentId'}]
    get:
      summary: Query attachment references owned by the appointment
      responses:
        '200': {description: Attachment references}
    post:
      summary: Reference a file already owned by the appointment customer and business scope
      responses:
        '200': {description: Created attachment reference}
  /api/platform/v1/truck-appointments/{id}/attachments/upload:
    parameters: [{$ref: '#/components/parameters/AppointmentId'}]
    post:
      summary: Upload and reference a truck appointment attachment
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                attachmentType: {type: string, maxLength: 32}
                file: {type: string, format: binary}
      responses:
        '200': {description: Uploaded attachment reference}
  /api/platform/v1/truck-appointments/{id}/attachments/{attachmentId}:
    parameters:
      - {$ref: '#/components/parameters/AppointmentId'}
      - {$ref: '#/components/parameters/AttachmentId'}
    delete:
      summary: Delete an attachment reference owned by the appointment
      responses:
        '200': {description: Reference deleted}
components:
  parameters:
    AppointmentId: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
    AttachmentId: {name: attachmentId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
    Action:
      name: action
      in: path
      required: true
      schema:
        type: string
        enum: [SUBMIT, DISPATCH, PICKUP, ARRIVE, LOAD, DEPART, COMPLETE, EXCEPTION, CANCEL]
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
    RequestHash: {name: X-Request-Hash, in: header, required: false, schema: {type: string, pattern: '^[0-9a-fA-F]{64}$'}}
  schemas:
    ActionRequest:
      type: object
      required: [expectedVersion]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        reason: {type: string, maxLength: 500}
    SaveRequest:
      type: object
      required: [oceanBookingId, plannedLoadingAt, expectedVersion]
      properties:
        oceanBookingId: {type: integer, format: int64, minimum: 1}
        containerBookingId: {type: integer, format: int64, minimum: 1}
        loadingPlanId: {type: integer, format: int64, minimum: 1}
        plannedLoadingAt: {type: string, format: date-time}
        expectedVersion: {type: integer, minimum: 0}