# 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):

```json
{
  "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:

```javascript
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:

```json
{
  "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