484 lines
9.5 KiB
Markdown
484 lines
9.5 KiB
Markdown
# 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`
|