# CHANGELOG Kontrak API v1

Setiap perubahan pada route, controller, FormRequest, JsonResource, `ApiResponse`, exception handler
API, atau middleware API dicatat di sini dalam task yang sama (CLAUDE.md 11.1). Entri terbaru di atas.

## Format Entri

```markdown
## YYYY-MM-DD

| Endpoint | Jenis | Ringkasan |
|---|---|---|
| `METHOD /path` | ADDED / CHANGED / REMOVED / BREAKING | apa yang berubah dan dampaknya bagi client |
```

| Jenis | Arti |
|---|---|
| `ADDED` | endpoint atau field baru; client lama tetap berjalan |
| `CHANGED` | perilaku berubah tanpa merusak client lama (mis. batas validasi melonggar, message berubah) |
| `REMOVED` | endpoint atau field dihapus |
| `BREAKING` | perubahan yang merusak client lama: field dihapus/diganti nama, tipe atau arti berubah, validasi mengetat |

Sebelum aplikasi rilis ke Play Store, `REMOVED` dan `BREAKING` masih boleh terjadi di v1. Setelah
rilis, keduanya hanya boleh terjadi di `/api/v2`.

---

## 2026-11-15

| Endpoint | Jenis | Ringkasan |
|---|---|---|
| `GET /announcements`, `GET /announcements/{announcement}` | ADDED | Pengumuman perusahaan untuk karyawan: daftar yang sedang tayang (disematkan di atas, maksimal 50) dengan `is_read`, dan detail yang sekaligus menandai dibaca. Pengumuman terjadwal, berakhir, atau milik perusahaan lain dijawab 404. Berkas [`announcements.md`](announcements.md) |
| `GET /me/config` | CHANGED | `modules.module_announcement` kini mengikuti paket (sebelumnya selalu `false`). Bentuk respons tidak berubah |
| `PUT /me/push-token`, `DELETE /me/push-token` | ADDED | Pendaftaran dan penghapusan token FCM untuk sesi login saat ini. Token push terikat ke token login dan ikut terhapus saat logout, ganti kata sandi, login ulang di perangkat yang sama, atau perangkat pinjaman berakhir; client wajib mendaftar ulang setiap login dan pada `onNewToken()`. Pengiriman push belum aktif. Berkas [`push-tokens.md`](push-tokens.md) |

---

## 2026-10-23

| Endpoint | Jenis | Ringkasan |
|---|---|---|
| `GET /approvals`, `GET /approvals/{approval}`, `POST /approvals/{approval}/approve`, `POST /approvals/{approval}/reject` | ADDED | Persetujuan pengajuan oleh penyetuju dari aplikasi. `GET /approvals` mengirim tahap yang menunggu keputusan karyawan login (`status=pending`, bawaan) atau riwayat keputusannya (`status=decided`), dapat disaring `type`. Item berisi `can_decide`, `requester`, dan `request` (objek modul lengkap). Tolak wajib `notes`; setujui menerima `notes` dan `approved_amount` (reimbursement, tahap terakhir). Keputusan sebagai Admin HR tetap hanya di panel. Berkas [`approvals.md`](approvals.md) |
| Seluruh endpoint pengajuan | CHANGED | `approvals[].notes` dan `decision_notes` kini dapat berisi sampai 1000 karakter (kolom `TEXT`); sebelumnya dibatasi kolom 255 karakter. Tipe tidak berubah |
| `GET`/`POST /attendance/corrections`, `GET`/`POST /leaves`, `GET /leaves/{leave}`, `POST /leaves/{leave}/cancel`, dan pasangan yang sama pada `/overtimes`, `/business-trips`, `/reimbursements` | ADDED | `approvals[].decided_by` (string, `null` selama belum diputuskan atau bila tahap `CANCELLED`): nama yang benar-benar memutuskan tahap. Berbeda dari `approver` bila Admin HR memutuskan menggantikan penyetuju lewat panel |
| Endpoint yang sama | CHANGED | Penyetuju kini disusun dari satu aturan untuk seluruh jenis pengajuan: Tahap 1 = Atasan Langsung, atau Kepala Departemen terdekat dari unit pemohon ke atas; Tahap 2 = penyetuju Tahap 1 untuk orang Tahap 1. Pemohon tidak pernah menjadi penyetujunya sendiri dan Tahap 1 ≠ Tahap 2. `approvals[].stage_name` untuk pengajuan baru bernilai `Tahap 1`, `Tahap 2`, atau `Admin HR` (sebelumnya nama tahap dari menu Jenjang Persetujuan, mis. `Atasan Langsung`); pengajuan lama tidak diubah. Alur bisa satu tahap. Tipe dan arti field tidak berubah. Lihat [alur persetujuan](attendance-corrections.md#alur-persetujuan) |
| `POST /attendance/corrections`, `POST /leaves`, `POST /overtimes`, `POST /business-trips`, `POST /reimbursements` | CHANGED | Karyawan tanpa penyetuju berjenjang kini mendapat satu tahap `Admin HR` dengan `approver` `null` dan message sukses biasa. Sebelumnya tahap-tahap dengan `approver` `null` dan message peringatan `Pengajuan tersimpan, tetapi penyetuju pada tahap ... belum ditentukan. Hubungi Admin HR.` |
| Endpoint `POST` yang sama | CHANGED | `message` sukses menyebut nama penyetuju Tahap 1 atau `Admin HR`, mis. `Pengajuan koreksi presensi terkirim dan menunggu persetujuan Anton Satu.` (sebelumnya `...menunggu persetujuan atasan langsung.`). Penolakan 422 `Jenjang persetujuan ... belum dikonfigurasi. Hubungi Admin HR.` dihapus karena tidak dapat terjadi lagi |

---

## 2026-10-22

| Endpoint | Jenis | Ringkasan |
|---|---|---|
| Seluruh route berlimiter (`POST /auth/login`, `POST /attendance/check-in`, `/check-out`, `POST /client-visits/check-in`, `/auth/lend/*`, `/auth/forgot-password`, `/auth/reset-password`, `GET /app/version`, `GET /companies/{slug}/branding`) | CHANGED | Respons 429 kini membawa header `Retry-After` (detik sampai kuota pulih) dan `X-RateLimit-Reset` (Unix timestamp), selain `X-RateLimit-Limit`/`X-RateLimit-Remaining`. Body tidak berubah |
| `GET /me/config` | ADDED | Blok `consent`: `policy_version`, `title`, `body` (teks polos, paragraf `\n`), `accepted`, `accepted_at` untuk karyawan login dan versi kebijakan aktif. Versi aktif pertama `2026-10`; teks awal **belum ditinjau tim legal** |
| `POST /consents` | CHANGED | `policy_version` wajib sama dengan versi aktif (`in`); versi lain dijawab 422 `errors.policy_version`. Body request dan bentuk respons sukses tidak berubah; aplikasi yang mengirim `2026-10` tetap diterima selama versi itu aktif |
| `GET /attendance/today` | ADDED | `check_in_opens_at` dan `check_out_closes_at` (ISO 8601 UTC, `null` bila tidak ada jadwal masuk) dari resolver yang sama dengan pemeriksaan `OUTSIDE_WINDOW`. Arti `can_check_in`/`can_check_out` tidak berubah: keduanya tetap tidak memeriksa jam |
| `GET /me/config` | CHANGED | `today.check_in_opens_at`/`check_out_closes_at` kini memperhitungkan pelebaran jendela dari lembur `BEFORE_SHIFT`/`AFTER_SHIFT` yang disetujui, sama dengan aturan yang ditegakkan. Contoh: lembur 17:00–20:00 pada jam kerja 08:00–17:00 → sebelumnya 06:30–19:00 WIB, kini 03:00–22:30 WIB. Tanpa lembur tersebut nilainya tidak berubah |
| `GET /me/config` | CHANGED | `modules.module_announcement` dan `modules.module_face_matching` kini selalu `false` selama endpoint-nya belum tersedia (sebelumnya `true` pada paket produksi). Kunci, tipe, dan arti tidak berubah; modul yang dirilis kelak akan kembali mengikuti paket |
| `GET /app/version` | ADDED | Endpoint publik tanpa token untuk layar pembuka: `latest_version_name`, `latest_version_code`, `minimum_version_code`, `store_url`, `message` per `platform`. Nilai dikelola di panel platform; platform yang belum diatur dijawab angka `0`. Limiter `api` 60/menit per IP. Berkas [`app-version.md`](app-version.md) |
| — | ADDED | Berkas modul [`attendance-corrections.md`](attendance-corrections.md), [`overtimes.md`](overtimes.md), [`leaves.md`](leaves.md), [`business-trips.md`](business-trips.md), [`reimbursements.md`](reimbursements.md), [`timesheets.md`](timesheets.md), [`client-visits.md`](client-visits.md), [`device-lending.md`](device-lending.md) dari 164 panggilan HTTP nyata. Seluruh 53 endpoint v1 kini terdokumentasi |
| `POST /client-visits/check-in`, `POST /client-visits/{clientVisit}/check-out` | CHANGED | **Perbaikan:** `captured_at` dan `device_time` yang membawa offset kini dikonversi ke UTC sebelum disimpan. Sebelumnya jam lokal disimpan sebagai UTC (WIB bergeser +7 jam), sehingga `checked_in_at` di respons 7 jam lebih lambat dan **check-out selalu ditolak** `Waktu check-out harus lebih besar daripada waktu check-in.` Client yang mengirim waktu UTC (`Z`) tidak terdampak. Bentuk request dan response tidak berubah |

Perilaku yang sudah berlaku di kode dan baru tercatat di kontrak (bukan perubahan):

- `POST /leaves` → `leave_type_id` milik perusahaan lain lolos validasi lalu dijawab 404
  `Sumber daya tidak ditemukan.`, bukan 422.
- `POST /reimbursements` dan `POST /timesheet-entries` → `business_trip_id`/`client_visit_id` milik
  karyawan lain diabaikan (tersimpan `null`) tanpa penolakan.
- `POST /client-visits/{clientVisit}/cancel` → `reason` dibaca tanpa FormRequest dan tanpa validasi
  panjang.
- `GET /timesheets/today` membuat timesheet `DRAFT` kosong; `GET /me/leave-balances` membuat baris
  saldo yang belum ada, termasuk untuk `?year=` lain.
- `POST /attendance/corrections` → `work_date` berformat `DD-MM-YYYY` lolos validasi `date`. Tidak ada
  endpoint detail maupun pembatalan koreksi.
- `GET /reimbursements` → `approved_amount` bernilai `0` (bukan `null`) sebelum disetujui.
- `POST /client-visits/{clientVisit}/check-out` → pesan validasi `follow_up_date` berbunyi
  `...tanggal today atau setelahnya.` (kata `today` belum diterjemahkan).

---

## 2026-10-21

| Endpoint | Jenis | Ringkasan |
|---|---|---|
| — | ADDED | Berkas modul [`auth.md`](auth.md), [`me.md`](me.md), [`attendance.md`](attendance.md): parameter lengkap dari FormRequest, struktur field response, daftar enum, dan contoh request/response dari eksekusi nyata (100 panggilan HTTP). Dokumentasi saja, kode dan perilaku API tidak berubah |
| — | CHANGED | Token pada contoh `README.md` disamarkan menjadi `1\|contohTokenDisamarkanTidakBerlakuDiServerManaPun`; token samaran dan token lama diuji ke produksi dan dijawab 401 |
| — | ADDED | Kerangka kontrak `docs/api/`: konvensi umum di `README.md` dan berkas changelog ini. Kondisi awal 53 endpoint v1 tercatat di README bagian 15 |
| `GET /attendance/today` | ADDED | field `is_overtime` (boolean) dan `overtime_type` (`REST_DAY`, `HOLIDAY`, atau `null`) |
| `GET /overtimes`, `GET /overtimes/{overtime}` | ADDED | field `hourly_rate` dan `amount` (rupiah bilangan bulat, `null` sebelum lembur direalisasi atau tarif belum diatur) |
| `POST /attendance/corrections` | CHANGED | tanggal libur yang punya lembur hari libur disetujui kini dapat dikoreksi; jendela koreksi hari kerja diperlebar oleh lembur yang disetujui pada tanggal itu |
| `POST /timesheet-entries`, `POST /client-visits/check-in` | CHANGED | `work_date` mengikuti lembur hari libur yang melewati tengah malam (tanggal mulai lembur) |

Perilaku yang sudah berlaku di kode dan baru tercatat di kontrak (bukan perubahan):

- `GET /me/config` → `subscription` hanya berisi `status`, `plan`, `is_locked` bila perusahaan tidak
  punya langganan berjalan; `status_label`, `trial_ends_at`, `ends_at` tidak dikirim.
- `GET /me/config` → `module_announcement` dan `module_face_matching` bernilai `true` pada paket
  produksi, padahal endpoint belum ada.
- `GET /me/config` → `today.check_in_opens_at`/`check_out_closes_at` belum memperhitungkan pelebaran
  jendela dari lembur sebelum/sesudah jam kerja yang disetujui.
- `GET /attendance/today` → `can_check_in`/`can_check_out` tidak memeriksa jam; sebelum jendela dibuka
  nilainya tetap `true`.
- `POST /attendance/check-in|check-out` → kirim ulang dengan `uuid` lama dijawab `200 DUPLICATE` walau
  lewat toleransi offline, tetapi tetap wajib lolos validasi (termasuk `photo`).
- `POST /attendance/check-in|check-out` → batas laju (429) diperiksa sebelum kunci langganan (402).
