init push

2026-07-16 22:16:45 +07:00
commit 8b068bdb10
1021 changed files with 332816 additions and 0 deletions
--- a/docs/file-manager-aircraft-upload-create.md
+++ b/docs/file-manager-aircraft-upload-create.md
@@ -0,0 +1,143 @@
+# 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