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

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