# Perjalanan Bisnis

Riwayat, detail, pengajuan, dan pembatalan perjalanan bisnis (dinas luar). Selama perjalanan bisnis
yang disetujui, presensi **tetap wajib** pada hari kerja, tetapi geofence lokasi kantor diabaikan dan
jendela jam presensi diperlebar. Konvensi umum ada di [README.md](README.md); dampaknya pada presensi
ada di [attendance.md](attendance.md) dan blok `business_trip` di [me.md](me.md#konfigurasi-aplikasi).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /business-trips`, `POST /business-trips`, `GET /business-trips/{businessTrip}`, `POST /business-trips/{businessTrip}/cancel` |
| Sumber kode | `BusinessTripController`, `StoreBusinessTripRequest`, `BusinessTripResource`, `BusinessTripService`, `BusinessTripDayCalculator`, `BusinessTripLookup` |
| Contoh direkam | 2026-10-22 dan 2026-11-04, direkam ulang 2026-10-23 setelah perubahan alur persetujuan, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, `APP_LOCALE=id` |
| Data uji | Citra Satu, jam tetap Senin–Jumat, Cuti Sakit 2026-10-21 disetujui. Alur persetujuan Citra: Tahap 1 Anton Satu (atasan langsung) → Tahap 2 Budi Satu (Kepala Departemen unit Anton, karena Anton tanpa atasan langsung) |

---

## Enum

### `ApprovalStatus` (`status`)

| Nilai | `status_label` | Dapat dibatalkan karyawan |
|---|---|---|
| `PENDING` | Menunggu Persetujuan | ya |
| `APPROVED` | Disetujui | ya, **hanya bila** `start_date` masih setelah hari ini (zona perusahaan) |
| `REJECTED` | Ditolak | tidak |
| `CANCELLED` | Dibatalkan | tidak |

`days[].schedule_status` memakai `ScheduleStatus` dari [attendance.md](attendance.md#schedulestatus-schedule_status).

---

## Objek `business_trip`

Sumber: `BusinessTripResource`. `days` hanya ada pada detail dan respons pengajuan.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID perjalanan |
| `letter_number` | string | ya | nomor surat tugas/referensi |
| `purpose` | string | tidak | maksud perjalanan |
| `destination_name` | string | tidak | nama lokasi tujuan |
| `destination_address` | string | ya | alamat tujuan |
| `destination_latitude` | number | ya | lintang tujuan; dipakai menandai presensi yang jauh dari tujuan |
| `destination_longitude` | number | ya | bujur tujuan |
| `start_date` | string (`YYYY-MM-DD`) | tidak | tanggal berangkat |
| `end_date` | string (`YYYY-MM-DD`) | tidak | tanggal kembali |
| `total_days` | integer | tidak | jumlah **hari kalender** dalam rentang, termasuk hari libur |
| `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 |
| `days` | array objek | — | hanya detail/pengajuan, lihat tabel di bawah |
| `approvals` | array objek | tidak | tahap persetujuan, lihat [koreksi presensi](attendance-corrections.md#objek-correction) |

**`days[]`**

| Field | Tipe | Keterangan |
|---|---|---|
| `work_date` | string (`YYYY-MM-DD`) | satu tanggal dalam rentang |
| `is_counted` | boolean | selalu `true` |
| `requires_attendance` | boolean | `true` bila tanggal itu hari kerja; presensi tetap wajib dan tercatat `BUSINESS_TRIP` |
| `schedule_status` | string (enum) | `ScheduleStatus` tanggal itu |
| `schedule_status_label` | string | label tampilan |

Lampiran tidak dikembalikan.

---

## Riwayat perjalanan bisnis

**`GET /business-trips`**

Deskripsi: perjalanan bisnis milik karyawan login, **50 terbaru** urut `start_date` terbaru di atas,
tanpa `days`. Tanpa pagination dan tanpa filter.

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

**Contoh Request**

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

**Contoh Response Sukses** (`200`, 2026-11-04 08:00 WIB)

```json
{
  "success": true,
  "message": "Riwayat perjalanan bisnis berhasil diambil.",
  "data": [
    {
      "id": 2,
      "letter_number": null,
      "purpose": "Mengantar dokumen tender ke kantor pelanggan.",
      "destination_name": "PT Karya Mandiri Bekasi",
      "destination_address": null,
      "destination_latitude": null,
      "destination_longitude": null,
      "start_date": "2026-11-12",
      "end_date": "2026-11-12",
      "total_days": 1,
      "status": "CANCELLED",
      "status_label": "Dibatalkan",
      "submitted_at": "2026-10-22T06:05:00+00:00",
      "decided_at": null,
      "cancelled_at": "2026-10-22T06:05: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
        }
      ]
    },
    {
      "id": 1,
      "letter_number": "PB/2026/10/021",
      "purpose": "Audit stok gudang mitra dan pelatihan staf penerimaan barang.",
      "destination_name": "Gudang Mitra Surabaya",
      "destination_address": "Jl. Margomulyo No. 44, Surabaya",
      "destination_latitude": -7.241387,
      "destination_longitude": 112.678269,
      "start_date": "2026-11-03",
      "end_date": "2026-11-06",
      "total_days": 4,
      "status": "APPROVED",
      "status_label": "Disetujui",
      "submitted_at": "2026-10-22T06:00:00+00:00",
      "decided_at": "2026-10-22T06:05:00+00:00",
      "cancelled_at": null,
      "decision_notes": "Disetujui.",
      "approvals": [
        {
          "sequence": 1,
          "stage_name": "Tahap 1",
          "approver": "Anton Satu",
          "status": "APPROVED",
          "status_label": "Disetujui",
          "decided_at": "2026-10-22T06:05: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-22T06:05:00+00:00",
          "decided_by": "Budi Satu",
          "notes": "Disetujui."
        }
      ]
    }
  ]
}
```

**Field `data[]`:** [objek `business_trip`](#objek-business_trip) tanpa `days`.

---

## Detail perjalanan bisnis

**`GET /business-trips/{businessTrip}`**

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

**Parameter:** `businessTrip` (path, integer).

**Contoh Request**

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

**Contoh Response Sukses** (`200`, 2026-10-22 13:05 WIB)

```json
{
  "success": true,
  "message": "Detail perjalanan bisnis berhasil diambil.",
  "data": {
    "id": 1,
    "letter_number": "PB/2026/10/021",
    "purpose": "Audit stok gudang mitra dan pelatihan staf penerimaan barang.",
    "destination_name": "Gudang Mitra Surabaya",
    "destination_address": "Jl. Margomulyo No. 44, Surabaya",
    "destination_latitude": -7.241387,
    "destination_longitude": 112.678269,
    "start_date": "2026-11-03",
    "end_date": "2026-11-06",
    "total_days": 4,
    "status": "PENDING",
    "status_label": "Menunggu Persetujuan",
    "submitted_at": "2026-10-22T06:00:00+00:00",
    "decided_at": null,
    "cancelled_at": null,
    "decision_notes": null,
    "days": [
      {
        "work_date": "2026-11-03",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-11-04",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-11-05",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-11-06",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      }
    ],
    "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
      }
    ]
  }
}
```

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| Milik karyawan lain di perusahaan yang sama | 403 | `Perjalanan bisnis ini bukan milik Anda.` |
| ID tidak ada atau milik perusahaan lain | 404 | `Sumber daya tidak ditemukan.` |

---

## Ajukan perjalanan bisnis

**`POST /business-trips`**

Deskripsi: mengajukan perjalanan bisnis untuk rentang tanggal. Server menyusun `days` dari Jadwal
Kerja dan menyusun penyetuju sesuai [alur persetujuan](attendance-corrections.md#alur-persetujuan).

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

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`, `Content-Type:
application/json` atau `multipart/form-data` (wajib multipart bila mengirim `attachment`)

**Parameter** (`StoreBusinessTripRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `start_date` | body | string (`YYYY-MM-DD`) | ya | `required`, `date` |
| `end_date` | body | string (`YYYY-MM-DD`) | ya | `required`, `date`, `after_or_equal:start_date` |
| `purpose` | body | string | ya | `required`, `string`, `min:10`, `max:1000` |
| `destination_name` | body | string | ya | `required`, `string`, `max:255` |
| `destination_address` | body | string | tidak | `nullable`, `string`, `max:255` |
| `destination_latitude` | body | number | bila ada `destination_longitude` | `nullable`, `required_with:destination_longitude`, `numeric`, `between:-90,90` |
| `destination_longitude` | body | number | bila ada `destination_latitude` | `nullable`, `required_with:destination_latitude`, `numeric`, `between:-180,180` |
| `letter_number` | body | string | tidak | `nullable`, `string`, `max:100` |
| `attachment` | body (part berkas) | berkas | tidak | `nullable`, `file`, `mimes:jpg,jpeg,png,pdf`, `max:2048` KB (pengaturan perusahaan) |

**Contoh Request** (multipart dengan surat tugas, 2026-10-22 13:00 WIB)

```http
POST /api/v1/business-trips HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=absenova

--absenova
Content-Disposition: form-data; name="start_date"

2026-11-03
--absenova
Content-Disposition: form-data; name="end_date"

2026-11-06
--absenova
Content-Disposition: form-data; name="purpose"

Audit stok gudang mitra dan pelatihan staf penerimaan barang.
--absenova
Content-Disposition: form-data; name="destination_name"

Gudang Mitra Surabaya
--absenova
Content-Disposition: form-data; name="destination_address"

Jl. Margomulyo No. 44, Surabaya
--absenova
Content-Disposition: form-data; name="destination_latitude"

-7.2413870
--absenova
Content-Disposition: form-data; name="destination_longitude"

112.6782690
--absenova
Content-Disposition: form-data; name="letter_number"

PB/2026/10/021
--absenova
Content-Disposition: form-data; name="attachment"; filename="surat-tugas.pdf"
Content-Type: application/pdf

(berkas PDF, 185 KB)
--absenova--
```

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

```json
{
  "success": true,
  "message": "Pengajuan perjalanan bisnis terkirim dan menunggu persetujuan Anton Satu.",
  "data": {
    "id": 1,
    "letter_number": "PB/2026/10/021",
    "purpose": "Audit stok gudang mitra dan pelatihan staf penerimaan barang.",
    "destination_name": "Gudang Mitra Surabaya",
    "destination_address": "Jl. Margomulyo No. 44, Surabaya",
    "destination_latitude": -7.241387,
    "destination_longitude": 112.678269,
    "start_date": "2026-11-03",
    "end_date": "2026-11-06",
    "total_days": 4,
    "status": "PENDING",
    "status_label": "Menunggu Persetujuan",
    "submitted_at": "2026-10-22T06:00:00+00:00",
    "decided_at": null,
    "cancelled_at": null,
    "decision_notes": null,
    "days": [
      {
        "work_date": "2026-11-03",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-11-04",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-11-05",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      },
      {
        "work_date": "2026-11-06",
        "is_counted": true,
        "requires_attendance": true,
        "schedule_status": "ON_DUTY",
        "schedule_status_label": "Masuk kerja"
      }
    ],
    "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
      }
    ]
  }
}
```

Tanpa koordinat dan lampiran (JSON):

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

{
  "start_date": "2026-11-12",
  "end_date": "2026-11-12",
  "purpose": "Mengantar dokumen tender ke kantor pelanggan.",
  "destination_name": "PT Karya Mandiri Bekasi"
}
```

```json
"message": "Pengajuan perjalanan bisnis terkirim dan menunggu persetujuan Anton Satu.",
"data": {
  "id": 2,
  "letter_number": null,
  "purpose": "Mengantar dokumen tender ke kantor pelanggan.",
  "destination_name": "PT Karya Mandiri Bekasi",
  "destination_address": null,
  "destination_latitude": null,
  "destination_longitude": null,
  "start_date": "2026-11-12",
  "end_date": "2026-11-12",
  "total_days": 1,
  "status": "PENDING",
  "status_label": "Menunggu Persetujuan",
  "submitted_at": "2026-10-22T06:05:00+00:00",
  "decided_at": null,
  "cancelled_at": null,
  "decision_notes": null,
  "days": [
    {
      "work_date": "2026-11-12",
      "is_counted": true,
      "requires_attendance": true,
      "schedule_status": "ON_DUTY",
      "schedule_status_label": "Masuk kerja"
    }
  ],
  "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 `business_trip`](#objek-business_trip) dengan `days`.

**Penolakan dan urutan pemeriksaan** (422, `errors.business_trip`)

| # | HTTP | `message` (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 422 | ✓ `Data yang dikirim tidak lolos pemeriksaan.` (validasi FormRequest) |
| 2 | 422 | ✓ `Periode rekap untuk tanggal mulai tersebut sudah dikunci sehingga tidak dapat diajukan lagi.` |
| 3 | 422 | ✓ `Sudah ada perjalanan bisnis lain yang beririsan tanggalnya dan belum dibatalkan.` |
| 4 | 422 | ✓ `Tanggal tersebut beririsan dengan pengajuan cuti yang masih berlaku.` |
| 5 | 422 | `Jadwal kerja pada {tanggal} belum lengkap: {status}. Hubungi Admin HR.` |

Tidak ada batas tanggal mundur maupun minimal hari sebelum berangkat.

Validasi (`end_date` sebelum `start_date`, `purpose: "Audit"`, tanpa `destination_name`, hanya
`destination_latitude`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "end_date": [
      "Kolom tanggal selesai harus berisi tanggal tanggal mulai atau setelahnya."
    ],
    "purpose": [
      "Kolom maksud perjalanan minimal 10 karakter."
    ],
    "destination_name": [
      "Kolom nama lokasi tujuan wajib diisi."
    ],
    "destination_longitude": [
      "Kolom bujur tujuan wajib diisi bila terdapat lintang tujuan."
    ]
  }
}
```

**Catatan**

- Idempotency: tidak ada kunci. Pengajuan kedua untuk tanggal yang beririsan ditolak (nomor 3).
- 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.
- Sesudah disetujui, pada hari perjalanan: `GET /me/config` mengirim blok `business_trip`, presensi
  tidak memeriksa geofence kantor, jendela jam diperlebar `policy.business_trip_window_extra_minutes`,
  dan presensi yang jauh dari koordinat tujuan ditandai `is_suspect`.
- Klaim biaya perjalanan diajukan lewat [reimbursements.md](reimbursements.md) dengan
  `business_trip_id`.
- Rate limit: tidak ada. FeatureGate / modul: `module_business_trip` (server tidak memblokir). Status
  langganan: terkunci → 402.

---

## Batalkan perjalanan bisnis

**`POST /business-trips/{businessTrip}/cancel`**

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

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

**Status yang dapat dibatalkan:** `PENDING` kapan saja; `APPROVED` hanya bila `start_date` masih
setelah hari ini. `REJECTED` dan `CANCELLED` tidak.

**Contoh Request**

```http
POST /api/v1/business-trips/2/cancel HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`). Respons pembatalan tidak memuat `days`:

```json
{
  "success": true,
  "message": "Pengajuan perjalanan bisnis dibatalkan.",
  "data": {
    "id": 2,
    "letter_number": null,
    "purpose": "Mengantar dokumen tender ke kantor pelanggan.",
    "destination_name": "PT Karya Mandiri Bekasi",
    "destination_address": null,
    "destination_latitude": null,
    "destination_longitude": null,
    "start_date": "2026-11-12",
    "end_date": "2026-11-12",
    "total_days": 1,
    "status": "CANCELLED",
    "status_label": "Dibatalkan",
    "submitted_at": "2026-10-22T06:05:00+00:00",
    "decided_at": null,
    "cancelled_at": "2026-10-22T06:05: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
      }
    ]
  }
}
```

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

| Kondisi | `message` |
|---|---|
| Sudah `CANCELLED`/`REJECTED` | ✓ `Pengajuan perjalanan bisnis ini sudah berstatus Dibatalkan.` |
| `APPROVED` dan sudah berjalan (2026-11-04 08:00 WIB, perjalanan 3–6 Nov) | ✓ `Perjalanan bisnis yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Ajukan koreksi presensi atau hubungi Admin HR.` |
| Milik karyawan lain (403) | `Perjalanan bisnis ini bukan milik Anda.` |

```json
{
  "success": false,
  "message": "Perjalanan bisnis yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Ajukan koreksi presensi atau hubungi Admin HR.",
  "errors": {
    "business_trip": [
      "Perjalanan bisnis yang sudah berjalan atau selesai tidak dapat dibatalkan karyawan. Ajukan koreksi presensi atau hubungi Admin HR."
    ]
  }
}
```

**Catatan:** rate limit tidak ada; FeatureGate `module_business_trip`; langganan terkunci → 402.
