# Perangkat Pinjaman

Presensi lewat ponsel rekan kerja bila ponsel karyawan bermasalah. Karyawan memasukkan Nomor Karyawan
dan kata sandi **di perangkat pinjaman**, menerima kode 6 digit lewat surel, lalu mendapat **token sesi
pinjaman** dengan jatah presensi terbatas. Perangkat pemilik tidak berubah dan pemiliknya tetap dapat
masuk seperti biasa. Konvensi umum ada di [README.md](README.md); login biasa ada di [auth.md](auth.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `POST /auth/lend/request`, `POST /auth/lend/verify`, `GET /me/lending`, `POST /auth/lend/end` |
| Sumber kode | `DeviceLendingController`, `RequestDeviceLendingRequest`, `VerifyDeviceLendingRequest`, `DeviceLendingResource`, `DeviceLendingService`, `EmployeeAuthService` |
| Contoh direkam | 2026-11-12 sampai 2026-12-01, HTTP kernel Laravel, basis data SQLite sekali pakai berisi dua perusahaan, `APP_LOCALE=id`. Kode surel diambil dari notifikasi palsu |
| Data uji | Citra Satu meminjam ponsel Budi Satu (`0a9c71de-budi-redmi13`, Xiaomi Redmi 13). Pengaturan bawaan (`policy.device_lending`): aktif, kode berlaku 10 menit, sesi 12 jam, 2 presensi per sesi, 3 sesi per bulan, 5 kali salah kode |

**Alur:**

1. `POST /auth/lend/request` (tanpa token) → kode dikirim ke surel karyawan.
2. `POST /auth/lend/verify` (tanpa token) → `token` sesi pinjaman + data karyawan + status izin.
3. Presensi memakai token sesi pinjaman (`POST /attendance/check-in`, `/check-out`); setiap presensi
   yang diterima memakai satu jatah.
4. Sesi berakhir saat jatah habis, masa sesi lewat, atau `POST /auth/lend/end`. Token sesi **dihapus
   server** saat berakhir; panggilan berikutnya dijawab 401.

---

## Enum

### `DeviceLendingStatus` (`status`)

| Nilai | `status_label` | Arti |
|---|---|---|
| `PENDING` | Menunggu Kode | kode sudah dikirim, belum diverifikasi |
| `ACTIVE` | Sedang Berlaku | terverifikasi; token sesi dapat dipakai presensi |
| `COMPLETED` | Selesai Dipakai | jatah presensi habis |
| `EXPIRED` | Kedaluwarsa | kode tidak dimasukkan tepat waktu, atau masa sesi lewat |
| `REVOKED` | Dicabut | dihentikan karyawan/Admin HR, terlalu banyak salah kode, atau digantikan permintaan baru |

`DevicePlatform` (`platform`, `device_platform`) sama dengan [auth.md](auth.md).

---

## Objek `lending`

Sumber: `DeviceLendingResource`.

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | ID izin pinjam |
| `status` | string (enum) | tidak | `DeviceLendingStatus` |
| `status_label` | string | tidak | label tampilan |
| `device_name` | string | ya | nama perangkat pinjaman |
| `device_identifier` | string | tidak | pengenal perangkat pinjaman |
| `platform` | string (enum) | tidak | `DevicePlatform` |
| `owner_name` | string | ya | nama pemilik perangkat bila perangkat terdaftar atas karyawan lain; `null` bila tidak dikenal |
| `usage_count` | integer | tidak | jumlah presensi yang sudah memakai sesi ini |
| `max_usages` | integer | tidak | jatah presensi per sesi |
| `remaining_usages` | integer | tidak | `max_usages - usage_count` |
| `requested_at` | string (ISO 8601 UTC) | tidak | waktu kode diminta |
| `verified_at` | string (ISO 8601 UTC) | ya | waktu kode diverifikasi |
| `expires_at` | string (ISO 8601 UTC) | ya | akhir sesi = `verified_at` + `session_hours` |
| `ended_at` | string (ISO 8601 UTC) | ya | waktu sesi berakhir |
| `end_reason` | string | ya | alasan berakhir |
| `is_usable` | boolean | tidak | `true` bila `ACTIVE`, belum lewat `expires_at`, dan jatah masih ada |

---

## Minta kode izin

**`POST /auth/lend/request`**

Deskripsi: memeriksa Nomor Karyawan/surel dan kata sandi, lalu mengirim kode 6 digit ke surel
karyawan. Permintaan baru menutup izin lain milik karyawan yang masih terbuka.

| Auth & Middleware | |
|---|---|
| Token | **tidak** |
| Middleware | `throttle:device-lending` |
| Route name | `api.v1.auth.lend.request` |

**Header:** `Accept: application/json`, `Content-Type: application/json`

**Parameter** (`RequestDeviceLendingRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `identifier` | body | string | ya | `required`, `string`, `max:150`. Nomor Karyawan atau surel |
| `password` | body | string | ya | `required`, `string` |
| `device_identifier` | body | string | ya | `required`, `string`, `max:150`. Pengenal perangkat pinjaman, sama dengan yang dipakai login |
| `device_platform` | body | string (enum) | ya | `required`, salah satu `DevicePlatform` |
| `device_name` | body | string | tidak | `nullable`, `string`, `max:100` |
| `app_version` | body | string | tidak | `nullable`, `string`, `max:50` |

**Contoh Request** (2026-11-12 07:30 WIB)

```http
POST /api/v1/auth/lend/request HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "citra@nusantara-logistik.test",
  "password": "Rahasia123!",
  "device_identifier": "0a9c71de-budi-redmi13",
  "device_platform": "ANDROID",
  "device_name": "Xiaomi Redmi 13",
  "app_version": "1.0.1"
}
```

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

```json
{
  "success": true,
  "message": "Kode izin sudah dikirim ke alamat surel Anda.",
  "data": {
    "email": "ci***@nusantara-logistik.test",
    "expires_minutes": 10,
    "session_hours": 12,
    "max_usages": 2
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `email` | string | tidak | surel tujuan yang disamarkan (dua huruf pertama terlihat) |
| `expires_minutes` | integer | tidak | masa berlaku kode |
| `session_hours` | integer | tidak | lama sesi setelah verifikasi |
| `max_usages` | integer | tidak | jatah presensi per sesi |

**Penolakan dan urutan pemeriksaan**

| # | HTTP | `message` (direkam bila bertanda ✓) |
|---|---|---|
| 1 | 429 | ✓ `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |
| 2 | 422 | ✓ `Data yang dikirim tidak lolos pemeriksaan.` |
| 3 | 401 | ✓ `Nomor Karyawan atau kata sandi tidak sesuai.` (juga akun nonaktif atau `identifier` ganda) |
| 4 | 403 | ✓ `Perusahaan Anda tidak mengizinkan presensi lewat perangkat pinjaman. Hubungi Admin HR untuk mendaftarkan perangkat baru.` (`errors.device_lending`) |
| 5 | 422 | `Akun Anda belum memiliki alamat surel sehingga kode izin tidak dapat dikirim. Hubungi Admin HR.` |
| 6 | 422 | ✓ `Perangkat ini sudah terdaftar atas nama Anda. Masuklah seperti biasa tanpa kode izin.` |
| 7 | 422 | ✓ `Pinjam perangkat hanya dapat dipakai 3 kali dalam satu bulan dan jatah bulan ini sudah habis. Hubungi Admin HR untuk mendaftarkan perangkat baru.` |

Kuota bulanan menghitung sesi yang **berhasil diverifikasi** pada bulan berjalan; kode yang tidak pernah
dimasukkan tidak memakai kuota.

Validasi (`password`, `device_identifier` kosong, `device_platform: "WINDOWS"`):

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "password": [
      "Kolom kata sandi wajib diisi."
    ],
    "device_identifier": [
      "Kolom pengenal perangkat wajib diisi."
    ],
    "device_platform": [
      "Pilihan pada kolom jenis perangkat tidak sah."
    ]
  }
}
```

---

## Verifikasi kode

**`POST /auth/lend/verify`**

Deskripsi: mencocokkan kode, mengaktifkan izin, dan menerbitkan **token sesi pinjaman**.

| Auth & Middleware | |
|---|---|
| Token | **tidak** |
| Middleware | `throttle:device-lending` |
| Route name | `api.v1.auth.lend.verify` |

**Parameter** (`VerifyDeviceLendingRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `identifier` | body | string | ya | `required`, `string`, `max:150` |
| `password` | body | string | ya | `required`, `string`. Diperiksa ulang |
| `device_identifier` | body | string | ya | `required`, `string`, `max:150`. Wajib sama dengan saat meminta kode |
| `code` | body | string | ya | `required`, `string`, `size:6`. Kirim sebagai teks agar nol di depan tidak hilang |

**Contoh Request** (2026-11-12 07:32 WIB)

```http
POST /api/v1/auth/lend/verify HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "identifier": "citra@nusantara-logistik.test",
  "password": "Rahasia123!",
  "device_identifier": "0a9c71de-budi-redmi13",
  "code": "509434"
}
```

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

```json
{
  "success": true,
  "message": "Izin presensi pada perangkat ini berlaku. Jangan lupa keluar setelah selesai.",
  "data": {
    "token": "4|contohTokenDisamarkanTidakBerlakuDiServerManaPun",
    "employee": {
      "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
    },
    "lending": {
      "id": 1,
      "status": "ACTIVE",
      "status_label": "Sedang Berlaku",
      "device_name": "Xiaomi Redmi 13",
      "device_identifier": "0a9c71de-budi-redmi13",
      "platform": "ANDROID",
      "owner_name": "Budi Satu",
      "usage_count": 0,
      "max_usages": 2,
      "remaining_usages": 2,
      "requested_at": "2026-11-12T00:30:00+00:00",
      "verified_at": "2026-11-12T00:32:00+00:00",
      "expires_at": "2026-11-12T12:32:00+00:00",
      "ended_at": null,
      "end_reason": null,
      "is_usable": true
    }
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `token` | string | tidak | token sesi pinjaman; kirim sebagai `Authorization: Bearer` |
| `employee` | objek | tidak | sama dengan `data.employee` pada login ([auth.md](auth.md)) |
| `lending` | objek | tidak | [objek `lending`](#objek-lending) |

**Penolakan** (422, `errors.device_lending`, kecuali disebut lain)

| Kondisi | `message` (direkam bila bertanda ✓) |
|---|---|
| Batas laju | 429 `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |
| Validasi | ✓ `Data yang dikirim tidak lolos pemeriksaan.` (`code` bukan 6 karakter) |
| Kata sandi salah | 401 `Nomor Karyawan atau kata sandi tidak sesuai.` |
| Kode salah, tidak ada permintaan, atau perangkat berbeda | ✓ `Kode izin tidak sesuai atau sudah tidak berlaku.` |
| Kode lewat `expires_minutes` | ✓ `Kode izin sudah kedaluwarsa. Mintalah kode baru.` |
| Salah kode mencapai batas (bawaan 5) | `Kode salah terlalu banyak kali. Mintalah kode baru.` |

```json
{
  "success": false,
  "message": "Kode izin tidak sesuai atau sudah tidak berlaku.",
  "errors": {
    "device_lending": [
      "Kode izin tidak sesuai atau sudah tidak berlaku."
    ]
  }
}
```

---

## Status sesi pinjaman

**`GET /me/lending`**

Deskripsi: izin pinjam yang dipakai token saat ini. Dengan token login biasa, `data` bernilai `null`.

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

**Contoh Request**

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

**Contoh Response Sukses** (`200`, token sesi pinjaman, sesudah satu presensi masuk)

```json
{
  "success": true,
  "message": "Anda sedang memakai izin presensi pada perangkat pinjaman.",
  "data": {
    "id": 1,
    "status": "ACTIVE",
    "status_label": "Sedang Berlaku",
    "device_name": "Xiaomi Redmi 13",
    "device_identifier": "0a9c71de-budi-redmi13",
    "platform": "ANDROID",
    "owner_name": "Budi Satu",
    "usage_count": 1,
    "max_usages": 2,
    "remaining_usages": 1,
    "requested_at": "2026-11-12T00:30:00+00:00",
    "verified_at": "2026-11-12T00:32:00+00:00",
    "expires_at": "2026-11-12T12:32:00+00:00",
    "ended_at": null,
    "end_reason": null,
    "is_usable": true
  }
}
```

Token login biasa:

```json
{
  "success": true,
  "message": "Anda tidak sedang memakai perangkat pinjaman.",
  "data": {}
}
```

---

## Akhiri sesi pinjaman

**`POST /auth/lend/end`**

Deskripsi: menghentikan izin pinjam milik token saat ini dan menghapus token sesi. Panggil saat
karyawan selesai, sebelum mengembalikan ponsel.

| Auth & Middleware | |
|---|---|
| Token | wajib (token sesi pinjaman) |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.auth.lend.end` |

**Parameter:** tidak ada.

**Contoh Request**

```http
POST /api/v1/auth/lend/end HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

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

```json
{
  "success": true,
  "message": "Izin presensi pada perangkat pinjaman dihentikan.",
  "data": {}
}
```

Token yang sama sesudahnya:

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

**Penolakan**

| Kondisi | HTTP | `message` |
|---|---|---|
| Token login biasa | 422 | ✓ `Anda tidak sedang memakai perangkat pinjaman.` |
| Token sesi sudah berakhir | 401 | ✓ `Token tidak sah atau sudah kedaluwarsa. Silakan masuk kembali.` |

---

## Presensi dengan token sesi pinjaman

Check-in dan check-out memakai endpoint biasa di [attendance.md](attendance.md). Setiap presensi yang
diterima menambah `usage_count`. Saat jatah habis, status menjadi `COMPLETED` dan token dihapus.

Sesudah presensi pulang yang memakai jatah terakhir (2026-11-12 17:04 WIB), `GET /me/lending` dengan
token yang sama:

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

Masa sesi 12 jam lewat sebelum jatah habis: presensi berikutnya ditolak
`DEVICE_LENDING_ENDED` (2026-12-01 19:33 WIB), lalu token dihapus:

```json
{
  "success": false,
  "message": "Izin presensi pada perangkat pinjaman sudah habis atau dihentikan. Mintalah kode izin baru.",
  "errors": {
    "attendance": [
      "Izin presensi pada perangkat pinjaman sudah habis atau dihentikan. Mintalah kode izin baru."
    ]
  }
}
```

---

## Catatan

- **Token sesi pinjaman** diterima seluruh endpoint bertoken, bukan hanya presensi. Tampilkan hanya
  layar presensi selama sesi pinjaman, dan jangan simpan token ini sebagai token login perangkat.
- **Idempotency:** tidak ada kunci. Permintaan kode berulang menutup permintaan sebelumnya; hanya kode
  terakhir yang berlaku.
- **Rate limit:** `device-lending`, 3 per menit per `identifier` + IP, untuk `request` dan `verify`.
  Request yang gagal ikut terhitung. Respons membawa `X-RateLimit-Limit` dan `X-RateLimit-Remaining`;
  429 membawa `Retry-After` dan `X-RateLimit-Reset`.
- **FeatureGate / modul:** tidak ada saklar paket. Pengaturan perusahaan
  `policy.device_lending.enabled` menentukan; bila `false`, permintaan kode dijawab 403.
- **Status langganan:** `request` dan `verify` tidak memakai middleware langganan; `GET /me/lending`,
  `POST /auth/lend/end`, dan presensi dengan token sesi → 402 bila terkunci.
