144 lines
4.1 KiB
Markdown
144 lines
4.1 KiB
Markdown
# 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
|