biiproject-kit-v1/USER_GUIDE.md

# User Guide — Panduan Admin

Panduan ini untuk **Administrator** atau **Super Admin** yang mengoperasikan aplikasi.

---

## Login

1. Buka `https://domain.com/login`
2. Masukkan email & password
3. (Opsional) jika **2FA** diaktifkan, kode 6 digit dikirim ke email — input di halaman `/2fa`
4. (Opsional) centang **Trust this device** untuk skip 2FA selama 30 hari (cookie aman)
5. (Opsional) gunakan **Passkey (biometrik)** jika sudah didaftarkan di profil
6. (Opsional) login via **Google / Facebook / GitHub** jika Social OAuth diaktifkan

> Akun default setelah seeder: lihat tabel di README.md. Jika perlu reset, jalankan:
> ```bash
> ./vendor/bin/sail artisan db:seed --class=AdminUserSeeder
> ./vendor/bin/sail artisan cache:clear
> ```

### Rate Limit

Untuk mencegah brute force:

| Endpoint | Limit |
|----------|-------|
| `/login` (web) | 5/menit per IP |
| `/2fa` verify | 5/menit per IP |
| `/forgot-password` | dibatasi via Spatie throttle |
| `/api/v1/login` (mobile) | 10/menit per IP |
| `/api/v1/otp/send` | 5/menit per IP |
| `/api/v1/otp/verify` | 10/menit per IP |

Jika kena rate limit, response `429 Too Many Requests` — tunggu 1 menit.

---

## Dashboard

Halaman pertama setelah login. Menampilkan statistik sistem secara **real-time** via WebSocket (Laravel Reverb). Jika koneksi WebSocket tidak tersedia, data di-refresh otomatis tiap 30 detik.

### Widget Bawaan

| Widget | Isi |
|--------|-----|
| CPU Load | Persentase penggunaan CPU dengan sparkline |
| Memory | RAM used/total |
| Storage | Disk used/total |
| Live Users | Sesi aktif saat ini |
| Queue Stats | Job pending/processed/failed |
| Activity Feed | Log aktivitas terbaru (butuh permission `view health and logs`) |
| AI Security Insight | Skor keamanan terakhir dari AI analysis (butuh permission `view ai log analysis`) |

### Kustomisasi Dashboard

1. Klik tombol **Customize** di pojok kanan atas halaman Dashboard
2. Panel kustomisasi muncul dengan daftar widget:
   - Toggle switch untuk **tampilkan/sembunyikan** setiap widget
   - Drag-and-drop widget untuk **mengubah urutan** tampilan
3. Klik **Save Layout** — preferensi tersimpan di database per akun
4. Klik **Reset to Default** untuk kembali ke urutan dan visibilitas bawaan

> Preferensi layout **per-user** — setiap admin bisa punya tata letak sendiri.

---

## Menu Utama

### 1. Users — Manajemen Pengguna

**Akses:** sidebar → User Management

- Tambah / edit / hapus user (soft delete — bisa di-restore)
- Atur role (Super Admin, Admin, Custom)
- Aktif / nonaktifkan akun
- **Bulk action** — aktifkan/nonaktifkan/hapus banyak user sekaligus
- **Impersonate** — login sebagai user lain untuk debugging
  - Tidak bisa impersonate diri sendiri
  - Tidak bisa impersonate Super Admin/Developer
  - Tidak bisa impersonate user inactive
  - Tidak bisa nested impersonate (loop prevention)

> Force delete diri sendiri di-blokir oleh sistem — gunakan akun admin lain bila perlu.

### 2. Roles & Permissions

**Akses:** sidebar → Access Control

- Buat role baru dan pilih permission yang diizinkan
- **Permission dikelompokkan per kategori** dalam dua panel:
  - Panel kiri (**Available**) — permission yang belum diberikan ke role ini
  - Panel kanan (**Assigned**) — permission yang sudah diberikan
  - Pindahkan dengan **drag-and-drop** atau **double-click** item
  - Gunakan **search** di masing-masing panel untuk filter cepat
  - **Category group headers** muncul otomatis di panel Assigned saat ada permission dari kategori tersebut
- **85 granular tab permissions** — setiap tab di Global Settings dan Mobile Settings punya permission sendiri (mis. `manage global settings password policy`, `view mobile settings kill switch`)
- Role dan permission bisa diaktif/nonaktifkan tanpa dihapus
- Audit trail tersedia: setiap perubahan role/permission tercatat
- Tidak bisa archive role yang masih dipakai user — pindahkan user dulu

### 3. Action Logs — Audit Trail

**Akses:** sidebar → Action History

Mencatat semua perubahan data: siapa, kapan, apa yang diubah, dari IP mana. Berguna untuk audit & forensik.

Sensitive fields (password, token, secret, 2fa_secret) otomatis di-redact dari log entry.

---

## System Settings

### Global Settings

**Akses:** System Settings → Global Settings

| Tab | Pengaturan |
|-----|------------|
| General (Branding) | Nama app, logo, favicon, tagline, footer, landing page visibility, locale |
| Login Security | Max attempts, lockout duration, 2FA, OTP, captcha (reCAPTCHA v2/v3), passkey (WebAuthn) |
| Password Policy | Panjang min/max, karakter wajib (uppercase/lowercase/angka/simbol), expiry, riwayat |
| Social Login / OAuth | Toggle Google/Facebook/GitHub OAuth, client ID & secret, callback URL |
| IP & Access | Whitelist/blacklist IP admin, CORS, rate limit, force HTTPS, HSTS |
| Notification | SMTP (host, port, encryption, from address), Telegram bot token & chat ID |
| AI Config | Provider (GPT/Gemini/Claude/DeepSeek/Grok/Mistral/OpenRouter), API key, model, temperature |
| SAP Integration | RFC host, system number, client, user, password — termasuk tombol Test Connection |
| Backup & Storage | Driver (local/S3/GDrive), jadwal, retensi, enkripsi, notifikasi |
| Maintenance | Toggle, pesan, judul, countdown, secret key, IP whitelist |
| Legal & Content | Privacy Policy, Terms of Use, About, Security Policy, Help Center (editor WYSIWYG) |
| Regional | Timezone, format tanggal, format waktu |
| Session | Driver, lifetime, single session, auto logout, remember me, cookie settings |

> Tombol **Save Configuration** selalu muncul di pojok kanan bawah (floating). Setelah save, cache otomatis di-invalidate.

### Mobile Settings

**Akses:** System Settings → Mobile Settings

Kontrol konfigurasi aplikasi mobile dari jarak jauh — warna tema, base URL API, FCM topic, biometric login, kill switch, pesan maintenance mobile, dll. Perubahan langsung tersinkron ke aplikasi mobile via endpoint `/api/v1/mobile/sync` (dengan ETag caching).

### Maintenance Mode

**Akses:** System Settings → Maintenance (atau via tab di Global Settings)

1. Aktifkan toggle **Enable Maintenance Mode**
2. Isi judul & pesan untuk pengunjung
3. (Opsional) set **End Time** untuk countdown timer — aplikasi auto-release saat waktu berlalu
4. (Opsional) isi **Secret Key** — admin bisa tetap akses via `domain.com/{secret}`
5. (Opsional) isi **IP Whitelist** — IP yang dikecualikan dari maintenance
6. Klik **Apply Maintenance Settings**

> Live preview ditampilkan persis seperti yang dilihat pengunjung.

### Backup & Restore

**Akses:** System Settings → Backup & Storage

- Pilih **driver**: Local / Amazon S3 / Google Drive
- Atur jadwal backup otomatis, retensi (berapa backup disimpan), dan enkripsi AES-256
- Operasi: Run Backup Now, Download, Restore, Delete
- Notifikasi backup bisa dikirim ke email atau webhook
- Tombol **Test Connection** untuk verifikasi driver sebelum simpan

### System Monitoring

**Akses:** System Settings → System Monitoring

| Tab | Isi |
|-----|-----|
| Logs | Laravel error log (filter level, search, download, clear) |
| SAP Logs | Log integrasi SAP RFC — status request dan error |
| Mobile Logs | Log yang dikirim dari aplikasi mobile (`/api/v1/mobile/log`) |
| Background Jobs | Status queue, retry / delete failed jobs |
| AI Usage | Riwayat penggunaan AI — provider, model, token, waktu |
| Health | CPU, memory, disk usage secara real-time |

### Notification Center

**Akses:** sidebar → Notifications (ikon lonceng)

Pusat notifikasi sistem real-time via WebSocket (Reverb). Admin bisa:

- Melihat notifikasi masuk
- Menandai sudah dibaca (satu atau semua)
- Broadcast notifikasi ke semua user atau role tertentu

### Session Manager

**Akses:** System Settings → Session Manager

Lihat semua sesi aktif seluruh user. Bisa memaksa logout user tertentu jika dicurigai kompromi akun.

Jika `Single Session` aktif di Global Settings, user otomatis di-logout dari device lama saat login di device baru.

---

## Profil & Keamanan Akun

**Akses:** klik nama/avatar di pojok kanan atas → Profile

- Update nama, email, avatar
- Ganti password (cek policy: min 12, mixed-case, digit, symbol; tidak boleh sama dengan password sebelumnya jika history blocker aktif)
- Daftarkan / hapus **Passkey (biometrik)**
- Lihat & cabut sesi aktif

### Password Expiry

Jika admin mengaktifkan **Password Expiry** di Global Settings → Password Policy, user akan diarahkan ke `/profile/password` saat password lewat masa berlaku, dengan pesan warning.

---

## Halaman Legal (UU PDP)

Halaman publik yang bisa diakses tanpa login:

| URL | Konten |
|-----|--------|
| `/legal/privacy` | Kebijakan Privasi |
| `/legal/tos` | Syarat & Ketentuan |
| `/legal/about` | Tentang Biiproject |
| `/legal/security` | Kebijakan Keamanan |
| `/legal/help` | Pusat Bantuan & FAQ |

Konten semua halaman ini dikelola via Global Settings → Legal & Content.

Jika versi dokumen (`pdp_document_version` atau `tos_document_version`) diperbarui, user yang sudah login akan diarahkan ke halaman **re-agree** (`/legal/re-agree`) dan wajib menyetujui ulang sebelum bisa mengakses aplikasi.

---

## Tips Operasional

1. **Setelah menjalankan seeder**, selalu clear cache: `./vendor/bin/sail artisan cache:clear`
2. **Backup sebelum update** besar atau perubahan konfigurasi penting
3. Selalu uji koneksi (Email, SAP, Backup) lewat tombol **Test Connection** sebelum save
4. Setelah ubah `.env`, jalankan: `./vendor/bin/sail artisan optimize:clear`
5. Cek **Action Logs** secara berkala untuk audit keamanan
6. **Maintenance Mode**: selalu set Secret Key agar tidak terkunci dari panel sendiri
7. **IP Whitelist Admin**: tambahkan dulu IP statis Anda sebelum mengaktifkan, agar tidak terkunci
8. **2FA**: untuk akun super admin, sangat disarankan diaktifkan
9. **Single Session**: untuk environment sensitif (PII, finance), aktifkan agar 1 akun = 1 device

---

## Bantuan & Troubleshooting

| Masalah | Solusi |
|---------|--------|
| Lupa password admin | `./vendor/bin/sail artisan tinker` → reset via model `User` |
| Panel tidak responsif / data lama | `./vendor/bin/sail artisan optimize:clear` + `cache:clear` |
| Error 500 | Cek `storage/logs/laravel.log` atau menu System Monitoring → Logs |
| Setting yang baru disimpan tidak muncul | `./vendor/bin/sail artisan cache:clear` |
| User tidak bisa login | Cek status akun di User Management, pastikan role & permission aktif |
| Notifikasi real-time tidak muncul | Pastikan Reverb berjalan: `supervisorctl status biiproject-reverb` |
| Dashboard stats tidak update otomatis | Cek koneksi WebSocket di browser DevTools (Console). Jika gagal, refresh — akan fallback ke polling 30 detik. |
| Widget tersimpan tidak muncul | Buka Customize panel, klik Reset to Default, lalu coba Save Layout ulang. |
| Tab Settings tidak bisa diakses | Permission tab-level mungkin belum diberikan ke role Anda — minta Super Admin assign via Roles & Permissions. |
| Kena rate limit terus | Cek IP whitelist admin, tunggu 1 menit, atau reset via `php artisan cache:clear` |
| 2FA email tidak masuk | Verifikasi SMTP di Global Settings → Notifications + cek log queue |
| OAuth Google/Facebook gagal | Cek `/auth/callback` reachable (bukan 404), Client ID/Secret valid, redirect URI cocok |
| Health endpoint return 503 | Buka `/api/health`, lihat field `checks.*` — yang `fail` mengindikasikan dependensi rusak. `warn` masih 200. |
| User di-logout otomatis | Single-session mungkin aktif (login dari device lain), atau password expired |