init push

docs/file-manager-base-upload-create.md

@@ -0,0 +1,62 @@
+# File Manager Base Image Flow
+
+This document explains upload + create flow specifically for base images.
+
+## Purpose
+
+This flow uploads base images and persists file metadata into a forced folder hierarchy:
+
+- `__system_root_files__ > bases > <base-type> > <base-name>`
+
+Main differences compared to regular file flow:
+
+- dedicated upload endpoint: `POST /api/v1/file-manager/files/upload-base-image`
+- dedicated create endpoint: `POST /api/v1/file-manager/files/create-base-image`
+- `content_type` must be `image/*`
+- `base_uuid` is required in the create request per item
+- create step performs hard replace of existing files in target folder before creating new file
+
+## Step 1 - Request Upload Intent (Base)
+
+Endpoint:
+
+- `POST /api/v1/file-manager/files/upload-base-image`
+
+Validation highlights:
+
+- `type` must be `file_manager_file_upload_intent`
+- `name` required
+- `content_type` required and must start with `image/`
+- `size_bytes >= 0`
+
+## Step 2 - Upload Binary to Object Storage
+
+For each successful intent, frontend uploads binary with `PUT` to `upload_url`.
+
+## Step 3 - Create File Record (Base)
+
+Endpoint:
+
+- `POST /api/v1/file-manager/files/create-base-image`
+
+Validation highlights:
+
+- `type` must be `file_manager_file_create` or `file_manager_file`
+- `upload_intent_uuid` required and valid UUID
+- `base_uuid` required and valid UUID
+- `name` required
+
+Backend behavior:
+
+1. load base from `base_uuid`
+2. resolve `base-type` from base category (e.g. `hems` or `regular`)
+3. resolve/create folder path `__system_root_files__ > bases > <base-type> > <base-name>`
+4. hard replace: delete + purge all existing files in that target folder
+5. create file node from upload intent
+
+Hard replace cleanup target:
+
+- file row in DB
+- original object in S3
+- thumbnail object in S3 (if exists)
+- related attachment metadata