# Lembur

Riwayat, detail, pengajuan, dan pembatalan lembur oleh karyawan. Jenis lembur ditentukan **server**
dari jadwal tanggal kerja; client hanya mengirim tanggal dan jam. Konvensi umum ada di
[README.md](README.md); presensi pada hari lembur ada di [attendance.md](attendance.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /overtimes`, `POST /overtimes`, `GET /overtimes/{overtime}`, `POST /overtimes/{overtime}/cancel` |
| Sumber kode | `OvertimeController`, `StoreOvertimeRequest`, `OvertimeResource`, `OvertimeService`, `OvertimeCalculator`, `OvertimeQuota`, `OvertimeRealizer`, `OvertimePricer` |
| Contoh direkam | 2026-10-22, direkam ulang 2026-10-23 setelah perubahan alur persetujuan, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan (`nusantara-logistik` WIB, `borneo-retail` WITA), `APP_LOCALE=id`. Jam server dipasang per skenario |
| Data uji | Citra Satu: jam tetap 08:00–17:00 Senin–Jumat, Sabtu–Minggu libur, 2026-10-30 libur perusahaan di Jadwal Kerja. Pengaturan lembur bawaan: minimal 30 menit, pembulatan 15 menit, maks. 4 jam/hari, 18 jam/minggu, mundur maks. 3 hari. Tarif Standar: Rp32.000/jam hari kerja, Rp48.000 libur mingguan, Rp64.000 libur nasional. Alur persetujuan Citra: Tahap 1 Anton Satu (atasan langsung) → Tahap 2 Budi Satu (Kepala Departemen unit Anton, karena Anton tanpa atasan langsung) |

---

## Enum

### `OvertimeType` (`overtime_type`)

| Nilai | `overtime_type_label` | Ditentukan server bila |
|---|---|---|
| `BEFORE_SHIFT` | Sebelum Jam Kerja | tanggal kerja berjadwal masuk dan jam lembur berakhir paling lambat jam mulai shift |
| `AFTER_SHIFT` | Sesudah Jam Kerja | tanggal kerja berjadwal masuk dan jam lembur dimulai paling cepat jam selesai shift |
| `REST_DAY` | Hari Libur Mingguan | Jadwal Kerja tanggal itu berstatus libur (`OFF_DUTY`) |
| `HOLIDAY` | Hari Libur Nasional | tanggal itu hari libur (kalender libur atau Jadwal Kerja berstatus `HOLIDAY`, termasuk libur perusahaan) |

Pada hari kerja, jam yang beririsan dengan jam shift ditolak. Untuk shift malam server mencoba tanggal
sebelum/sesudah dan memilih celah terdekat dengan shift.

### `ApprovalStatus` (`status`)

| Nilai | `status_label` | Dapat dibatalkan karyawan |
|---|---|---|
| `PENDING` | Menunggu Persetujuan | ya |
| `APPROVED` | Disetujui | ya, **hanya sebelum** `planned_start_at` |
| `REJECTED` | Ditolak | tidak |
| `CANCELLED` | Dibatalkan | tidak |

---

## Objek `overtime`

Dipakai seluruh endpoint modul ini. Sumber: `OvertimeResource`.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID lembur |
| `work_date` | string (`YYYY-MM-DD`) | tidak | tanggal kerja yang diajukan |
| `overtime_type` | string (enum) | tidak | `OvertimeType`, ditentukan server |
| `overtime_type_label` | string | tidak | label tampilan |
| `planned_start_at` | string (ISO 8601 UTC) | tidak | jam mulai rencana |
| `planned_end_at` | string (ISO 8601 UTC) | tidak | jam selesai rencana; bisa tanggal berikutnya bila melewati tengah malam |
| `planned_minutes` | integer | tidak | durasi rencana dalam menit |
| `actual_start_at` | string (ISO 8601 UTC) | ya | jam mulai realisasi; `null` sebelum direalisasi |
| `actual_end_at` | string (ISO 8601 UTC) | ya | jam selesai realisasi |
| `actual_minutes` | integer | ya | menit realisasi; `null` sebelum direalisasi, `0` setelah dibatalkan |
| `payable_minutes` | integer | ya | menit dibayar = realisasi dibulatkan ke bawah kelipatan `policy.overtime.rounding_minutes`, tidak melebihi `planned_minutes`, dan tidak melewati sisa batas harian/mingguan |
| `hourly_rate` | integer | ya | tarif per jam dalam **rupiah bilangan bulat** sesuai jenis lembur; `null` sebelum direalisasi atau bila perusahaan belum mengatur tarif |
| `amount` | integer | ya | nominal lembur rupiah bilangan bulat = `round(payable_minutes × hourly_rate / 60)`; `null` bila `hourly_rate` `null` |
| `realized_at` | string (ISO 8601 UTC) | ya | waktu realisasi dicatat |
| `realization_notes` | string | ya | catatan realisasi |
| `reason` | string | tidak | alasan dari karyawan |
| `status` | string (enum) | tidak | `ApprovalStatus` |
| `status_label` | string | tidak | label tampilan |
| `submitted_at` | string (ISO 8601 UTC) | tidak | waktu pengajuan |
| `decided_at` | string (ISO 8601 UTC) | ya | waktu keputusan akhir |
| `cancelled_at` | string (ISO 8601 UTC) | ya | waktu pembatalan |
| `decision_notes` | string | ya | catatan keputusan akhir |
| `approvals` | array objek | tidak | tahap persetujuan, struktur sama dengan [koreksi presensi](attendance-corrections.md#objek-correction) |

**Realisasi** dicatat Admin HR (Catat Realisasi) atau dihitung dari presensi oleh perintah
`overtime:realize`. Sampai realisasi tercatat, field `actual_*`, `payable_minutes`, `hourly_rate`, dan
`amount` bernilai `null`. Nominal dibekukan saat realisasi; perubahan tarif sesudahnya tidak mengubah
nominal kecuali Admin HR menjalankan **Terapkan ke Lembur**.

---

## Riwayat lembur

**`GET /overtimes`**

Deskripsi: daftar lembur milik karyawan login, **50 terbaru** urut `work_date` terbaru di atas. Tanpa
pagination dan tanpa filter. Lembur dengan `work_date` sama tidak dijamin urutannya.

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

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

**Parameter:** tidak ada.

**Contoh Request**

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

**Contoh Response Sukses** (`200`, 2026-10-24 10:00 WIB, dipotong menjadi 2 dari 6 item)

```json
{
  "success": true,
  "message": "Riwayat lembur berhasil diambil.",
  "data": [
    {
      "id": 6,
      "work_date": "2026-10-30",
      "overtime_type": "HOLIDAY",
      "overtime_type_label": "Hari Libur Nasional",
      "planned_start_at": "2026-10-30T02:00:00+00:00",
      "planned_end_at": "2026-10-30T05:00:00+00:00",
      "planned_minutes": 180,
      "actual_start_at": null,
      "actual_end_at": null,
      "actual_minutes": 0,
      "payable_minutes": 0,
      "hourly_rate": null,
      "amount": null,
      "realized_at": null,
      "realization_notes": null,
      "reason": "Jaga gudang saat libur ulang tahun perusahaan.",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "submitted_at": "2026-10-22T03:06:00+00:00",
      "decided_at": null,
      "cancelled_at": null,
      "decision_notes": null,
      "approvals": [
        {
          "sequence": 1,
          "stage_name": "Tahap 1",
          "approver": "Anton Satu",
          "status": "PENDING",
          "status_label": "Menunggu Persetujuan",
          "decided_at": null,
          "decided_by": null,
          "notes": null
        },
        {
          "sequence": 2,
          "stage_name": "Tahap 2",
          "approver": "Budi Satu",
          "status": "PENDING",
          "status_label": "Menunggu Persetujuan",
          "decided_at": null,
          "decided_by": null,
          "notes": null
        }
      ]
    },
    {
      "id": 5,
      "work_date": "2026-10-25",
      "overtime_type": "REST_DAY",
      "overtime_type_label": "Hari Libur Mingguan",
      "planned_start_at": "2026-10-25T01:00:00+00:00",
      "planned_end_at": "2026-10-25T04:00:00+00:00",
      "planned_minutes": 180,
      "actual_start_at": null,
      "actual_end_at": null,
      "actual_minutes": 0,
      "payable_minutes": 0,
      "hourly_rate": null,
      "amount": null,
      "realized_at": null,
      "realization_notes": null,
      "reason": "Pindahan rak gudang ke area baru.",
      "status": "CANCELLED",
      "status_label": "Dibatalkan",
      "submitted_at": "2026-10-22T03:04:00+00:00",
      "decided_at": "2026-10-22T03:20:00+00:00",
      "cancelled_at": "2026-10-22T03:25:00+00:00",
      "decision_notes": "Disetujui.",
      "approvals": [
        {
          "sequence": 1,
          "stage_name": "Tahap 1",
          "approver": "Anton Satu",
          "status": "APPROVED",
          "status_label": "Disetujui",
          "decided_at": "2026-10-22T03:20:00+00:00",
          "decided_by": "Anton Satu",
          "notes": "Disetujui, sesuai kebutuhan operasional."
        },
        {
          "sequence": 2,
          "stage_name": "Tahap 2",
          "approver": "Budi Satu",
          "status": "APPROVED",
          "status_label": "Disetujui",
          "decided_at": "2026-10-22T03:20:00+00:00",
          "decided_by": "Budi Satu",
          "notes": "Disetujui."
        }
      ]
    }
  ]
}
```

**Field `data[]`:** [objek `overtime`](#objek-overtime).

**Catatan**

- Urutan `work_date` menurun, batas 50, tanpa `meta`/`links`.
- Rate limit: tidak ada. Idempotency: tidak relevan.
- FeatureGate / modul: `module_overtime` (server tidak memblokir).
- Status langganan: terkunci → 402.

---

## Detail lembur

**`GET /overtimes/{overtime}`**

Deskripsi: satu lembur milik karyawan login.

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

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan |
|---|---|---|---|---|
| `overtime` | path | integer | ya | ID lembur |

**Contoh Request**

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

**Contoh Response Sukses** (`200`). Lembur `AFTER_SHIFT` yang sudah direalisasi: realisasi 185 menit,
dibulatkan 180 menit, tarif hari kerja Rp32.000 → Rp96.000:

```json
{
  "success": true,
  "message": "Detail lembur berhasil diambil.",
  "data": {
    "id": 1,
    "work_date": "2026-10-20",
    "overtime_type": "AFTER_SHIFT",
    "overtime_type_label": "Sesudah Jam Kerja",
    "planned_start_at": "2026-10-20T10:00:00+00:00",
    "planned_end_at": "2026-10-20T13:00:00+00:00",
    "planned_minutes": 180,
    "actual_start_at": "2026-10-20T10:00:00+00:00",
    "actual_end_at": "2026-10-20T13:05:00+00:00",
    "actual_minutes": 185,
    "payable_minutes": 180,
    "hourly_rate": 32000,
    "amount": 96000,
    "realized_at": "2026-10-22T03:20:00+00:00",
    "realization_notes": "Realisasi sesuai catatan supervisor gudang.",
    "reason": "Bongkar muat kiriman tambahan dari pelabuhan",
    "status": "APPROVED",
    "status_label": "Disetujui",
    "submitted_at": "2026-10-19T03:00:00+00:00",
    "decided_at": "2026-10-19T08:00:00+00:00",
    "cancelled_at": null,
    "decision_notes": null,
    "approvals": []
  }
}
```

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Lembur milik karyawan lain di perusahaan yang sama | 403 | `Pengajuan lembur ini bukan milik Anda.` |
| ID tidak ada atau milik perusahaan lain | 404 | `Sumber daya tidak ditemukan.` |
| Token tidak sah | 401 | `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |

```json
{
  "success": false,
  "message": "Pengajuan lembur ini bukan milik Anda.",
  "errors": {}
}
```

---

## Ajukan lembur

**`POST /overtimes`**

Deskripsi: mengajukan lembur untuk satu tanggal kerja. Server menentukan jenis, menghitung durasi,
memeriksa batas dan irisan, lalu menyusun penyetuju sesuai [alur
persetujuan](attendance-corrections.md#alur-persetujuan).

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

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

**Parameter** (`StoreOvertimeRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `work_date` | body | string (`YYYY-MM-DD`) | ya | `required`, `date`. Tanggal kerja; untuk lembur sesudah shift malam, tanggal mulai shift |
| `start_time` | body | string (`HH:mm`) | ya | `required`, `date_format:H:i`, 24 jam (`17:00`, bukan `17.00`). Jam lokal zona perusahaan |
| `end_time` | body | string (`HH:mm`) | ya | `required`, `date_format:H:i`. Bila tidak lebih akhir dari `start_time`, dianggap hari berikutnya (`22:00`–`02:00`) |
| `reason` | body | string | ya | `required`, `string`, `min:10`, `max:1000` |

`overtime_type`, `planned_minutes`, dan nominal **tidak** dikirim client; nilainya dihitung server.

**Contoh Request** (2026-10-22 10:00 WIB)

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

{
  "work_date": "2026-10-23",
  "start_time": "17:00",
  "end_time": "19:00",
  "reason": "Menyelesaikan rekap pengiriman akhir pekan."
}
```

**Contoh Response Sukses** (`201`)

```json
{
  "success": true,
  "message": "Pengajuan lembur terkirim dan menunggu persetujuan Anton Satu.",
  "data": {
    "id": 3,
    "work_date": "2026-10-23",
    "overtime_type": "AFTER_SHIFT",
    "overtime_type_label": "Sesudah Jam Kerja",
    "planned_start_at": "2026-10-23T10:00:00+00:00",
    "planned_end_at": "2026-10-23T12:00:00+00:00",
    "planned_minutes": 120,
    "actual_start_at": null,
    "actual_end_at": null,
    "actual_minutes": null,
    "payable_minutes": null,
    "hourly_rate": null,
    "amount": null,
    "realized_at": null,
    "realization_notes": null,
    "reason": "Menyelesaikan rekap pengiriman akhir pekan.",
    "status": "PENDING",
    "status_label": "Menunggu Persetujuan",
    "submitted_at": "2026-10-22T03:00:00+00:00",
    "decided_at": null,
    "cancelled_at": null,
    "decision_notes": null,
    "approvals": [
      {
        "sequence": 1,
        "stage_name": "Tahap 1",
        "approver": "Anton Satu",
        "status": "PENDING",
        "status_label": "Menunggu Persetujuan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      },
      {
        "sequence": 2,
        "stage_name": "Tahap 2",
        "approver": "Budi Satu",
        "status": "PENDING",
        "status_label": "Menunggu Persetujuan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      }
    ]
  }
}
```

Variasi sukses yang direkam (isi `message` dan `data` saja, `approvals` sama dengan contoh di atas):

Sebelum jam kerja, 06:00–07:30:

```json
"message": "Pengajuan lembur terkirim dan menunggu persetujuan Anton Satu.",
"data": {
  "id": 4,
  "work_date": "2026-10-23",
  "overtime_type": "BEFORE_SHIFT",
  "overtime_type_label": "Sebelum Jam Kerja",
  "planned_start_at": "2026-10-22T23:00:00+00:00",
  "planned_end_at": "2026-10-23T00:30:00+00:00",
  "planned_minutes": 90,
  "actual_start_at": null,
  "actual_end_at": null,
  "actual_minutes": null,
  "payable_minutes": null,
  "hourly_rate": null,
  "amount": null,
  "realized_at": null,
  "realization_notes": null,
  "reason": "Menyiapkan muatan armada pagi sebelum jam kerja.",
  "status": "PENDING",
  "status_label": "Menunggu Persetujuan",
  "submitted_at": "2026-10-22T03:02:00+00:00",
  "decided_at": null,
  "cancelled_at": null,
  "decision_notes": null,
  "approvals": [
    {
      "sequence": 1,
      "stage_name": "Tahap 1",
      "approver": "Anton Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    },
    {
      "sequence": 2,
      "stage_name": "Tahap 2",
      "approver": "Budi Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    }
  ]
}
```

Hari Libur Mingguan, Minggu 2026-10-25 08:00–11:00:

```json
"message": "Pengajuan lembur terkirim dan menunggu persetujuan Anton Satu.",
"data": {
  "id": 5,
  "work_date": "2026-10-25",
  "overtime_type": "REST_DAY",
  "overtime_type_label": "Hari Libur Mingguan",
  "planned_start_at": "2026-10-25T01:00:00+00:00",
  "planned_end_at": "2026-10-25T04:00:00+00:00",
  "planned_minutes": 180,
  "actual_start_at": null,
  "actual_end_at": null,
  "actual_minutes": null,
  "payable_minutes": null,
  "hourly_rate": null,
  "amount": null,
  "realized_at": null,
  "realization_notes": null,
  "reason": "Pindahan rak gudang ke area baru.",
  "status": "PENDING",
  "status_label": "Menunggu Persetujuan",
  "submitted_at": "2026-10-22T03:04:00+00:00",
  "decided_at": null,
  "cancelled_at": null,
  "decision_notes": null,
  "approvals": [
    {
      "sequence": 1,
      "stage_name": "Tahap 1",
      "approver": "Anton Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    },
    {
      "sequence": 2,
      "stage_name": "Tahap 2",
      "approver": "Budi Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    }
  ]
}
```

Libur perusahaan di Jadwal Kerja (Jumat 2026-10-30), tercatat `HOLIDAY`:

```json
"message": "Pengajuan lembur terkirim dan menunggu persetujuan Anton Satu.",
"data": {
  "id": 6,
  "work_date": "2026-10-30",
  "overtime_type": "HOLIDAY",
  "overtime_type_label": "Hari Libur Nasional",
  "planned_start_at": "2026-10-30T02:00:00+00:00",
  "planned_end_at": "2026-10-30T05:00:00+00:00",
  "planned_minutes": 180,
  "actual_start_at": null,
  "actual_end_at": null,
  "actual_minutes": null,
  "payable_minutes": null,
  "hourly_rate": null,
  "amount": null,
  "realized_at": null,
  "realization_notes": null,
  "reason": "Jaga gudang saat libur ulang tahun perusahaan.",
  "status": "PENDING",
  "status_label": "Menunggu Persetujuan",
  "submitted_at": "2026-10-22T03:06:00+00:00",
  "decided_at": null,
  "cancelled_at": null,
  "decision_notes": null,
  "approvals": [
    {
      "sequence": 1,
      "stage_name": "Tahap 1",
      "approver": "Anton Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    },
    {
      "sequence": 2,
      "stage_name": "Tahap 2",
      "approver": "Budi Satu",
      "status": "PENDING",
      "status_label": "Menunggu Persetujuan",
      "decided_at": null,
      "decided_by": null,
      "notes": null
    }
  ]
}
```

**Field `data`:** [objek `overtime`](#objek-overtime).

**Penolakan dan urutan pemeriksaan**

Seluruh penolakan aturan bisnis dijawab **422** dengan `errors.overtime`.

| # | HTTP | `message` (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 401 / 402 | token tidak sah / langganan terkunci |
| 2 | 422 | ✓ `Data yang dikirim tidak lolos pemeriksaan.` (validasi FormRequest) |
| 3 | 422 | `schedule_message` tanggal itu bila jadwal tidak dapat ditentukan, mis. `Karyawan belum memiliki pola shift. Hubungi Admin HR.` |
| 4 | 422 | ✓ `Jam lembur beririsan dengan jam kerja terjadwal 08:00–17:00. Lembur hanya dihitung di luar jam kerja.` |
| 5 | 422 | `Jam lembur beririsan dengan shift {nama} pada {tanggal} ({jam mulai}–{jam selesai}).` (irisan dengan shift tanggal sebelum/sesudah) |
| 6 | 422 | ✓ `Durasi lembur minimal 30 menit, sedangkan pengajuan ini 20 menit.` |
| 7 | 422 | ✓ `Batas lembur harian 4 jam terlampaui. Pada tanggal 2026-10-23 sudah tercatat 3 jam 30 menit dan pengajuan ini menambah 2 jam.` |
| 8 | 422 | `Batas lembur mingguan 18 jam terlampaui. Pada minggu tanggal {tanggal} sudah tercatat {durasi}.` |
| 9 | 422 | ✓ `Sudah ada pengajuan lembur lain yang beririsan jamnya dan belum dibatalkan.` |
| 10 | 422 | `Tanggal tersebut beririsan dengan pengajuan cuti yang masih berlaku.` |
| 11 | 422 | ✓ `Periode rekap untuk tanggal tersebut sudah dikunci sehingga tidak dapat diajukan lagi.` |
| 12 | 422 | ✓ `Lembur hanya dapat diajukan mundur paling lama 3 hari. Ajukan lewat Admin HR untuk tanggal yang lebih lama.` |

Batas harian dan mingguan menghitung lembur `PENDING` dan `APPROVED` (rencana), bukan yang ditolak
atau dibatalkan. Angka batas mengikuti `policy.overtime` di `me/config`.

Validasi (`start_time: "17.00"`, `end_time: "7 malam"`, `reason: "Lembur"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "start_time": [
      "Kolom jam mulai tidak sesuai format H:i."
    ],
    "end_time": [
      "Kolom jam selesai tidak sesuai format H:i."
    ],
    "reason": [
      "Kolom alasan lembur minimal 10 karakter."
    ]
  }
}
```

Penolakan aturan bisnis (16:00–18:00 pada hari kerja 08:00–17:00):

```json
{
  "success": false,
  "message": "Jam lembur beririsan dengan jam kerja terjadwal 08:00–17:00. Lembur hanya dihitung di luar jam kerja.",
  "errors": {
    "overtime": [
      "Jam lembur beririsan dengan jam kerja terjadwal 08:00–17:00. Lembur hanya dihitung di luar jam kerja."
    ]
  }
}
```

**Catatan**

- Idempotency: tidak ada kunci. Pengajuan kedua untuk jam yang sama ditolak oleh aturan irisan
  (nomor 9), tetapi client tetap wajib menonaktifkan tombol selama request berjalan.
- Penyetuju disusun server saat pengajuan dibuat dan disimpan pada `approvals`; lihat
  [alur persetujuan](attendance-corrections.md#alur-persetujuan). `message` sukses menyebut
  penyetuju Tahap 1, atau `Admin HR` bila karyawan tidak memiliki penyetuju berjenjang.
- Lembur `REST_DAY`/`HOLIDAY` yang disetujui membuka presensi pada hari libur itu; lihat
  [attendance.md](attendance.md).
- Rate limit: tidak ada.
- FeatureGate / modul: `module_overtime` (server tidak memblokir).
- Status langganan: terkunci → 402.

---

## Batalkan lembur

**`POST /overtimes/{overtime}/cancel`**

Deskripsi: karyawan membatalkan lembur miliknya. Tahap persetujuan yang belum diputuskan ikut
dibatalkan.

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

**Parameter:** `overtime` (path, integer). Tanpa body.

**Status yang dapat dibatalkan:** `PENDING` kapan saja; `APPROVED` hanya selama `planned_start_at`
belum lewat. `REJECTED` dan `CANCELLED` tidak dapat dibatalkan.

**Contoh Request**

```http
POST /api/v1/overtimes/3/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, lembur `PENDING`)

```json
{
  "success": true,
  "message": "Pengajuan lembur dibatalkan.",
  "data": {
    "id": 3,
    "work_date": "2026-10-23",
    "overtime_type": "AFTER_SHIFT",
    "overtime_type_label": "Sesudah Jam Kerja",
    "planned_start_at": "2026-10-23T10:00:00+00:00",
    "planned_end_at": "2026-10-23T12:00:00+00:00",
    "planned_minutes": 120,
    "actual_start_at": null,
    "actual_end_at": null,
    "actual_minutes": 0,
    "payable_minutes": 0,
    "hourly_rate": null,
    "amount": null,
    "realized_at": null,
    "realization_notes": null,
    "reason": "Menyelesaikan rekap pengiriman akhir pekan.",
    "status": "CANCELLED",
    "status_label": "Dibatalkan",
    "submitted_at": "2026-10-22T03:00:00+00:00",
    "decided_at": null,
    "cancelled_at": "2026-10-22T03:25:00+00:00",
    "decision_notes": null,
    "approvals": [
      {
        "sequence": 1,
        "stage_name": "Tahap 1",
        "approver": "Anton Satu",
        "status": "CANCELLED",
        "status_label": "Dibatalkan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      },
      {
        "sequence": 2,
        "stage_name": "Tahap 2",
        "approver": "Budi Satu",
        "status": "CANCELLED",
        "status_label": "Dibatalkan",
        "decided_at": null,
        "decided_by": null,
        "notes": null
      }
    ]
  }
}
```

Lembur `APPROVED` yang belum dimulai (`200`, isi `message` dan `data` saja):

```json
"message": "Pengajuan lembur dibatalkan.",
"data": {
  "id": 5,
  "work_date": "2026-10-25",
  "overtime_type": "REST_DAY",
  "overtime_type_label": "Hari Libur Mingguan",
  "planned_start_at": "2026-10-25T01:00:00+00:00",
  "planned_end_at": "2026-10-25T04:00:00+00:00",
  "planned_minutes": 180,
  "actual_start_at": null,
  "actual_end_at": null,
  "actual_minutes": 0,
  "payable_minutes": 0,
  "hourly_rate": null,
  "amount": null,
  "realized_at": null,
  "realization_notes": null,
  "reason": "Pindahan rak gudang ke area baru.",
  "status": "CANCELLED",
  "status_label": "Dibatalkan",
  "submitted_at": "2026-10-22T03:04:00+00:00",
  "decided_at": "2026-10-22T03:20:00+00:00",
  "cancelled_at": "2026-10-22T03:25:00+00:00",
  "decision_notes": "Disetujui.",
  "approvals": [
    {
      "sequence": 1,
      "stage_name": "Tahap 1",
      "approver": "Anton Satu",
      "status": "APPROVED",
      "status_label": "Disetujui",
      "decided_at": "2026-10-22T03:20:00+00:00",
      "decided_by": "Anton Satu",
      "notes": "Disetujui, sesuai kebutuhan operasional."
    },
    {
      "sequence": 2,
      "stage_name": "Tahap 2",
      "approver": "Budi Satu",
      "status": "APPROVED",
      "status_label": "Disetujui",
      "decided_at": "2026-10-22T03:20:00+00:00",
      "decided_by": "Budi Satu",
      "notes": "Disetujui."
    }
  ]
}
```

**Contoh Response Error** (`422`, `errors.overtime`)

| Kondisi | `message` |
|---|---|
| Sudah `CANCELLED` atau `REJECTED` | ✓ `Pengajuan lembur ini sudah berstatus Dibatalkan.` |
| `APPROVED` dan `planned_start_at` sudah lewat | ✓ `Lembur yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Hubungi Admin HR.` |
| Milik karyawan lain (403) | `Pengajuan lembur ini bukan milik Anda.` |

```json
{
  "success": false,
  "message": "Lembur yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Hubungi Admin HR.",
  "errors": {
    "overtime": [
      "Lembur yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Hubungi Admin HR."
    ]
  }
}
```

**Catatan**

- Idempotency: memanggil ulang pembatalan dijawab 422 `...sudah berstatus Dibatalkan.`; anggap sukses
  di client bila status lokal sudah `CANCELLED`.
- Rate limit: tidak ada. FeatureGate: `module_overtime`. Status langganan: terkunci → 402.
