init push
This commit is contained in:
483
docs/takeover-file-api.md
Normal file
483
docs/takeover-file-api.md
Normal file
@@ -0,0 +1,483 @@
|
||||
# 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`
|
||||
Reference in New Issue
Block a user