fm_be/docs/takeover-file-api.md

Takeover File API

Dokumen ini menjelaskan alur lengkap file pada takeover:

1. upload intent file
2. finalize upload menjadi file manager file tanpa parent takeover
3. create takeover baru sambil menempelkan file pakai file_id
4. update takeover dengan mode add, remove, atau replace file
5. response takeover dan FM report yang menampilkan file
6. SSE yang tetap dipakai dari file manager

Ringkasan Konsep

Ada 3 objek yang perlu dibedakan:

1. file
   • file fisik di file manager
2. attachment
   • relasi file ke reference bisnis, misalnya takeover
3. takeover_file
   • relasi khusus takeover ke file_attachment_id

Flow yang dipakai di sistem ini:

1. FE minta upload intent ke file manager
2. FE upload binary file ke storage
3. FE finalize file lewat endpoint takeover file dan menerima file_id
4. FE kirim file_id saat create/update takeover
5. Backend membuat attachment ref_type = takeover
6. Backend menyimpan relasi takeover file

Endpoint Yang Dipakai

File Manager

Request upload intent untuk takeover

POST /api/v1/file-manager/files/upload-takeover-file

Fungsi:

1. minta upload intent
2. dapat upload_intent_uuid
3. dapat upload_url

Finalize file takeover

POST /api/v1/file-manager/files/create-takeover-file

Fungsi:

1. finalize file dari upload intent
2. membuat file manager file node
3. mengembalikan file_id untuk dipakai di takeover create/update

Endpoint ini tidak membuat attachment dan tidak membuat row takeover_files.

Catatan:

• takeover_uuid tidak wajib
• file boleh sementara tanpa parent takeover
• attachment takeover baru dibuat saat POST /api/v1/takeovers/create atau PATCH /api/v1/takeovers/update/{id}

Takeover

Create takeover baru

POST /api/v1/takeovers/create

Update takeover

PATCH /api/v1/takeovers/update/{id}

Flow Create Takeover Dengan File

1. FE minta upload intent file

Pakai endpoint:

POST /api/v1/file-manager/files/upload-takeover-file

Contoh payload:

{
  "data": [
    {
      "type": "file_manager_file_upload_intent",
      "attributes": {
        "name": "takeover-report.pdf",
        "content_type": "application/pdf",
        "size_bytes": 123456
      }
    }
  ]
}

Response akan mengembalikan:

1. upload_intent_uuid
2. upload_url
3. method
4. required_headers

2. FE upload binary ke storage

Gunakan upload_url dan method dari response upload intent.

3. FE finalize upload menjadi file manager file

Pakai endpoint:

POST /api/v1/file-manager/files/create-takeover-file

Contoh payload:

{
  "data": [
    {
      "type": "file_manager_file_create",
      "attributes": {
        "upload_intent_uuid": "019e8713-aa19-7fb7-a510-a0332dc69697",
        "name": "takeover-report.pdf"
      }
    }
  ]
}

Response akan mengembalikan file manager resource. Ambil data[0].resource.id sebagai file_id.

Contoh potongan response:

{
  "data": [
    {
      "index": 0,
      "success": true,
      "resource": {
        "type": "file_manager_file",
        "id": "019e8714-1111-7aaa-8bbb-222222222222",
        "attributes": {
          "name": "takeover-report.pdf"
        }
      }
    }
  ]
}

4. FE kirim takeover create

Pakai endpoint:

POST /api/v1/takeovers/create

Field file yang didukung:

data.attributes.files[]

Struktur item:

{
  "file_id": "019e8714-1111-7aaa-8bbb-222222222222"
}

Contoh payload:

{
  "data": {
    "type": "takeover_create",
    "attributes": {
      "base_id": "019d6771-5fb5-7337-837f-bc5ed85181a1",
      "duty_date": "2026-06-22",
      "notes": "Takeover baru dengan file",
      "files": [
        {
          "file_id": "019e8714-1111-7aaa-8bbb-222222222222"
        }
      ]
    }
  }
}

5. Backend attach file ke takeover

Saat request create takeover diproses, backend akan:

1. membuat takeover
2. membaca file_id dari data.attributes.files[]
3. create attachment dengan ref_type = takeover
4. menyimpan relasi ke takeover_files

Catatan kompatibilitas:

• item lama dengan upload_intent_uuid masih didukung sebagai fallback
• flow baru yang disarankan adalah kirim file_id

Flow Update Takeover Dengan File

Pakai endpoint:

PATCH /api/v1/takeovers/update/{id}

Ada 3 mode yang disarankan.

Mode 1. Add file baru

Gunakan:

• files
• atau files_add

Keduanya menerima item yang sama:

{
  "file_id": "019e8714-3333-7aaa-8bbb-444444444444"
}

Contoh:

{
  "data": {
    "type": "takeover_update",
    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
    "attributes": {
      "notes": "Tambah file baru",
      "files_add": [
        {
          "file_id": "019e8714-3333-7aaa-8bbb-444444444444"
        }
      ]
    }
  }
}

Mode 2. Remove file tertentu

Gunakan:

files_remove

Isi field ini adalah file_attachment_id, bukan takeover_file.id.

Contoh:

{
  "data": {
    "type": "takeover_update",
    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
    "attributes": {
      "files_remove": [
        "019d7000-aaaa-7bbb-8ccc-222222222222"
      ]
    }
  }
}

Saat remove:

1. relasi takeover_files dihapus
2. attachment file-manager juga dihapus
3. file lifecycle ikut direconcile oleh file manager

Mode 3. Replace semua file

Gunakan:

files_replace

Mode ini:

1. menghapus semua file lama dari takeover
2. menambahkan daftar file baru

Aturan:

1. files_replace tidak boleh digabung dengan files
2. files_replace tidak boleh digabung dengan files_add
3. files_replace tidak boleh digabung dengan files_remove

Contoh:

{
  "data": {
    "type": "takeover_update",
    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
    "attributes": {
      "files_replace": [
        {
          "file_id": "019e8714-5555-7aaa-8bbb-666666666666"
        }
      ]
    }
  }
}

Mode campuran: add + remove

Kalau kamu ingin menambah file baru sambil menghapus file lama, pakai:

1. files_add
2. files_remove

Contoh:

{
  "data": {
    "type": "takeover_update",
    "id": "019eed5d-36c2-72d9-acab-388b4e41a949",
    "attributes": {
      "files_add": [
        {
          "file_id": "019e8714-7777-7aaa-8bbb-888888888888"
        }
      ],
      "files_remove": [
        "019d7000-aaaa-7bbb-8ccc-222222222222"
      ]
    }
  }
}

Validation Rules

Create takeover

Field yang wajib:

1. duty_date

Field file:

1. files[] opsional
2. untuk flow baru, setiap item file berisi:
   • file_id

Catatan:

• upload_intent_uuid + name masih bisa dipakai sebagai fallback lama
• untuk flow baru, gunakan file_id dari response /create-takeover-file

Update takeover

Field file yang tersedia:

1. files
2. files_add
3. files_remove
4. files_replace

Aturan kombinasi:

1. files_replace eksklusif
2. files dan files_add diperlakukan sebagai add file baru
3. files_remove harus berisi UUID attachment yang masih terhubung ke takeover

Response Takeover

Response takeover sekarang punya field:

data.attributes.files

Contoh item:

{
  "type": "takeover_file",
  "id": "019d7000-aaaa-7bbb-8ccc-111111111111",
  "attributes": {
    "file_attachment_id": "019d7000-aaaa-7bbb-8ccc-222222222222",
    "file_name": "takeover-report.pdf",
    "download_url": "https://..."
  }
}

Arti field:

1. id
   • UUID relasi takeover_file
2. file_attachment_id
   • UUID attachment file-manager
3. file_name
   • nama file yang tersimpan
4. download_url
   • URL download file jika storage tersedia

Response FM Report

Response fm report juga menampilkan file takeover melalui:

data.attributes.takeover_files

Isi resource sama seperti response takeover:

1. id
2. file_attachment_id
3. file_name
4. download_url

SSE

Flow takeover file tetap memakai SSE file manager yang sudah ada.

Event utama:

file.updated

Artinya saat file berhasil difinalisasi atau status file berubah, FE tetap bisa mendengarkan event realtime dari stream file manager.

Endpoint stream:

GET /api/v1/file-manager/events

Catatan:

1. belum ada stream SSE takeover-file khusus
2. yang dipakai adalah stream file manager yang sudah eksisting

Migration dan Struktur Database

Tabel baru:

takeover_files

Kolom:

1. id
2. takeover_id
3. file_attachment_id

Migration:

migrations/20260622_create_takeover_files.sql

Best Practice Pemakaian

1. Finalize upload dulu lewat /api/v1/file-manager/files/create-takeover-file
2. Kalau takeover sudah ada, gunakan PATCH /api/v1/takeovers/update/{id}
3. Pakai files_replace hanya kalau memang ingin mengganti semua file
4. Pakai files_add dan files_remove kalau ingin perubahan parsial yang lebih aman
5. Untuk menghapus file, gunakan file_attachment_id dari response takeover

Contoh Alur Yang Disarankan

Create takeover baru dengan 1 file

1. request upload intent
2. upload binary ke storage
3. panggil POST /api/v1/file-manager/files/create-takeover-file
4. ambil file_id dari response
5. panggil POST /api/v1/takeovers/create dengan files[].file_id

Update takeover dan tambah file baru

1. request upload intent
2. upload binary ke storage
3. panggil POST /api/v1/file-manager/files/create-takeover-file
4. ambil file_id dari response
5. panggil PATCH /api/v1/takeovers/update/{id} dengan files_add[].file_id

Update takeover dan replace semua file

1. request upload intent baru untuk file pengganti
2. upload binary ke storage
3. panggil POST /api/v1/file-manager/files/create-takeover-file
4. ambil file_id dari response
5. panggil PATCH /api/v1/takeovers/update/{id} dengan files_replace[].file_id