# Versi Aplikasi

Pemeriksaan versi aplikasi di layar pembuka, **sebelum login**. Server memberi versi terbaru dan versi
minimal yang masih boleh dipakai; client memutuskan menampilkan layar "wajib perbarui" atau tawaran
pembaruan. Nilai dikelola pengelola Absenova di panel platform (**Aplikasi Mobile → Versi Aplikasi**)
dan berlaku tanpa rilis aplikasi. Konvensi umum ada di [README.md](README.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /app/version` |
| Sumber kode | `AppVersionController`, `ShowAppVersionRequest`, `AppVersionResource`, `AppVersionService`, model `AppVersion`, panel `App\Filament\Platform\Resources\AppVersions` |
| Contoh direkam | 2026-10-22, HTTP kernel Laravel, basis data SQLite sekali pakai sesudah migrasi `2026_10_22_100000_create_app_versions_table`, `APP_LOCALE=id`. Nilai Android diisi lewat formulir panel platform (Livewire) |
| Data uji | Android: versi terbaru `1.2.0` (`versionCode` 12), minimal `versionCode` 10. `store_url` di contoh adalah data uji; tautan sebenarnya diisi pengelola di panel |

---

## Periksa versi

**`GET /app/version`**

Deskripsi: informasi versi untuk satu platform. Bukan data perusahaan: nilainya sama untuk seluruh
pelanggan Absenova.

| Auth & Middleware | |
|---|---|
| Token | **tidak** |
| Middleware | `throttle:api` |
| Route name | `api.v1.app.version` |

**Header:** `Accept: application/json`

**Parameter** (`ShowAppVersionRequest`)

| Nama | Lokasi | Tipe | Wajib | Aturan validasi (FormRequest) |
|---|---|---|---|---|
| `platform` | query | string (enum) | ya | `required`, salah satu `DevicePlatform` (`ANDROID`, `IOS`) |

**Contoh Request**

```http
GET /api/v1/app/version?platform=ANDROID HTTP/1.1
Accept: application/json
```

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

```json
{
  "success": true,
  "message": "Informasi versi aplikasi berhasil diambil.",
  "data": {
    "latest_version_name": "1.2.0",
    "latest_version_code": 12,
    "minimum_version_code": 10,
    "store_url": "https://play.google.com/store/apps/details?id=id.absenova.app",
    "message": "Versi baru memperbaiki presensi offline. Perbarui aplikasi untuk melanjutkan."
  }
}
```

Platform yang belum diatur di panel (`200`, angka `0` sehingga tidak pernah memaksa pembaruan):

```json
{
  "success": true,
  "message": "Informasi versi aplikasi berhasil diambil.",
  "data": {
    "latest_version_name": null,
    "latest_version_code": 0,
    "minimum_version_code": 0,
    "store_url": null,
    "message": null
  }
}
```

**Field `data`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `latest_version_name` | string | ya | `versionName` terbaru di toko aplikasi, untuk ditampilkan. `null` bila platform belum diatur |
| `latest_version_code` | integer | tidak | `versionCode` terbaru. `0` bila belum diatur |
| `minimum_version_code` | integer | tidak | `versionCode` terendah yang masih boleh dipakai; selalu `<= latest_version_code`. `0` bila belum diatur |
| `store_url` | string | ya | tautan halaman aplikasi di toko; `null` bila belum diisi |
| `message` | string | ya | pesan untuk layar pembaruan, teks polos; `null` bila kosong |

**Logika client** (bandingkan `versionCode` bilangan bulat, **bukan** string versi):

| Kondisi | Tindakan client |
|---|---|
| `BuildConfig.VERSION_CODE < minimum_version_code` | layar wajib perbarui; tombol membuka `store_url`; aplikasi tidak dilanjutkan |
| `minimum_version_code <= VERSION_CODE < latest_version_code` | tawarkan pembaruan, boleh dilewati |
| `VERSION_CODE >= latest_version_code` | lanjut tanpa tawaran |

Tampilkan `message` bila tidak `null`. Bila `store_url` `null`, arahkan ke toko aplikasi berdasarkan
nama paket aplikasi.

**Contoh Response Error**

| Kondisi | HTTP | `message` |
|---|---|---|
| `platform` kosong atau tidak dikenal | 422 | `Data yang dikirim tidak lolos pemeriksaan.` |
| Batas laju terlampaui | 429 | `Terlalu banyak percobaan. Tunggu beberapa saat lalu coba lagi.` |

```json
{
  "success": false,
  "message": "Data yang dikirim tidak lolos pemeriksaan.",
  "errors": {
    "platform": [
      "Pilihan pada kolom jenis perangkat tidak sah."
    ]
  }
}
```

**Catatan**

- Idempotency: tidak relevan (GET).
- Rate limit: `api`, 60 per menit per IP (tanpa token). Respons membawa `X-RateLimit-Limit: 60` dan
  `X-RateLimit-Remaining`; request ke-61 dalam satu menit dijawab 429 dengan `Retry-After` dan
  `X-RateLimit-Reset`.
- FeatureGate / modul: tidak ada.
- Status langganan: tidak diperiksa (tanpa token dan bukan data perusahaan).
- Perubahan di panel berlaku pada request berikutnya; tidak ada cache server.
