# Kunjungan Klien

Daftar klien, check-in dan check-out kunjungan lapangan (tim sales, teknisi, kurir), pembatalan, dan
riwayat. Kunjungan **bukan** presensi kerja: tidak memengaruhi rekap presensi, tetapi check-out yang
berhasil menambah aktivitas otomatis ke [timesheet](timesheets.md). Konvensi umum ada di
[README.md](README.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /clients`, `GET /client-visits`, `GET /client-visits/open`, `POST /client-visits/check-in`, `GET /client-visits/{clientVisit}`, `POST /client-visits/{clientVisit}/check-out`, `POST /client-visits/{clientVisit}/cancel` |
| Sumber kode | `ClientVisitController`, `StoreClientVisitRequest`, `StoreClientVisitCheckOutRequest`, `ClientResource`, `ClientVisitResource`, `ClientVisitService`, `TimesheetService` |
| Contoh direkam | 2026-11-10, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, `APP_LOCALE=id` |
| Data uji | Citra Satu. Klien PT Sinar Jaya Abadi (aktif, radius 300 m, pemilik akun Citra), CV Maju Bersama (calon pelanggan, radius kosong), PT Lama Tidak Aktif. Pengaturan bawaan: foto wajib maks. 500 KB, radius bawaan 300 m, durasi minimal 5 menit, kunjungan terbuka maks. 12 jam, toleransi kirim 24 jam |

---

## Enum

### `ClientVisitPurpose` (`purpose`)

| Nilai | `purpose_label` |
|---|---|
| `SALES_CALL` | Kunjungan Penjualan |
| `PRESENTATION` | Presentasi Produk |
| `NEGOTIATION` | Negosiasi |
| `DELIVERY` | Pengiriman Barang |
| `MAINTENANCE` | Perawatan & Perbaikan |
| `COLLECTION` | Penagihan |
| `SURVEY` | Survei Lokasi |
| `OTHER` | Lainnya |

### `ClientVisitStatus` (`status`)

| Nilai | `status_label` | Dapat check-out / dibatalkan |
|---|---|---|
| `ONGOING` | Sedang Berlangsung | ya |
| `COMPLETED` | Selesai | tidak |
| `CANCELLED` | Dibatalkan | tidak |

### `ClientVisitOutcome` (`outcome`)

| Nilai | `outcome_label` |
|---|---|
| `SUCCESSFUL` | Berhasil |
| `FOLLOW_UP` | Perlu Tindak Lanjut |
| `POSTPONED` | Ditunda Klien |
| `FAILED` | Tidak Berhasil |

### `ClientStatus` (`clients[].status`)

| Nilai | `status_label` | Muncul di `GET /clients` |
|---|---|---|
| `PROSPECT` | Calon Pelanggan | ya |
| `ACTIVE` | Pelanggan Aktif | ya |
| `INACTIVE` | Tidak Aktif | tidak; check-in dengan `client_id` klien ini ditolak |

---

## Daftar klien

**`GET /clients`**

Deskripsi: klien perusahaan yang dapat dikunjungi (`PROSPECT` dan `ACTIVE`), urut nama, **maksimal
200**. Tanpa pagination.

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

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan |
|---|---|---|---|---|
| `search` | query | string | tidak | mencocokkan sebagian nama atau kode klien. Tanpa validasi |

**Contoh Request**

```http
GET /api/v1/clients?search=sinar HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, tanpa `search`)

```json
{
  "success": true,
  "message": "Daftar klien berhasil diambil.",
  "data": [
    {
      "id": 2,
      "code": "CL-0002",
      "name": "CV Maju Bersama",
      "status": "PROSPECT",
      "status_label": "Calon Pelanggan",
      "industry": "Ritel",
      "contact_person": "Lina Kartika",
      "contact_phone": "0218880456",
      "address": "Jl. Pemuda No. 102",
      "city": "Jakarta Timur",
      "latitude": -6.193441,
      "longitude": 106.8907722,
      "radius_meters": null,
      "is_account_owner": false
    },
    {
      "id": 1,
      "code": "CL-0001",
      "name": "PT Sinar Jaya Abadi",
      "status": "ACTIVE",
      "status_label": "Pelanggan Aktif",
      "industry": "Distribusi Bahan Bangunan",
      "contact_person": "Hendra Wijaya",
      "contact_phone": "0215550123",
      "address": "Jl. Gunung Sahari Raya No. 21",
      "city": "Jakarta Pusat",
      "latitude": -6.1612301,
      "longitude": 106.8394562,
      "radius_meters": 300,
      "is_account_owner": true
    }
  ]
}
```

**Field `data[]`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | dipakai sebagai `client_id` saat check-in |
| `code` | string | ya | kode klien |
| `name` | string | tidak | nama klien |
| `status` | string (enum) | tidak | `ClientStatus` |
| `status_label` | string | tidak | label tampilan |
| `industry` | string | ya | bidang usaha |
| `contact_person` | string | ya | nama kontak |
| `contact_phone` | string | ya | telepon kontak |
| `address` | string | ya | alamat |
| `city` | string | ya | kota |
| `latitude` | number | ya | lintang lokasi klien; `null` bila belum dipetakan |
| `longitude` | number | ya | bujur lokasi klien |
| `radius_meters` | integer | ya | radius klien; `null` → server memakai `policy.client_visit.radius_meters` |
| `is_account_owner` | boolean | tidak | `true` bila karyawan login pemegang akun klien ini |

---

## Objek `client_visit`

Sumber: `ClientVisitResource`. Dipakai seluruh endpoint kunjungan.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID kunjungan, dipakai untuk check-out dan pembatalan |
| `uuid` | string | tidak | UUID dari client saat check-in |
| `work_date` | string (`YYYY-MM-DD`) | tidak | tanggal kerja (tanggal mulai shift, ikut lembur lintas tengah malam) |
| `client_id` | integer | ya | klien terdaftar; `null` untuk klien teks bebas |
| `client_name` | string | tidak | nama klien terdaftar atau teks bebas |
| `purpose` | string (enum) | tidak | `ClientVisitPurpose` |
| `purpose_label` | string | tidak | label tampilan |
| `status` | string (enum) | tidak | `ClientVisitStatus` |
| `status_label` | string | tidak | label tampilan |
| `checked_in_at` | string (ISO 8601 UTC) | tidak | `captured_at` check-in |
| `checked_out_at` | string (ISO 8601 UTC) | ya | `captured_at` check-out |
| `duration_minutes` | integer | ya | menit kunjungan; `null` selama berlangsung, `0` bila dibatalkan |
| `distance_meters` | integer | ya | jarak check-in ke koordinat klien; `null` bila klien tanpa koordinat atau teks bebas |
| `is_within_radius` | boolean | tidak | `true` bila `distance_meters - accuracy_meters <= radius`; selalu `true` bila jarak tidak diukur |
| `outcome` | string (enum) | ya | `ClientVisitOutcome`, diisi saat check-out |
| `outcome_label` | string | ya | label tampilan |
| `notes` | string | ya | catatan check-in; diganti catatan check-out bila dikirim |
| `follow_up_date` | string (`YYYY-MM-DD`) | ya | tanggal tindak lanjut |
| `is_suspect` | boolean | tidak | ditandai untuk ditinjau Admin HR, lihat tabel penanda di check-in |
| `cancel_reason` | string | ya | alasan pembatalan |

Foto kunjungan dan koordinat check-out tidak dikembalikan.

---

## Riwayat kunjungan

**`GET /client-visits`**

Deskripsi: kunjungan milik karyawan login, **50 terbaru** urut `checked_in_at` terbaru di atas.

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

**Contoh Request**

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

**Contoh Response Sukses** (`200`, 2026-11-10 16:00 WIB)

```json
{
  "success": true,
  "message": "Riwayat kunjungan klien berhasil diambil.",
  "data": [
    {
      "id": 3,
      "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30003",
      "work_date": "2026-11-10",
      "client_id": null,
      "client_name": "Toko Bangunan Sentosa",
      "purpose": "SURVEY",
      "purpose_label": "Survei Lokasi",
      "status": "ONGOING",
      "status_label": "Sedang Berlangsung",
      "checked_in_at": "2026-11-10T08:20:00+00:00",
      "checked_out_at": null,
      "duration_minutes": 0,
      "distance_meters": null,
      "is_within_radius": true,
      "outcome": null,
      "outcome_label": null,
      "notes": "Calon pelanggan baru, survei kebutuhan.",
      "follow_up_date": null,
      "is_suspect": true,
      "cancel_reason": null
    },
    {
      "id": 2,
      "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30002",
      "work_date": "2026-11-10",
      "client_id": 1,
      "client_name": "PT Sinar Jaya Abadi",
      "purpose": "DELIVERY",
      "purpose_label": "Pengiriman Barang",
      "status": "CANCELLED",
      "status_label": "Dibatalkan",
      "checked_in_at": "2026-11-10T07:40:05+00:00",
      "checked_out_at": null,
      "duration_minutes": 0,
      "distance_meters": 3224,
      "is_within_radius": false,
      "outcome": null,
      "outcome_label": null,
      "notes": null,
      "follow_up_date": null,
      "is_suspect": true,
      "cancel_reason": "Salah pilih klien, kunjungan sebenarnya ke gudang sendiri."
    },
    {
      "id": 1,
      "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
      "work_date": "2026-11-10",
      "client_id": 1,
      "client_name": "PT Sinar Jaya Abadi",
      "purpose": "SALES_CALL",
      "purpose_label": "Kunjungan Penjualan",
      "status": "COMPLETED",
      "status_label": "Selesai",
      "checked_in_at": "2026-11-10T06:02:15+00:00",
      "checked_out_at": "2026-11-10T07:12:25+00:00",
      "duration_minutes": 70,
      "distance_meters": 10,
      "is_within_radius": true,
      "outcome": "FOLLOW_UP",
      "outcome_label": "Perlu Tindak Lanjut",
      "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
      "follow_up_date": "2026-11-13",
      "is_suspect": false,
      "cancel_reason": null
    }
  ]
}
```

---

## Kunjungan yang masih terbuka

**`GET /client-visits/open`**

Deskripsi: kunjungan `ONGOING` terbaru milik karyawan login, atau `null`. Panggil saat aplikasi dibuka
untuk melanjutkan layar check-out. Ringkasannya juga ada di `GET /me/config` → `open_client_visit`.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.client-visits.open` |

**Contoh Request**

```http
GET /api/v1/client-visits/open HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, ada kunjungan terbuka)

```json
{
  "success": true,
  "message": "Masih ada kunjungan yang belum di-check-out.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "ONGOING",
    "status_label": "Sedang Berlangsung",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": null,
    "duration_minutes": 0,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": null,
    "outcome_label": null,
    "notes": "Presentasi harga semen untuk proyek ruko.",
    "follow_up_date": null,
    "is_suspect": false,
    "cancel_reason": null
  }
}
```

Tidak ada kunjungan terbuka (`200`, `data` `null`):

```json
{
  "success": true,
  "message": "Tidak ada kunjungan yang sedang berlangsung.",
  "data": {}
}
```

---

## Check-in kunjungan

**`POST /client-visits/check-in`**

Deskripsi: memulai kunjungan dengan koordinat mentah, foto, dan klien terdaftar atau nama klien teks
bebas. Server mengukur jarak ke klien dan menandai kecurigaan; check-in di luar radius **tetap
diterima**.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive`, `throttle:attendance` |
| Route name | `api.v1.client-visits.check-in` |

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

**Parameter** (`StoreClientVisitRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `uuid` | body (part teks) | string (UUID) | ya | `required`, `uuid`. Dibuat client sekali per kunjungan; kunci idempotency |
| `client_id` | body (part teks) | integer | salah satu dengan `client_name` | `nullable`, `integer`, `min:1`. Dari `GET /clients` |
| `client_name` | body (part teks) | string | bila tanpa `client_id` | `required_without:client_id`, `nullable`, `string`, `max:150`. Diabaikan bila `client_id` dikirim |
| `purpose` | body (part teks) | string (enum) | ya | `required`, salah satu `ClientVisitPurpose` |
| `latitude` | body (part teks) | number | ya | `required`, `numeric`, `between:-90,90` |
| `longitude` | body (part teks) | number | ya | `required`, `numeric`, `between:-180,180` |
| `accuracy_meters` | body (part teks) | number | ya | `required`, `numeric`, `min:0`, `max:10000` |
| `captured_at` | body (part teks) | string (ISO 8601) | ya | `required`, `date`. **Wajib dengan offset** (`2026-11-10T13:02:15+07:00`) |
| `device_time` | body (part teks) | string (ISO 8601) | tidak | `nullable`, `date`. Jam perangkat saat kirim |
| `mock_location` | body (part teks) | boolean | tidak | `nullable`, `boolean`. Kirim `1`/`0`; `true`/`false` ditolak di multipart |
| `notes` | body (part teks) | string | tidak | `nullable`, `string`, `max:1000` |
| `photo` | body (part berkas) | berkas gambar | bila `policy.client_visit.photo_required` | `required`/`nullable` mengikuti pengaturan, `image`, `max:{policy.client_visit.photo_max_kilobytes}` KB (bawaan 500) |

**Contoh Request** (2026-11-10 13:02 WIB)

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

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

7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001
--absenova
Content-Disposition: form-data; name="latitude"

-6.161312
--absenova
Content-Disposition: form-data; name="longitude"

106.8395011
--absenova
Content-Disposition: form-data; name="accuracy_meters"

8
--absenova
Content-Disposition: form-data; name="captured_at"

2026-11-10T13:02:15+07:00
--absenova
Content-Disposition: form-data; name="device_time"

2026-11-10T13:02:15+07:00
--absenova
Content-Disposition: form-data; name="mock_location"

0
--absenova
Content-Disposition: form-data; name="client_id"

1
--absenova
Content-Disposition: form-data; name="purpose"

SALES_CALL
--absenova
Content-Disposition: form-data; name="notes"

Presentasi harga semen untuk proyek ruko.
--absenova
Content-Disposition: form-data; name="photo"; filename="kunjungan.jpg"
Content-Type: image/jpeg

(berkas JPEG 480×640, 260 KB)
--absenova--
```

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

```json
{
  "success": true,
  "message": "Kunjungan dimulai. Jangan lupa check-out setelah selesai.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "ONGOING",
    "status_label": "Sedang Berlangsung",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": null,
    "duration_minutes": null,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": null,
    "outcome_label": null,
    "notes": "Presentasi harga semen untuk proyek ruko.",
    "follow_up_date": null,
    "is_suspect": false,
    "cancel_reason": null
  }
}
```

Kirim ulang `uuid` yang sama (`200`, data asli, tanpa data ganda):

```json
"message": "Kunjungan ini sudah pernah terkirim sebelumnya.",
"data": {
  "id": 1,
  "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
  "work_date": "2026-11-10",
  "client_id": 1,
  "client_name": "PT Sinar Jaya Abadi",
  "purpose": "SALES_CALL",
  "purpose_label": "Kunjungan Penjualan",
  "status": "ONGOING",
  "status_label": "Sedang Berlangsung",
  "checked_in_at": "2026-11-10T06:02:15+00:00",
  "checked_out_at": null,
  "duration_minutes": 0,
  "distance_meters": 10,
  "is_within_radius": true,
  "outcome": null,
  "outcome_label": null,
  "notes": "Presentasi harga semen untuk proyek ruko.",
  "follow_up_date": null,
  "is_suspect": false,
  "cancel_reason": null
}
```

Di luar radius klien 300 m (`201`, ditandai `is_suspect`):

```json
"message": "Kunjungan dimulai, tetapi lokasi Anda jauh dari koordinat klien sehingga ditandai untuk ditinjau Admin HR.",
"data": {
  "id": 2,
  "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30002",
  "work_date": "2026-11-10",
  "client_id": 1,
  "client_name": "PT Sinar Jaya Abadi",
  "purpose": "DELIVERY",
  "purpose_label": "Pengiriman Barang",
  "status": "ONGOING",
  "status_label": "Sedang Berlangsung",
  "checked_in_at": "2026-11-10T07:40:05+00:00",
  "checked_out_at": null,
  "duration_minutes": null,
  "distance_meters": 3224,
  "is_within_radius": false,
  "outcome": null,
  "outcome_label": null,
  "notes": null,
  "follow_up_date": null,
  "is_suspect": true,
  "cancel_reason": null
}
```

Klien teks bebas dengan `mock_location: 1` (`201`, jarak tidak diukur, ditandai `is_suspect`):

```json
"message": "Kunjungan dimulai. Jangan lupa check-out setelah selesai.",
"data": {
  "id": 3,
  "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30003",
  "work_date": "2026-11-10",
  "client_id": null,
  "client_name": "Toko Bangunan Sentosa",
  "purpose": "SURVEY",
  "purpose_label": "Survei Lokasi",
  "status": "ONGOING",
  "status_label": "Sedang Berlangsung",
  "checked_in_at": "2026-11-10T08:20:00+00:00",
  "checked_out_at": null,
  "duration_minutes": null,
  "distance_meters": null,
  "is_within_radius": true,
  "outcome": null,
  "outcome_label": null,
  "notes": "Calon pelanggan baru, survei kebutuhan.",
  "follow_up_date": null,
  "is_suspect": true,
  "cancel_reason": null
}
```

**Penanda `is_suspect`** (kunjungan tetap diterima)

| Pemicu | Kondisi |
|---|---|
| Lokasi palsu | `mock_location = 1` |
| Akurasi nol | `accuracy_meters = 0` |
| Akurasi rendah | `accuracy_meters` melebihi `policy.gps_accuracy_threshold_meters` |
| Jauh dari klien | jarak diukur dan di luar radius klien |
| Jam perangkat menyimpang | selisih `device_time` dengan jam server lebih dari 10 menit |

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

| # | HTTP | `message` (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 429 | `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` (kuota bersama presensi) |
| 2 | 422 | ✓ `Data yang dikirim tidak lolos pemeriksaan.` (validasi FormRequest, termasuk foto wajib) |
| 3 | **200** | ✓ `uuid` sudah pernah diterima: bukan penolakan, data asli dikembalikan |
| 4 | 422 | ✓ `Klien yang dipilih tidak ditemukan atau sedang tidak aktif.` |
| 5 | 422 | `Nama klien wajib diisi bila kunjungan tidak dikaitkan ke klien terdaftar.` |
| 6 | 422 | ✓ `Waktu yang dikirim berada di masa depan menurut jam server.` (`captured_at` lebih dari 10 menit di depan jam server) |
| 7 | 422 | ✓ `Kunjungan hanya dapat dikirim paling lama 24 jam setelah waktu perekaman. Waktu perekaman: 2026-11-09 09:00 WIB.` (angka mengikuti `policy.offline_sync_tolerance_hours`) |
| 8 | 422 | ✓ `Masih ada kunjungan yang belum di-check-out. Selesaikan kunjungan tersebut lebih dahulu.` |
| 9 | 422 | `Foto wajib disertakan pada setiap check-in kunjungan klien.` (praktis tertangkap validasi nomor 2) |

Validasi (`uuid` tidak sah, tanpa `client_id`/`client_name`, `purpose: "JUALAN"`, `mock_location:
"true"`, tanpa foto):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "uuid": [
      "Kolom pengenal kunjungan harus berupa UUID yang sah."
    ],
    "client_name": [
      "Kolom nama klien wajib diisi bila tidak terdapat klien terdaftar."
    ],
    "purpose": [
      "Pilihan pada kolom tujuan kunjungan tidak sah."
    ],
    "longitude": [
      "Kolom bujur wajib diisi."
    ],
    "accuracy_meters": [
      "Kolom akurasi GPS wajib diisi."
    ],
    "mock_location": [
      "Kolom mock location harus bernilai benar atau salah."
    ],
    "photo": [
      "Kolom foto kunjungan wajib diisi."
    ]
  }
}
```

**Catatan**

- **Idempotency:** `uuid` per kunjungan. Simpan bersama antrean offline dan pakai ulang saat kirim
  ulang; jawaban `200` berisi data asli.
- **Satu kunjungan terbuka.** Check-in baru ditolak selama masih ada `ONGOING`; selesaikan dengan
  check-out atau batalkan. Kunjungan yang terbuka lebih dari `policy.client_visit.max_open_hours` tidak
  dapat di-check-out lagi (ditolak `...melewati batas wajar...`); batalkan atau minta Admin HR menutupnya.
- **Waktu:** `checked_in_at` = `captured_at`. Kirim dengan offset; sebelum 2026-10-22 server menyimpan
  jam lokal sebagai UTC (lihat CHANGELOG).
- Rate limit: `attendance`, 12 per menit per karyawan, **kuota bersama** dengan
  `POST /attendance/check-in` dan `POST /attendance/check-out`. Respons membawa `X-RateLimit-Limit` dan
  `X-RateLimit-Remaining`; 429 membawa `Retry-After` dan `X-RateLimit-Reset`.
- FeatureGate / modul: `module_client_visit` (server tidak memblokir). Status langganan: terkunci →
  402.

---

## Check-out kunjungan

**`POST /client-visits/{clientVisit}/check-out`**

Deskripsi: menyelesaikan kunjungan `ONGOING`, mencatat hasil, dan (bila diizinkan perusahaan) membuat
aktivitas timesheet `CLIENT_VISIT` otomatis.

| Auth & Middleware | |
|---|---|
| Token | wajib |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.client-visits.check-out` |

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

**Parameter** (`StoreClientVisitCheckOutRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `clientVisit` | path | integer | ya | ID kunjungan |
| `outcome` | body | string (enum) | ya | `required`, salah satu `ClientVisitOutcome` |
| `captured_at` | body | string (ISO 8601) | ya | `required`, `date`. Wajib dengan offset |
| `latitude` | body | number | tidak | `nullable`, `numeric`, `between:-90,90` |
| `longitude` | body | number | tidak | `nullable`, `numeric`, `between:-180,180` |
| `accuracy_meters` | body | number | tidak | `nullable`, `numeric`, `min:0`, `max:10000` |
| `notes` | body | string | tidak | `nullable`, `string`, `max:1000` |
| `follow_up_date` | body | string (`YYYY-MM-DD`) | tidak | `nullable`, `date`, `after_or_equal:today` |

**Contoh Request** (2026-11-10 14:12 WIB)

```http
POST /api/v1/client-visits/1/check-out HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
Content-Type: application/json

{
  "outcome": "FOLLOW_UP",
  "captured_at": "2026-11-10T14:12:25+07:00",
  "latitude": -6.1612877,
  "longitude": 106.839498,
  "accuracy_meters": 7.5,
  "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
  "follow_up_date": "2026-11-13"
}
```

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

```json
{
  "success": true,
  "message": "Kunjungan selesai dan durasinya tercatat.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "COMPLETED",
    "status_label": "Selesai",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": "2026-11-10T07:12:25+00:00",
    "duration_minutes": 70,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": "FOLLOW_UP",
    "outcome_label": "Perlu Tindak Lanjut",
    "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
    "follow_up_date": "2026-11-13",
    "is_suspect": false,
    "cancel_reason": null
  }
}
```

Bila aktivitas timesheet tidak dapat dibuat (mis. timesheet tanggal itu sudah dikirim), check-out tetap
berhasil dengan message `Kunjungan selesai dan durasinya tercatat, tetapi aktivitas timesheet tidak
dibuat otomatis karena {alasan}`.

**Penolakan** (422, `errors.client_visit`)

| Kondisi | `message` (direkam bila bertanda ✓) |
|---|---|
| Validasi | ✓ `Data yang dikirim tidak lolos pemeriksaan.` |
| Bukan `ONGOING` | ✓ `Kunjungan ini sudah berstatus Selesai.` |
| `captured_at` di masa depan / lewat toleransi | sama dengan check-in nomor 6–7 |
| `captured_at` tidak lebih akhir dari check-in | `Waktu check-out harus lebih besar daripada waktu check-in.` |
| Durasi kurang dari `policy.client_visit.minimum_duration_minutes` | ✓ `Durasi kunjungan minimal 5 menit, sedangkan kunjungan ini baru 2 menit.` |
| Durasi lebih dari `max_open_hours` | `Durasi kunjungan melewati batas wajar. Hubungi Admin HR untuk menutup kunjungan ini.` |
| Milik karyawan lain (403) | `Kunjungan ini bukan milik Anda.` |

Validasi (`outcome: "SELESAI"`, `captured_at: "nanti"`, `follow_up_date` sebelum hari ini):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "outcome": [
      "Pilihan pada kolom hasil kunjungan tidak sah."
    ],
    "captured_at": [
      "Kolom waktu perekaman bukan tanggal yang sah."
    ],
    "follow_up_date": [
      "Kolom tanggal tindak lanjut harus berisi tanggal today atau setelahnya."
    ]
  }
}
```

**Catatan**

- Idempotency: tidak ada kunci. Check-out kedua dijawab 422 `Kunjungan ini sudah berstatus Selesai.`;
  anggap sukses bila status lokal sudah `COMPLETED`.
- Rate limit: tidak ada (check-out tidak memakai limiter `attendance`).
- FeatureGate: `module_client_visit`. Status langganan: terkunci → 402.

---

## Batalkan kunjungan

**`POST /client-visits/{clientVisit}/cancel`**

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

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan |
|---|---|---|---|---|
| `clientVisit` | path | integer | ya | ID kunjungan |
| `reason` | body | string | tidak | alasan pembatalan. **Tanpa FormRequest**: tidak divalidasi; batasi di client maksimal 255 karakter |

**Status yang dapat dibatalkan:** hanya `ONGOING`.

**Contoh Request**

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

{
  "reason": "Salah pilih klien, kunjungan sebenarnya ke gudang sendiri."
}
```

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

```json
{
  "success": true,
  "message": "Kunjungan dibatalkan.",
  "data": {
    "id": 2,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30002",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "DELIVERY",
    "purpose_label": "Pengiriman Barang",
    "status": "CANCELLED",
    "status_label": "Dibatalkan",
    "checked_in_at": "2026-11-10T07:40:05+00:00",
    "checked_out_at": null,
    "duration_minutes": 0,
    "distance_meters": 3224,
    "is_within_radius": false,
    "outcome": null,
    "outcome_label": null,
    "notes": null,
    "follow_up_date": null,
    "is_suspect": true,
    "cancel_reason": "Salah pilih klien, kunjungan sebenarnya ke gudang sendiri."
  }
}
```

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

| Kondisi | `message` |
|---|---|
| Bukan `ONGOING` | ✓ `Hanya kunjungan yang sedang berlangsung yang dapat dibatalkan.` |
| Milik karyawan lain (403) | `Kunjungan ini bukan milik Anda.` |

---

## Detail kunjungan

**`GET /client-visits/{clientVisit}`**

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

**Contoh Request**

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

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

```json
{
  "success": true,
  "message": "Detail kunjungan klien berhasil diambil.",
  "data": {
    "id": 1,
    "uuid": "7c2d4e6f-8a9b-4c1d-9e2f-10c1f0c30001",
    "work_date": "2026-11-10",
    "client_id": 1,
    "client_name": "PT Sinar Jaya Abadi",
    "purpose": "SALES_CALL",
    "purpose_label": "Kunjungan Penjualan",
    "status": "COMPLETED",
    "status_label": "Selesai",
    "checked_in_at": "2026-11-10T06:02:15+00:00",
    "checked_out_at": "2026-11-10T07:12:25+00:00",
    "duration_minutes": 70,
    "distance_meters": 10,
    "is_within_radius": true,
    "outcome": "FOLLOW_UP",
    "outcome_label": "Perlu Tindak Lanjut",
    "notes": "Pelanggan minta penawaran tertulis untuk 1.200 sak.",
    "follow_up_date": "2026-11-13",
    "is_suspect": false,
    "cancel_reason": null
  }
}
```

**Contoh Response Error**

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