# Profil dan Konfigurasi Karyawan

Profil karyawan, konfigurasi aplikasi (`me/config`), daftar perangkat, ganti kata sandi, dan
persetujuan data pribadi. Konvensi umum ada di [README.md](README.md); login di [auth.md](auth.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /me`, `GET /me/config`, `GET /me/devices`, `PUT /me/password`, `POST /consents` |
| Sumber kode | `ProfileController`, `MobileConfigController` + `MobileConfigService`, `DeviceController`, `PasswordController`, `ConsentController`, `ChangePasswordRequest`, `StoreConsentRequest` |
| Contoh direkam | 2026-10-21, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan (`nusantara-logistik` WIB, `borneo-retail` WITA), `APP_LOCALE=id` seperti server |

Seluruh endpoint di berkas ini wajib token (`Authorization: Bearer <token>`) dan melewati
`auth:sanctum` + `EnsureSubscriptionActive`.

---

## Enum

`EmploymentStatus`, `WorkPattern`, `DevicePlatform`, dan `DeviceStatus` ada di
[auth.md](auth.md#enum).

### `SubscriptionStatus` (`subscription.status`)

| Nilai | `status_label` | `is_locked` |
|---|---|---|
| `TRIALING` | Masa Uji Coba | `false` |
| `ACTIVE` | Aktif | `false` |
| `PAST_DUE` | Menunggak | `true` |
| `SUSPENDED` | Ditangguhkan | `true` |
| `null` | (tidak dikirim) | `false`, perusahaan tanpa langganan berjalan |

`CANCELED` (Dibatalkan) ada di enum, tetapi langganan berstatus itu tidak dianggap langganan berjalan,
sehingga `me/config` mengirim bentuk `status: null` dan `is_locked: false`.

### `ScheduleStatus` (`today.status`)

| Nilai | `status_label` | `today.message` |
|---|---|---|
| `ON_DUTY` | Masuk kerja | `Masuk kerja pada shift {nama shift}.` atau, pada hari libur dengan lembur disetujui, `Lembur {Hari Libur Mingguan/Hari Libur Nasional} yang sudah disetujui.` |
| `OFF_DUTY` | Libur | `Tidak dijadwalkan masuk pada tanggal ini.` |
| `HOLIDAY` | Libur nasional | `Libur: {nama libur}.` |
| `NOT_SCHEDULED` | Tidak dijadwalkan | `Karyawan tidak mengikuti presensi harian.` |
| `NO_SHIFT_PATTERN` | Belum punya pola shift | `Karyawan belum memiliki pola shift. Hubungi Admin HR.` |
| `INCOMPLETE_PATTERN` | Pola shift belum lengkap | `Pola {nama pola} pada hari {hari} belum diisi jam kerja.` |

Hanya `ON_DUTY` yang menerima presensi (`requires_attendance: true`).

### `OvertimeType` (`today.overtime_type`)

| Nilai | Label | Muncul di `today` |
|---|---|---|
| `REST_DAY` | Hari Libur Mingguan | ya, bila hari libur mingguan punya lembur disetujui |
| `HOLIDAY` | Hari Libur Nasional | ya, bila hari libur nasional punya lembur disetujui |
| `BEFORE_SHIFT` | Sebelum Jam Kerja | tidak (`overtime_type` hanya mengisi lembur hari libur) |
| `AFTER_SHIFT` | Sesudah Jam Kerja | tidak |

### `ClientVisitPurpose` (`open_client_visit.purpose`)

`SALES_CALL`, `PRESENTATION`, `NEGOTIATION`, `DELIVERY`, `MAINTENANCE`, `COLLECTION`, `SURVEY`,
`OTHER`. Label dan rincian di `client-visits.md`.

---

## Profil karyawan

**`GET /me`**

Deskripsi: mengambil data karyawan pemilik token. Dipanggil saat aplikasi dibuka untuk memastikan token
masih berlaku dan memperbarui profil di layar.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` (dikecualikan saat langganan terkunci) |
| Route name | `api.v1.me.show` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter:** tidak ada.

**Contoh Request**

```http
GET /api/v1/me HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Data karyawan berhasil diambil.",
  "data": {
    "id": 3,
    "employee_number": "EMP-0007",
    "name": "Citra Satu",
    "email": "citra@nusantara-logistik.test",
    "phone": "081234560007",
    "employment_status": "OUTSOURCE",
    "employment_status_label": "Alih Daya",
    "work_pattern": "FIXED",
    "work_pattern_label": "Jam Tetap",
    "department": "Divisi Operasional",
    "position": "Spesialis",
    "job_level": "Direktur",
    "must_change_password": false
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID karyawan |
| `employee_number` | string | tidak | Nomor Karyawan, unik dalam satu perusahaan |
| `name` | string | tidak | nama lengkap |
| `email` | string | ya | surel; dibutuhkan untuk lupa kata sandi dan perangkat pinjaman |
| `phone` | string | ya | nomor telepon |
| `employment_status` | string (enum) | tidak | `EmploymentStatus` |
| `employment_status_label` | string | tidak | label tampilan |
| `work_pattern` | string (enum) | tidak | `WorkPattern` |
| `work_pattern_label` | string | tidak | label tampilan |
| `department` | string | ya | nama departemen |
| `position` | string | ya | nama jabatan |
| `job_level` | string | ya | nama jenjang jabatan |
| `must_change_password` | boolean | tidak | `true` → arahkan ke `PUT /me/password` sebelum fitur lain |

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Token tidak ada, salah, dicabut, atau milik karyawan yang sudah ganti/atur ulang kata sandi | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |
| Perusahaan dinonaktifkan pengelola Absenova | 403 | `Perusahaan Anda sedang tidak aktif. Hubungi administrator.` |

```json
{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}
```

**Catatan**

- Isolasi tenant: data selalu milik karyawan pemilik token. Token karyawan `borneo-retail` mendapat
  profil `BR-0101` Anton Dua dari perusahaannya sendiri (terekam), tidak pernah data perusahaan lain.
- Idempotency: tidak relevan (GET).
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada.
- Status langganan: **tetap 200 saat langganan terkunci** (terekam saat `SUSPENDED`).

---

## Konfigurasi aplikasi

**`GET /me/config`**

Deskripsi: satu paket konfigurasi untuk client: identitas perusahaan, status langganan, saklar modul,
kebijakan presensi dan modul lain, lokasi kerja, jadwal hari ini, perjalanan bisnis aktif, dan kunjungan
klien yang masih terbuka. Dipanggil setelah login, saat aplikasi dibuka, dan saat kembali ke latar depan.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` (dikecualikan saat langganan terkunci) |
| Route name | `api.v1.me.config` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter:** tidak ada. Seluruh nilai diturunkan dari token dan jam server.

**Contoh Request**

```http
GET /api/v1/me/config HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, karyawan jam tetap, Rabu 2026-10-21 07:41 WIB)

```json
{
  "success": true,
  "message": "Konfigurasi presensi berhasil diambil.",
  "data": {
    "company": {
      "uuid": "01a15ca1-1f9c-710c-bf21-daafa03f60c9",
      "slug": "nusantara-logistik",
      "name": "Nusantara Logistik",
      "logo_url": null,
      "logo_version": null,
      "timezone": "Asia/Jakarta"
    },
    "subscription": {
      "status": "TRIALING",
      "status_label": "Masa Uji Coba",
      "plan": "Absenova",
      "trial_ends_at": "2026-11-04T04:03:46+00:00",
      "ends_at": "2026-11-04",
      "is_locked": false
    },
    "modules": {
      "module_shift_scheduling": true,
      "module_attendance_correction": true,
      "module_leave": true,
      "module_overtime": true,
      "module_business_trip": true,
      "module_reimbursement": true,
      "module_timesheet": true,
      "module_client_visit": true,
      "module_announcement": false,
      "module_face_matching": false,
      "module_data_export": true
    },
    "policy": {
      "photo_required": true,
      "photo_max_kilobytes": 300,
      "gps_accuracy_threshold_meters": 50,
      "offline_sync_tolerance_hours": 24,
      "business_trip_window_extra_minutes": 180,
      "timesheet": {
        "minimum_entry_minutes": 15,
        "maximum_entry_minutes": 720,
        "max_minutes_per_day": 960,
        "max_backdate_days": 7,
        "entry_from_client_visit": true
      },
      "device_lending": {
        "enabled": true,
        "code_expires_minutes": 10,
        "session_hours": 12,
        "max_usages": 2,
        "max_per_month": 3
      },
      "client_visit": {
        "radius_meters": 300,
        "photo_required": true,
        "photo_max_kilobytes": 500,
        "minimum_duration_minutes": 5,
        "max_open_hours": 12
      },
      "overtime": {
        "minimum_minutes": 30,
        "rounding_minutes": 15,
        "max_minutes_per_day": 240,
        "max_minutes_per_week": 1080,
        "max_backdate_days": 3
      },
      "timezone": "Asia/Jakarta"
    },
    "consent": {
      "policy_version": "2026-10",
      "title": "Persetujuan Pemrosesan Data Pribadi",
      "body": "Untuk mencatat kehadiran, aplikasi ini memproses data pribadi Anda berikut: lokasi GPS beserta tingkat akurasinya, foto wajah saat presensi, waktu pada perangkat, penanda lokasi palsu (mock location), serta pengenal dan nama perangkat yang Anda pakai.\nData tersebut dipakai untuk memverifikasi kehadiran Anda dan memastikan presensi dilakukan di lokasi kerja yang ditetapkan perusahaan.\nPengelola data adalah perusahaan tempat Anda bekerja, yang memprosesnya melalui layanan Absenova. Data presensi Anda dapat dilihat oleh Admin HR perusahaan.\nAnda berhak mengakses, memperbaiki, dan meminta penghapusan data pribadi Anda, serta menarik persetujuan ini, melalui Admin HR perusahaan Anda.\nDengan menekan Setuju, Anda menyatakan telah membaca dan menyetujui pemrosesan data pribadi di atas.",
      "accepted": false,
      "accepted_at": null
    },
    "work_locations": [
      {
        "id": 1,
        "code": "KP-JKT",
        "name": "Kantor Pusat Jakarta",
        "latitude": -6.2087634,
        "longitude": 106.845599,
        "radius_meters": 150
      },
      {
        "id": 2,
        "code": "GD-CKG",
        "name": "Gudang Cakung",
        "latitude": -6.1836102,
        "longitude": 106.9442431,
        "radius_meters": 200
      }
    ],
    "today": {
      "work_date": "2026-10-21",
      "status": "ON_DUTY",
      "status_label": "Masuk kerja",
      "message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
      "shift": "Jam Kantor 08:00 - 17:00",
      "starts_at": "2026-10-21T01:00:00+00:00",
      "ends_at": "2026-10-21T10:00:00+00:00",
      "check_in_opens_at": "2026-10-20T23:30:00+00:00",
      "check_out_closes_at": "2026-10-21T12:00:00+00:00",
      "requires_attendance": true,
      "is_overtime": false,
      "overtime_type": null
    },
    "business_trip": null,
    "open_client_visit": null
  }
}
```

Variasi yang direkam (hanya bagian yang berbeda):

Karyawan sedang perjalanan bisnis dan punya kunjungan klien terbuka (07:41 WIB). Jendela presensi
melebar 180 menit (`business_trip_window_extra_minutes`) ke dua arah:

```json
"today": {
  "work_date": "2026-10-21",
  "status": "ON_DUTY",
  "status_label": "Masuk kerja",
  "message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
  "shift": "Jam Kantor 08:00 - 17:00",
  "starts_at": "2026-10-21T01:00:00+00:00",
  "ends_at": "2026-10-21T10:00:00+00:00",
  "check_in_opens_at": "2026-10-20T20:30:00+00:00",
  "check_out_closes_at": "2026-10-21T15:00:00+00:00",
  "requires_attendance": true,
  "is_overtime": false,
  "overtime_type": null
},
"business_trip": {
  "id": 1,
  "letter_number": "PB/2026/10/014",
  "destination_name": "Gudang Mitra Surabaya",
  "destination_latitude": -7.241387,
  "destination_longitude": 112.678269,
  "start_date": "2026-10-21",
  "end_date": "2026-10-23",
  "geofence_waived": true,
  "notice": "Presensi hari ini dicatat sebagai perjalanan bisnis. Foto tetap wajib dan koordinat Anda tetap direkam."
},
"open_client_visit": {
  "id": 1,
  "client_name": "PT Sinar Jaya Abadi",
  "purpose": "SALES_CALL",
  "checked_in_at": "2026-10-21T00:15:00+00:00",
  "notice": "Kunjungan klien masih terbuka. Lakukan check-out agar durasinya tercatat."
}
```

Shift malam 23:00–07:00 (22:30 WIB). `work_date` tanggal mulai shift, `ends_at` keesokan harinya:

```json
"today": {
  "work_date": "2026-10-21",
  "status": "ON_DUTY",
  "status_label": "Masuk kerja",
  "message": "Masuk kerja pada shift Shift Malam 23:00 - 07:00.",
  "shift": "Shift Malam 23:00 - 07:00",
  "starts_at": "2026-10-21T16:00:00+00:00",
  "ends_at": "2026-10-22T00:00:00+00:00",
  "check_in_opens_at": "2026-10-21T15:00:00+00:00",
  "check_out_closes_at": "2026-10-22T02:00:00+00:00",
  "requires_attendance": true,
  "is_overtime": false,
  "overtime_type": null
}
```

Langganan `SUSPENDED` (endpoint lain dijawab 402):

```json
"subscription": {
  "status": "SUSPENDED",
  "status_label": "Ditangguhkan",
  "plan": "Absenova",
  "trial_ends_at": "2026-11-04T04:03:46+00:00",
  "ends_at": "2026-11-04",
  "is_locked": true
}
```

Perusahaan tanpa langganan berjalan (`borneo-retail`, WITA), karyawan tanpa lokasi kerja. Objek
`subscription` hanya berisi **tiga** kunci:

```json
"subscription": {
  "status": null,
  "plan": null,
  "is_locked": false
},
"work_locations": [],
"today": {
  "work_date": "2026-10-21",
  "status": "ON_DUTY",
  "status_label": "Masuk kerja",
  "message": "Masuk kerja pada shift Jam Kantor 08:00 - 17:00.",
  "shift": "Jam Kantor 08:00 - 17:00",
  "starts_at": "2026-10-21T00:00:00+00:00",
  "ends_at": "2026-10-21T09:00:00+00:00",
  "check_in_opens_at": "2026-10-20T22:30:00+00:00",
  "check_out_closes_at": "2026-10-21T11:00:00+00:00",
  "requires_attendance": true,
  "is_overtime": false,
  "overtime_type": null
}
```

Contoh `today` untuk hari libur, libur dari Jadwal Kerja, dan lembur hari libur ada di
[attendance.md](attendance.md#presensi-hari-ini) (`GET /attendance/today` memakai penentu jadwal yang
sama).

**Field `data.company`** (objek)

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `uuid` | string (UUID) | tidak | pengenal tetap perusahaan |
| `slug` | string | tidak | kode perusahaan |
| `name` | string | tidak | nama tampilan |
| `logo_url` | string (URL) | ya | URL bertanda tangan, berlaku 120 menit; `null` bila belum ada logo |
| `logo_version` | string | ya | kunci cache logo; berubah bila logo diganti |
| `timezone` | string (IANA) | tidak | zona waktu perusahaan untuk menampilkan seluruh timestamp |

**Field `data.subscription`** (objek, tidak pernah `null`)

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `status` | string (enum) | ya | `SubscriptionStatus`; `null` bila tidak ada langganan berjalan |
| `status_label` | string | — | **hanya ada bila `status` terisi** |
| `plan` | string | ya | nama paket, mis. `Absenova` |
| `trial_ends_at` | string (ISO 8601 UTC) | ya | akhir masa uji coba. **Hanya ada bila `status` terisi** |
| `ends_at` | string (`YYYY-MM-DD`) | ya | tanggal akhir masa langganan. **Hanya ada bila `status` terisi** |
| `is_locked` | boolean | tidak | `true` → seluruh endpoint bertoken selain `POST /auth/logout`, `GET /me`, `GET /me/config` dijawab **402**, termasuk presensi. Client menampilkan layar terkunci |

Di Kotlin/Gson, jadikan `status_label`, `trial_ends_at`, dan `ends_at` nullable dengan nilai bawaan
`null` agar bentuk tiga kunci tidak memicu galat.

**Field `data.modules`** (objek, 11 kunci boolean)

Saklar modul dari paket langganan. Server **tidak** memblokir endpoint berdasarkan saklar ini; client
menyembunyikan menu modul yang `false`.

| Kunci | API terkait | Keterangan |
|---|---|---|
| `module_attendance_correction` | `attendance-corrections.md` | koreksi presensi |
| `module_leave` | `leaves.md` | cuti dan izin |
| `module_overtime` | `overtimes.md` | lembur |
| `module_business_trip` | `business-trips.md` | perjalanan bisnis |
| `module_reimbursement` | `reimbursements.md` | reimbursement |
| `module_timesheet` | `timesheets.md` | timesheet |
| `module_client_visit` | `client-visits.md` | kunjungan klien |
| `module_announcement` | `announcements.md` | pengumuman perusahaan. Dirilis 2026-11-15; contoh respons di atas direkam sebelum rilis sehingga masih `false` |
| `module_shift_scheduling` | tidak ada | fitur panel admin; tidak memengaruhi client |
| `module_data_export` | tidak ada | fitur panel admin; tidak memengaruhi client |
| `module_face_matching` | **belum ada** | Fase 2, belum dirilis; server selalu mengirim `false` sampai endpoint tersedia, apa pun isi paket |

**Field `data.policy`** (objek)

Aturan perusahaan untuk validasi awal di client. Server tetap memvalidasi ulang. Nilai pada contoh adalah
bawaan perusahaan baru.

| Field | Tipe | Null | Bawaan | Keterangan |
|---|---|---|---|---|
| `photo_required` | boolean | tidak | `true` | `photo` wajib pada `POST /attendance/check-in` dan `/check-out` |
| `photo_max_kilobytes` | integer | tidak | `300` | batas ukuran `photo` presensi (KB) |
| `gps_accuracy_threshold_meters` | integer | tidak | `50` | `accuracy_meters` di atas nilai ini ditolak, untuk semua pola kerja |
| `offline_sync_tolerance_hours` | integer | tidak | `24` | `captured_at` lebih tua dari ini ditolak |
| `business_trip_window_extra_minutes` | integer | tidak | `180` | pelebaran jendela presensi pada hari perjalanan bisnis, sudah diterapkan ke `today` |
| `timesheet.minimum_entry_minutes` | integer | tidak | `15` | durasi minimum satu aktivitas |
| `timesheet.maximum_entry_minutes` | integer | tidak | `720` | durasi maksimum satu aktivitas |
| `timesheet.max_minutes_per_day` | integer | tidak | `960` | total menit aktivitas per hari |
| `timesheet.max_backdate_days` | integer | tidak | `7` | batas mundur tanggal aktivitas |
| `timesheet.entry_from_client_visit` | boolean | tidak | `true` | check-out kunjungan klien membuat aktivitas timesheet otomatis |
| `device_lending.enabled` | boolean | tidak | `true` | perusahaan mengizinkan presensi lewat perangkat pinjaman |
| `device_lending.code_expires_minutes` | integer | tidak | `10` | masa berlaku kode izin pinjam |
| `device_lending.session_hours` | integer | tidak | `12` | masa berlaku sesi pinjam setelah kode diverifikasi |
| `device_lending.max_usages` | integer | tidak | `2` | jumlah presensi per sesi pinjam |
| `device_lending.max_per_month` | integer | tidak | `3` | jumlah sesi pinjam per bulan |
| `client_visit.radius_meters` | integer | tidak | `300` | radius lokasi klien |
| `client_visit.photo_required` | boolean | tidak | `true` | foto wajib saat check-in kunjungan |
| `client_visit.photo_max_kilobytes` | integer | tidak | `500` | batas ukuran foto kunjungan (KB) |
| `client_visit.minimum_duration_minutes` | integer | tidak | `5` | durasi minimum kunjungan |
| `client_visit.max_open_hours` | integer | tidak | `12` | kunjungan terbuka lebih lama dari ini ditutup sistem |
| `overtime.minimum_minutes` | integer | tidak | `30` | durasi minimum pengajuan lembur |
| `overtime.rounding_minutes` | integer | tidak | `15` | pembulatan menit lembur |
| `overtime.max_minutes_per_day` | integer | tidak | `240` | batas lembur per hari |
| `overtime.max_minutes_per_week` | integer | tidak | `1080` | batas lembur per minggu |
| `overtime.max_backdate_days` | integer | tidak | `3` | batas mundur tanggal pengajuan lembur |
| `timezone` | string (IANA) | tidak | `Asia/Jakarta` | sama dengan `company.timezone` |

**Field `data.work_locations`** (array, boleh kosong)

Lokasi kerja aktif yang ditugaskan ke karyawan. Array kosong berarti presensi ditolak
(`Karyawan belum ditugaskan pada lokasi presensi mana pun. Hubungi Admin HR.`) kecuali pola `REMOTE`
atau hari perjalanan bisnis.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID lokasi |
| `code` | string | tidak | kode lokasi |
| `name` | string | tidak | nama lokasi, muncul di `attendance.work_location` |
| `latitude` | number | tidak | lintang desimal |
| `longitude` | number | tidak | bujur desimal; nol di belakang koma tidak dikirim (`106.845599`) |
| `radius_meters` | integer | tidak | radius geofence. Presensi sah bila `jarak - accuracy_meters <= radius_meters` |

**Field `data.today`** (objek, tidak pernah `null`)

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `work_date` | string (`YYYY-MM-DD`) | tidak | tanggal kerja menurut kalender perusahaan; untuk shift malam adalah **tanggal mulai shift** |
| `status` | string (enum) | tidak | `ScheduleStatus` |
| `status_label` | string | tidak | label tampilan |
| `message` | string | tidak | kalimat siap tampil, lihat tabel `ScheduleStatus` |
| `shift` | string | ya | nama shift; `null` bila tidak masuk kerja atau pada lembur hari libur |
| `starts_at` | string (ISO 8601 UTC) | ya | mulai shift atau mulai lembur hari libur |
| `ends_at` | string (ISO 8601 UTC) | ya | akhir shift atau akhir lembur hari libur |
| `check_in_opens_at` | string (ISO 8601 UTC) | ya | awal jendela presensi, dihitung resolver yang sama dengan pemeriksaan `OUTSIDE_WINDOW`: sudah termasuk pelebaran perjalanan bisnis atau lembur `BEFORE_SHIFT`/`AFTER_SHIFT` yang disetujui (yang terbesar). Nilainya sama dengan `GET /attendance/today` → `check_in_opens_at` |
| `check_out_closes_at` | string (ISO 8601 UTC) | ya | akhir jendela presensi, aturan sama dengan `check_in_opens_at` |
| `requires_attendance` | boolean | tidak | `true` hanya bila `status = ON_DUTY` |
| `is_overtime` | boolean | tidak | `true` bila presensi hari ini adalah lembur hari libur yang disetujui |
| `overtime_type` | string (enum) | ya | `REST_DAY` atau `HOLIDAY` bila `is_overtime`, selain itu `null` |

**Field `data.business_trip`** (objek atau `null`)

Terisi bila hari ini termasuk perjalanan bisnis yang disetujui.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID perjalanan bisnis |
| `letter_number` | string | ya | nomor surat tugas |
| `destination_name` | string | tidak | nama tujuan |
| `destination_latitude` | number | ya | lintang tujuan |
| `destination_longitude` | number | ya | bujur tujuan |
| `start_date` | string (`YYYY-MM-DD`) | tidak | tanggal mulai |
| `end_date` | string (`YYYY-MM-DD`) | tidak | tanggal selesai |
| `geofence_waived` | boolean | tidak | selalu `true`: radius lokasi kerja tidak diperiksa |
| `notice` | string | tidak | kalimat siap tampil |

**Field `data.open_client_visit`** (objek atau `null`)

Terisi bila karyawan punya kunjungan klien berstatus berjalan.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID kunjungan, untuk `POST /client-visits/{id}/check-out` |
| `client_name` | string | tidak | nama klien |
| `purpose` | string (enum) | tidak | `ClientVisitPurpose` |
| `checked_in_at` | string (ISO 8601 UTC) | tidak | waktu check-in kunjungan |
| `notice` | string | tidak | kalimat siap tampil |

**Field `data.consent`** (objek, tidak pernah `null`)

Kebijakan persetujuan data pribadi (UU 27/2022 PDP) yang **aktif** dan status persetujuan karyawan login
untuk versi itu. Versi dan teks dikelola pengelola Absenova di panel platform dan berlaku tanpa rilis
aplikasi.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `policy_version` | string | tidak | versi aktif, mis. `2026-10`. Kirim nilai ini apa adanya ke `POST /consents` |
| `title` | string | tidak | judul layar persetujuan |
| `body` | string | tidak | isi kebijakan, **teks polos tanpa HTML**; paragraf dipisah satu karakter `\n` |
| `accepted` | boolean | tidak | `true` bila karyawan sudah menyetujui **versi aktif**. Persetujuan versi lama tidak dihitung |
| `accepted_at` | string (ISO 8601 UTC) | ya | waktu persetujuan versi aktif; `null` bila `accepted` `false` |

Saat versi aktif diganti, `accepted` kembali `false` untuk seluruh karyawan sampai mereka menyetujui
versi baru. Contoh sesudah versi `2026-11` diaktifkan (karyawan baru menyetujui `2026-10`):

```json
{
  "policy_version": "2026-11",
  "title": "Persetujuan Pemrosesan Data Pribadi",
  "body": "Untuk mencatat kehadiran, aplikasi ini memproses lokasi GPS dan akurasinya, foto wajah, waktu perangkat, penanda lokasi palsu, serta pengenal dan nama perangkat.\nData dipakai untuk memverifikasi kehadiran dan lokasi kerja. Foto presensi disimpan paling lama 12 bulan.\nPengelola data adalah perusahaan Anda melalui Absenova; data dapat dilihat Admin HR.\nAnda dapat meminta akses, perbaikan, penghapusan, atau menarik persetujuan melalui Admin HR.",
  "accepted": false,
  "accepted_at": null
}
```

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Token tidak sah | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |
| Perusahaan dinonaktifkan pengelola Absenova | 403 | `Perusahaan Anda sedang tidak aktif. Hubungi administrator.` |

```json
{
  "success": false,
  "message": "Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.",
  "errors": {}
}
```

**Catatan**

- **Jendela waktu `today` sama dengan aturan server** pada saat request, termasuk pelebaran lembur
  sebelum/sesudah jam kerja dan perjalanan bisnis. Karena `me/config` boleh di-cache, ambil jendela
  terbaru dari `GET /attendance/today` saat membuka layar presensi. Client tetap tidak memblokir tombol
  berdasarkan jam perangkat; kirim presensi dan tampilkan `message` bila ditolak.
- `today` dihitung dari jam server saat request. Shift malam yang sedang berjalan setelah tengah malam
  tetap menampilkan `work_date` tanggal mulai shift selama jendela presensinya masih terbuka.
- Cache: `company`, `modules`, dan `policy` boleh di-cache. `today`, `business_trip`, dan
  `open_client_visit` berubah sepanjang hari; ambil ulang saat aplikasi kembali ke latar depan.
  `consent` dapat berubah kapan saja saat versi aktif diganti; periksa setiap kali `me/config` diambil.
- Idempotency: tidak relevan (GET).
- Rate limit: tidak ada.
- FeatureGate / modul: endpoint ini sumber saklar modul.
- Status langganan: **tetap 200 saat langganan terkunci**; baca `subscription.is_locked`.

---

## Daftar perangkat

**`GET /me/devices`**

Deskripsi: daftar perangkat yang pernah didaftarkan karyawan, terbaru di atas. Dipakai layar pengaturan
untuk menunjukkan perangkat aktif dan perangkat yang menunggu persetujuan atau sudah dicabut.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.me.devices` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter:** tidak ada.

**Contoh Request**

```http
GET /api/v1/me/devices HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Daftar perangkat berhasil diambil.",
  "data": [
    {
      "id": 2,
      "device_identifier": "b3d0e8f1-samsung-a55-citra",
      "device_name": "Samsung Galaxy A55",
      "platform": "ANDROID",
      "status": "REVOKED",
      "status_label": "Dicabut",
      "approved_at": null,
      "last_used_at": null
    },
    {
      "id": 1,
      "device_identifier": "6f1c2a9e-4b7d-4e21-9a51-citra-pixel8",
      "device_name": "Google Pixel 8",
      "platform": "ANDROID",
      "status": "APPROVED",
      "status_label": "Disetujui",
      "approved_at": "2026-10-21T00:40:00+00:00",
      "last_used_at": "2026-10-21T00:41:00+00:00"
    }
  ]
}
```

**Field `data[]`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID perangkat |
| `device_identifier` | string | tidak | pengenal yang dikirim saat login |
| `device_name` | string | ya | nama perangkat |
| `platform` | string (enum) | tidak | `DevicePlatform` |
| `status` | string (enum) | tidak | `DeviceStatus` |
| `status_label` | string | tidak | label tampilan |
| `approved_at` | string (ISO 8601 UTC) | ya | `null` bila belum pernah disetujui |
| `last_used_at` | string (ISO 8601 UTC) | ya | login terakhir; `null` bila belum pernah berhasil login |

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Token tidak sah | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |
| Langganan terkunci | 402 | `Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan.` |

```json
{
  "success": false,
  "message": "Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. Aplikasi dikunci sampai admin perusahaan melunasi tagihan.",
  "errors": {}
}
```

**Catatan**

- Untuk mengenali perangkat sendiri, bandingkan `device_identifier` dengan nilai yang disimpan client.
- Pada contoh, Samsung Galaxy A55 tercatat saat login ditolak (`PENDING`) lalu dicabut Admin HR
  (`REVOKED`), sehingga `approved_at` tetap `null`.
- Client tidak dapat menghapus atau mengganti perangkat; penggantian lewat persetujuan Admin HR.
- Idempotency: tidak relevan (GET).
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada.
- Status langganan: terkunci → 402.

---

## Ganti kata sandi

**`PUT /me/password`**

Deskripsi: mengganti kata sandi dengan memasukkan kata sandi lama. Wajib dipanggil bila
`must_change_password` bernilai `true`. Setelah berhasil, **seluruh** token karyawan dicabut, termasuk
token yang dipakai request ini.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.me.password` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`, `Content-Type: application/json`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `current_password` | body | string | ya | `required`, `string`; dicocokkan dengan kata sandi saat ini di Controller |
| `password` | body | string | ya | `required`, `string`, `confirmed`, minimal 8 karakter |
| `password_confirmation` | body | string | ya | wajib sama dengan `password` |

**Contoh Request**

```http
PUT /api/v1/me/password HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_password": "Rahasia123!",
  "password": "SandiBaru2026",
  "password_confirmation": "SandiBaru2026"
}
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Kata sandi berhasil diperbarui. Silakan masuk kembali.",
  "data": {}
}
```

**Field `data`:** objek kosong `{}`.

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Validasi gagal | 422 | `Data yang dikirim tidak lolos pemeriksaan.` |
| Kata sandi lama salah | 422 | `Kata sandi lama tidak sesuai.` (`errors.current_password`) |
| Token tidak sah | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |
| Langganan terkunci | 402 | `Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. ...` |

Validasi (`password: "pendek"`, `password_confirmation: "lain"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "password": [
      "Konfirmasi kata sandi baru tidak cocok.",
      "Kolom kata sandi baru minimal 8 karakter."
    ]
  }
}
```

Kata sandi lama salah:

```json
{
  "success": false,
  "message": "Kata sandi lama tidak sesuai.",
  "errors": {
    "current_password": [
      "Kata sandi lama tidak sesuai."
    ]
  }
}
```

**Catatan**

- Setelah 200, token yang sama langsung dijawab 401 (terekam). Client menghapus token lokal dan
  membuka layar login. `must_change_password` menjadi `false`.
- Idempotency: tidak ada. Panggilan kedua dengan token lama dijawab 401.
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada.
- Status langganan: terkunci → 402. Karyawan dengan `must_change_password: true` di perusahaan yang
  terkunci tidak dapat mengganti kata sandi sampai tagihan dilunasi.

---

## Persetujuan data pribadi

**`POST /consents`**

Deskripsi: mencatat persetujuan karyawan atas pemrosesan data pribadi (UU 27/2022 PDP) untuk versi
kebijakan yang **aktif**. Teks dan versi dibaca dari `GET /me/config` → `consent`. Dipanggil dari layar
persetujuan bila `consent.accepted` bernilai `false`.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.consents.store` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`, `Content-Type: application/json`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `policy_version` | body | string | ya | `required`, `string`, `max:50`, `in:{versi aktif}`. Wajib sama dengan `me/config` → `consent.policy_version`; versi lain ditolak 422 |
| `accepted` | body | boolean | ya | `required`, `accepted`: hanya `true`, `1`, `"1"`, `"yes"`, `"on"`, `"true"` yang lolos |

**Contoh Request**

```http
POST /api/v1/consents HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "policy_version": "2026-10",
  "accepted": true
}
```

**Contoh Response Sukses** (`200`)

```json
{
  "success": true,
  "message": "Persetujuan tercatat.",
  "data": {
    "policy_version": "2026-10",
    "consented_at": "2026-10-21T00:41:00+00:00"
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `policy_version` | string | tidak | versi yang dicatat |
| `consented_at` | string (ISO 8601 UTC) | tidak | waktu persetujuan menurut server |

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| `accepted` bernilai `false` atau kosong, `policy_version` kosong | 422 | `Data yang dikirim tidak lolos pemeriksaan.` |
| `policy_version` bukan versi aktif | 422 | `Data yang dikirim tidak lolos pemeriksaan.`, `errors.policy_version`: `Versi kebijakan ini sudah tidak berlaku. Muat ulang kebijakan terbaru lalu setujui kembali.` |
| Token tidak sah | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |
| Langganan terkunci | 402 | `Masa langganan perusahaan sudah berakhir dan tagihan belum dibayar. ...` |

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "accepted": [
      "Kolom persetujuan wajib disetujui."
    ]
  }
}
```

Versi lama sesudah versi `2026-11` diaktifkan (`policy_version: "2026-10"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "policy_version": [
      "Versi kebijakan ini sudah tidak berlaku. Muat ulang kebijakan terbaru lalu setujui kembali."
    ]
  }
}
```

**Catatan**

- Penolakan tidak dikirim ke server. Bila karyawan menolak, client tidak memanggil endpoint ini.
- **Sumber kebenaran di server.** Status ada di `me/config` → `consent.accepted`; jangan memakai teks
  atau versi yang tertanam di aplikasi. Sesudah `200`, panggil ulang `GET /me/config` atau anggap
  `accepted` `true` untuk versi yang baru dikirim.
- Bila respons 422 `errors.policy_version`, versi aktif sudah berganti: muat ulang `me/config`,
  tampilkan teks baru, lalu kirim versi baru.
- Server **belum** mewajibkan consent sebelum presensi: presensi tetap diterima walau `accepted`
  `false`. Penegakan sedang menunggu keputusan pemilik produk (lihat README bagian 13).
- Idempotency: satu catatan per karyawan per `policy_version`. Mengirim ulang versi yang sama
  memperbarui `consented_at`, tidak membuat catatan ganda.
- Rate limit: tidak ada.
- FeatureGate / modul: tidak ada.
- Status langganan: terkunci → 402.
