# 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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Contoh payload:

```json
{
  "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:

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

Contoh:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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`