# Integrasi Hak Akses (Permissions) di UI beserta Konfigurasi CRUD

## ✅ Hasil Pengecekan Kesiapan Project
1. **Navigasi (*Menu/Routing*)**: Sudah tersedia di `stores/navItems1.ts` (`defaultNavItems`). Array ini akan menjadi sumber daftar halaman di dialog "Edit Hak Akses" — dengan catatan penting di bagian struktur data (lihat poin 2 di bawah).
2. **Library Komponen**: Vuetify 3 sudah tersedia, tinggal memasang `<v-checkbox>` / `<v-switch>` di tabel dialog Edit Hak Akses.
3. **Mock Backend API**: `server/api/hak-akses/index.ts` sudah bisa menahan format data CRUD yang akan dikirim dari UI.

Karena API backend sesungguhnya belum siap, kita pakai **Nuxt Local API (Mock Backend)** sebagai *Backend-for-Frontend* sementara, dengan arsitektur *toggling* API sejak awal agar migrasi ke backend asli mulus.

> ⚠️ **Catatan penting**: Toggle mock/real API ini menyelesaikan masalah *sumber data*, bukan masalah *keamanan*. Semua pengecekan `v-permission` dan middleware di bawah ini berjalan di client — lihat bagian **Keamanan** sebelum dianggap selesai.

---

## Bagan Alur Sistem Hak Akses (Permission Flow)

```mermaid
flowchart TD
    User([Pengguna]) --> Login(Berhasil Login via Keycloak)
    Login --> Auth[useAuth.ts: Dapat Data Roles & Groups]
    Auth --> PermStore[permissionStore.ts memuat Permissions]

    PermStore --> CheckFlag{USE_MOCK_API ?}

    CheckFlag -- TRUE --> MockAPI[Nuxt Local API: /api/hak-akses]
    CheckFlag -- FALSE --> RealAPI[Real Backend: /api/v1/permission]

    MockAPI --> FetchFail{Fetch gagal?}
    RealAPI --> FetchFail
    FetchFail -- Ya --> DenyDefault[Deny-by-default: anggap tanpa izin]
    FetchFail -- Tidak --> PermState(Permission State Disimpan)

    PermState --> Router[Vue Router Middleware - client]
    PermState --> ServerCheck[Server Middleware/Plugin - SSR guard]
    PermState --> Sidebar[Sidebar Navigation]

    Router -- canAccess: False --> Deny[Redirect ke Error/403]
    Router -- canAccess: True --> Page[Buka Halaman]
    ServerCheck -- canAccess: False --> Deny

    Sidebar -- canView: False --> HideMenu[Sembunyikan Menu]

    Page --> Directive[v-permission directive pada Komponen]
    Directive -- canDelete: False --> HideBtn[Tombol Hapus Hilang/Disabled]
    Directive -- canAdd: True --> ShowBtn[Tombol Tambah Tampil]

    Page -.-> BackendGuard[[Backend API tetap validasi ulang izin]]
```

---

## Proposed Changes

### 1. Seamless Backend Migration Strategy (Persiapan API Asli)
- `stores/permissionStore.ts` dan composable pemanggil membaca konfigurasi *runtime* (`useRuntimeConfig()`).
- Tambahkan flag `USE_MOCK_PERMISSION_API: true`.
- Saat backend siap, cukup ubah `NUXT_PUBLIC_USE_MOCK_PERMISSION_API=false` di `.env`.
- **Tambahan — contract test**: buat satu skema/interface TypeScript (idealnya divalidasi dengan `zod`) yang dipakai bersama oleh mock API dan dipakai untuk memvalidasi response real API nanti. Ini memastikan klaim "tinggal ganti flag" benar-benar teruji, bukan asumsi.

### 2. Upgrade Local API Mock (`server/api/hak-akses/index.ts`)
- Perbarui `data/mock/hakAkses.json` agar field `hakAksesMenu` berisi boolean: `canAccess`, `canView`, `canAdd`, `canEdit`, `canDelete`.
- **Perubahan struktur — pakai key stabil, bukan label**: setiap entri `hakAksesMenu` menyimpan `menuKey` (mengacu ke `key`/`routeName` unik di `navItems1.ts`), bukan `name` (label tampilan). Label bisa berubah/di-rename tanpa memutus mapping izin.

```json
{
  "menuKey": "master-klinik-ruang",
  "name": "Master Klinik Ruang",
  "canAccess": true,
  "canView": true,
  "canAdd": false,
  "canEdit": false,
  "canDelete": false
}
```

- Validasi payload masuk dengan skema (zod) di endpoint mock, supaya struktur tidak diam-diam berubah antara UI dan backend.

### 3. Memperbarui `Setting/HakAkses.vue` (UI Konfigurasi CRUD)
- Dialog Edit melooping `navItems1.ts`, menampilkan matriks checkbox untuk `canAccess`, `canView`, `canAdd`, `canEdit`, `canDelete`, dikunci ke `menuKey` masing-masing.
- Payload POST mengarah ke API Mock/Real sesuai flag.
- **Aturan precedence eksplisit** (harus didefinisikan sebelum coding, karena ada `role`, `group`, dan `isGroupBased` sekaligus):
  1. Jika user punya override individual (role-based) → pakai itu.
  2. Jika tidak ada override individual dan `isGroupBased: true` → pakai izin dari group.
  3. Jika keduanya tidak ada → deny-by-default.
  - Tuliskan aturan ini sebagai komentar di `permissionStore.ts`, bukan hanya di dokumen, supaya tidak jadi sumber bug tersembunyi saat logic berkembang.

### 4. Vue Custom Directive `v-permission`
- File baru `plugins/permission.ts` untuk registrasi directive.
- Dukungan penggunaan:
  - Single: `<v-btn v-permission="'canEdit'">Edit</v-btn>`
  - Multiple (AND): `<v-btn v-permission="['canEdit', 'canDelete']">...</v-btn>`
- **Mode hide vs disable**: tambahkan modifier, misal `v-permission:disable="'canDelete'"`, agar tombol bisa di-disable dengan tooltip ("Anda tidak punya izin") alih-alih hilang total tanpa penjelasan — pilih sesuai konteks UX per halaman.

### 5. `stores/permissionStore.ts` (State Management)
- Mengambil data izin dari Local/Real API saat login.
- Menyimpan state global.
- **Deny-by-default**: jika fetch permission gagal (network error, token expired), state dianggap "tanpa izin sama sekali", bukan default terbuka.
- **Refresh strategy**: tentukan apakah perubahan hak akses oleh admin berlaku langsung (polling/refetch berkala) atau baru berlaku setelah re-login. Pilih salah satu secara eksplisit dan dokumentasikan, jangan dibiarkan implisit.

### 6. Middleware & Dynamic Sidebar
- **Client middleware (`middleware/permissions.ts`)**: mencegat rute jika `canAccess` false.
- **Server-side guard**: karena project ini SSR (Nuxt), tambahkan pengecekan di server middleware/plugin juga — bukan hanya client — untuk mencegah *flash of unauthorized content* (halaman sempat ter-render sebelum redirect).
- **Sidebar (`stores/navItems1.ts`)**: filter menu berdasarkan `canView`, dikunci ke `menuKey`.

### 7. Keamanan Backend (wajib, non-negotiable)
- `v-permission` dan middleware di atas adalah **UX**, bukan kontrol akses sesungguhnya — keduanya berjalan di client dan bisa dilewati siapa saja yang memanggil API langsung.
- Backend API asli **wajib** memvalidasi ulang setiap permission di server berdasarkan identitas user dari token, tidak pernah mempercayai payload/izin yang dikirim dari frontend.

---

## Verification Plan

### 1. Verifikasi API Lokal via cURL
Pastikan API Lokal mampu membaca dan menyimpan JSON berformat CRUD dengan `menuKey`:

```bash
curl -X POST "http://localhost:3000/api/hak-akses" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "group": "LOKET",
    "namaTipeUser": "Admin Loket",
    "isGroupBased": true,
    "hakAksesMenu": [
      {
        "menuKey": "master-klinik-ruang",
        "name": "Master Klinik Ruang",
        "canAccess": true,
        "canView": true,
        "canAdd": false,
        "canEdit": false,
        "canDelete": false
      }
    ]
  }'
```

### 2. Manual UI Verification
1. Buka **Setting > Hak Akses**, atur hak untuk Role tertentu (centang `canView`, matikan `canDelete`).
2. Login sebagai akun dengan Role tersebut.
3. Buka halaman target.
4. **Validasi**: Halaman terbuka, tombol "Delete" tersembunyi/disabled sesuai mode `v-permission`.
5. **Validasi fetch gagal**: Simulasikan permission API error (mis. matikan endpoint sementara) → pastikan sistem deny-by-default, bukan default terbuka.
6. **Validasi kesiapan API asli**: Cek logika precedence dan toggle flag di `permissionStore.ts`.

### 3. Automated Testing (baru)
- **Unit test** untuk `permissionStore.ts`: precedence role vs group, deny-by-default saat fetch gagal, evaluasi `canAccess`/`canView`/dst.
- **Contract test**: bandingkan skema response Mock API vs Real API (setelah Real API tersedia) menggunakan skema TypeScript/zod yang sama, untuk memastikan switch flag benar-benar tanpa perubahan kode lain.
- **Directive test**: pastikan `v-permission` menyembunyikan/disable elemen dengan benar untuk kombinasi single dan multiple permission.

---

## Strategi Selama Backend Asli Belum Tersedia

Karena tim belum bisa mengimplementasikan validasi izin di server sungguhan, mock API diperlakukan sebagai **kontrak (contract-first)**, bukan sekadar penyimpanan data sementara. Tujuannya: frontend sudah teruji terhadap semua skenario yang nanti jadi tanggung jawab backend asli, dan tidak perlu dirombak saat migrasi.

### 1. Mock API mengikuti skema, bukan menerima apa saja
- Definisikan interface TypeScript / skema `zod` untuk request dan response `hak-akses` **sekarang**, bukan menunggu backend asli.
- Mock API menolak (400) payload yang tidak sesuai skema.
- Skema ini menjadi kontrak yang wajib dipatuhi backend asli nanti — perbedaan struktur akan ketahuan lewat contract test, bukan saat production.

### 2. Simulasikan tanggung jawab yang nanti dipegang backend
- Tambahkan endpoint mock `/api/hak-akses/check` yang bisa mensimulasikan penolakan server (403) karena user tidak punya izin — supaya UI dan middleware sudah teruji menangani penolakan dari server, bukan hanya dari state client.
- Simulasikan juga kegagalan fetch (delay/error 500) untuk memverifikasi deny-by-default benar-benar berjalan.

### 3. Tandai eksplisit bagian yang "sementara tidak aman"
Beri komentar `TODO(security)` di titik-titik yang wajib diperkuat saat backend asli terpasang, contoh:
```ts
// TODO(security): saat backend asli terpasang, endpoint ini WAJIB
// memvalidasi ulang permission dari token JWT/session di server,
// jangan percaya payload role/group yang dikirim dari client.
```
Ini mencegah asumsi keliru saat handoff bahwa "karena UI sudah mengatur tampilan sesuai izin, backend tidak perlu memvalidasi ulang".

### 4. Definition of Done — Migrasi ke Backend Asli
Checklist ini harus tercentang semua **sebelum** flag `USE_MOCK_PERMISSION_API` dimatikan (`false`) di production:
- [ ] Endpoint real API memvalidasi permission berdasarkan identitas dari token (JWT/session), bukan dari body request yang dikirim client.
- [ ] Response real API lolos contract test terhadap skema yang sama dengan mock API (field, tipe data, struktur `hakAksesMenu` identik).
- [ ] Skenario penolakan server (403) dan fetch gagal (500/timeout) sudah diuji terhadap real API, tidak hanya terhadap mock.
- [ ] Ada audit log untuk setiap perubahan hak akses (siapa mengubah, kapan, dari-ke apa) — direkomendasikan mengingat ini fitur kontrol akses.
- [ ] Rate limiting pada endpoint pengubahan hak akses, untuk mencegah penyalahgunaan.
- [ ] Semua komentar `TODO(security)` di kode sudah diselesaikan atau dipindahkan menjadi tiket tersendiri yang dilacak.