fm_be/docs/file-manager-aircraft-upload-create.md

File Manager Aircraft Image Flow

This document explains the upload + create flow specifically for aircraft images.

Purpose

This flow is used to upload aircraft images (drag-and-drop) and persist file metadata into a forced folder hierarchy based on the aircraft designation.

Main differences compared to the regular file flow:

• dedicated upload endpoint: POST /api/v1/file-manager/files/upload-aircraft-image
• dedicated create endpoint: POST /api/v1/file-manager/files/create-aircraft-image
• content_type must be image/*
• target folder is forced to: __system_root_files__ > aircraft > <aircraft designation>
• aircraft_uuid is required in the create request per item

Prerequisites

1. User is logged in and has file_manager.create permission.
2. Frontend has per-file data: name, content_type, size_bytes, and binary file.

Step 1 - Request Upload Intent (Aircraft)

Endpoint:

• POST /api/v1/file-manager/files/upload-aircraft-image

Request body (bulk, minimum 1 item):

{
  "data": [
    {
      "type": "file_manager_file_upload_intent",
      "attributes": {
        "name": "aircraft-front.jpg",
        "content_type": "image/jpeg",
        "size_bytes": 42170
      }
    }
  ]
}

Important validation rules in this endpoint:

• data must be an array
• type must be file_manager_file_upload_intent
• name is required
• content_type is required and must start with image/
• size_bytes >= 0

Per-item response (partial success is possible), FE receives:

• upload_intent_uuid
• upload_url
• method (PUT)
• required_headers
• object info (bucket, key)
• expires_at, expires_in_seconds

Step 2 - Upload Binary Directly to Object Storage

For each item with success: true from step 1:

1. take upload_url
2. perform PUT binary file to that URL
3. send headers according to required_headers

Example:

await fetch(upload_url, {
  method: "PUT",
  headers: {
    "Content-Type": file.type
  },
  body: file
});

Notes:

• 1 file = 1 PUT request
• parallel upload is allowed with a concurrency limit
• files that fail PUT must not be sent to the create step

Step 3 - Create File Record (Aircraft)

Endpoint:

• POST /api/v1/file-manager/files/create-aircraft-image

Request body:

{
  "data": [
    {
      "type": "file_manager_file_create",
      "attributes": {
        "upload_intent_uuid": "019d8215-c622-7576-86bd-3ddeecaf4867",
        "aircraft_uuid": "019d8215-c799-7209-9237-2e2f5d0f8709",
        "name": "aircraft-front.jpg"
      }
    }
  ]
}

Important validation rules:

• data must be an array
• type must be file_manager_file_create or file_manager_file
• upload_intent_uuid is required and must be a valid UUID
• aircraft_uuid is required and must be a valid UUID
• name is required

Aircraft-specific behavior:

• backend loads aircraft by aircraft_uuid and reads its designation
• backend resolves/creates folder hierarchy:
  • __system_root_files__ (system root)
  • aircraft under system root
  • <designation> under aircraft (example: OE-XHZ)
• final file is created inside <designation> folder
• folder_id from payload is ignored in this endpoint because folder is derived from aircraft designation

Step 4 - Backend Process During Create

For each valid item:

1. backend validates and loads aircraft from aircraft_uuid
2. backend resolves/creates __system_root_files__ > aircraft > <designation>
3. backend validates uploaded object from upload_intent_uuid
4. backend creates file node in <designation> folder
5. file status enters normal file manager lifecycle (uploaded -> processing -> validated -> ready or failed)

Status Codes

• 201: all create items succeed
• 207: partial success (mixed success and failure)
• 404: aircraft not found (per-item in bulk response)
• 422: payload validation error
• 400: invalid JSON payload
• 503: aircraft service unavailable

FE Integration Summary

1. call upload-aircraft-image
2. upload binary to storage via presigned URL
3. call create-aircraft-image only for items with successful PUT
4. store resulting file id for reference in aircraft module