Appearance (Tampilan)
| Code | SET-APR |
| Module | Settings |
| Type | Tenant configuration (singleton) |
| Status | Implemented |
| Priority | P1 |
| Process | Setup tenant |
| API | [URL Postman] |
1. Overview
Tampilan adalah pengaturan tema antarmuka yang berlaku untuk seluruh tenant: jenis huruf, warna utama, warna dasar, kelengkungan sudut, dan skala teks. Hanya ada satu pengaturan per tenant (singleton). Admin memilih opsi dari daftar yang tersedia, melihat hasilnya langsung (live preview) di seluruh dashboard, lalu menyimpannya.
Hasil yang diharapkan: setiap tenant bisa menyesuaikan tampilan dashboard dengan identitas mereknya tanpa bantuan developer.
2. Problem
- Semua tenant tampil identik, sehingga dashboard tidak terasa milik bisnis mereka.
- Sebagian pengguna butuh teks yang lebih besar atau lebih kecil agar nyaman dipakai di perangkat toko.
- Mengubah tema lewat kode per tenant tidak bisa diskalakan.
3. Goals & Non-goals
Goals
- Admin bisa mengubah tema tenant sendiri. Indikator: perubahan tema tidak memerlukan deploy.
- Admin melihat hasil sebelum menyimpan. Indikator: setiap pilihan langsung diterapkan ke seluruh antarmuka saat mode ubah.
- Perubahan yang tidak disimpan tidak bocor. Indikator: meninggalkan halaman ubah tanpa simpan mengembalikan tema tersimpan.
Non-goals
- Tema per pengguna (tema berlaku untuk seluruh tenant)
- Warna kustom bebas (hex / color picker); hanya dari daftar opsi
- Unggah font kustom
- Pengaturan mode terang/gelap (mengikuti preferensi perangkat pengguna)
4. User Scenarios
| Role | Scenario |
|---|---|
| Owner | Menyamakan warna utama dashboard dengan warna merek toko |
| Owner | Memperbesar skala teks agar kasir yang lebih tua nyaman membaca |
| Admin | Mencoba beberapa kombinasi warna, lalu batal karena hasilnya kurang cocok |
| Auditor | Melihat riwayat siapa yang mengubah tampilan dan kapan |
5. User Flow
- Mode lihat — Menampilkan 5 pengaturan dengan opsi aktif ditandai; opsi lain tampil redup. Tombol Log Aktivitas dan Ubah Data (jika berizin).
- Mode ubah — Halaman
/settings/appearance/edit, opsi bisa diklik. - Pilih opsi — Setiap klik langsung menerapkan tema ke seluruh dashboard (sidebar, tombol, teks) sebagai pratinjau.
- Simpan — Tombol Perbarui aktif hanya jika ada perubahan. Error dari BE ditampilkan pada field.
- Tersimpan — Toast sukses, lalu kembali ke mode lihat.
- Tinggalkan tanpa simpan — Konfirmasi perubahan belum disimpan; jika pengguna tetap keluar, tema dikembalikan ke nilai tersimpan.
Alternative paths
- Pengguna tanpa izin ubah membuka URL edit — diarahkan ke halaman unauthorized.
- Pengguna menekan back browser saat pratinjau — tema dikembalikan ke nilai tersimpan (sama seperti langkah 6).
6. User Stories
Prioritas: P0 wajib untuk rilis, P1 penting, P2 kalau sempat.
US-01 — Melihat pengaturan tampilan (P1)
Sebagai admin, saya ingin melihat tema yang sedang aktif, agar tahu konfigurasi tenant saat ini.
| ID | Kriteria penerimaan |
|---|---|
| AC-01.1 | Pengguna dengan izin view melihat 5 pengaturan: Font, Warna Utama, Warna Dasar, Sudut, Skala, masing-masing dengan label dan deskripsi. |
| AC-01.2 | Opsi aktif ditandai; opsi lain tampil redup dan tidak bisa diklik. |
| AC-01.3 | Skeleton tampil selama data dimuat. |
US-02 — Mengubah tampilan dengan pratinjau (P1)
Sebagai admin, saya ingin mencoba opsi tema dan langsung melihat hasilnya, agar yakin sebelum menyimpan.
| ID | Kriteria penerimaan |
|---|---|
| AC-02.1 | Tombol Ubah Data hanya tampil untuk pengguna dengan izin update. |
| AC-02.2 | Di mode ubah, memilih opsi langsung menerapkan tema ke seluruh antarmuka. |
| AC-02.3 | Tombol Perbarui nonaktif sampai ada perubahan. |
| AC-02.4 | Setelah berhasil disimpan, toast sukses tampil dan pengguna kembali ke mode lihat dengan tema baru. |
| AC-02.5 | Saat meninggalkan mode ubah tanpa menyimpan, muncul konfirmasi; jika tetap keluar, tema kembali ke nilai tersimpan. |
US-03 — Riwayat perubahan (P2)
Sebagai owner, saya ingin melihat log aktivitas tampilan, agar tahu siapa mengubah tema.
| ID | Kriteria penerimaan |
|---|---|
| AC-03.1 | Tombol Log Aktivitas di mode lihat membuka panel log dengan filter event, pelaku, dan rentang tanggal. |
7. Document Structure
| Field | Required | Default | Notes |
|---|---|---|---|
Font (font_family) | Tidak | Default aplikasi | Geist, Roboto, Open Sans, Lato, Montserrat, Inter, Poppins, Raleway, Manrope, DM Sans |
Warna Utama (primary_color) | Tidak | Default aplikasi | Neutral, Red, Orange, Amber, Yellow, Lime, Green, Emerald, Teal, Cyan, Sky, Blue, Indigo, Violet, Purple, Fuchsia, Pink, Rose |
Warna Dasar (base_color) | Tidak | Default aplikasi | Neutral, Slate, Gray, Zinc, Stone, Taupe, Mauve, Mist, Olive |
Sudut (radius) | Tidak | Default aplikasi | none (Tajam), standard (Sedang), large (Penuh) |
Skala (scale) | Tidak | Default aplikasi | sm (Kecil), md (Sedang), lg (Besar) |
Nilai disimpan sebagai id opsi (misalnya blue, dm-sans).
8. Status Lifecycle
Tidak berlaku. Tampilan adalah pengaturan singleton tanpa status.
9. Permissions & Actions
Permissions
| Action | Permission | Syarat tambahan |
|---|---|---|
| Lihat tampilan dan log aktivitas | settings:appearance:view:any | — |
| Ubah tampilan | settings:appearance:update:any | — |
FE menyembunyikan tombol Ubah Data dan mengalihkan URL edit ke unauthorized bila tidak berizin; BE tetap menolaknya.
10. Business Rules
Aturan bisnis adalah ketentuan yang berlaku di semua layar dan semua aksi, siapa pun yang melakukannya. FE memakainya sebagai validasi di form, BE memakainya sebagai sumber kebenaran; jika keduanya berbeda, perilaku BE yang dianggap benar dan FE menyesuaikan.
- BR-01 Satu pengaturan tampilan per tenant, berlaku untuk semua pengguna tenant.
- BR-02 Nilai setiap field harus salah satu id opsi yang didefinisikan di bagian 7.
- BR-03 Pratinjau hanya bersifat lokal di browser pengguna yang mengubah; pengguna lain baru melihat perubahan setelah disimpan.
- BR-04 Tema tenant dimuat dari data inisialisasi tenant (
/public/init) yang di-cache hingga 1 hari; setelah simpan, cache ini harus diperbarui agar semua sesi memakai tema baru. - BR-05 Setiap perubahan dicatat di log aktivitas.
11. Edge Cases
Edge case adalah kondisi yang jarang terjadi tetapi pasti muncul di operasional nyata. Perilaku yang diharapkan ditetapkan di sini agar tidak diputuskan sendiri-sendiri saat implementasi.
| ID | Case | Expected behavior |
|---|---|---|
| EC-01 | Tema disimpan, lalu halaman di-reload | Harus memakai tema baru. Saat ini simpan Tampilan belum memperbarui cache data inisialisasi tenant (berbeda dengan Perusahaan), sehingga tema lama bisa tampil kembali hingga cache kedaluwarsa (BR-04) |
| EC-02 | Dua admin mengubah tampilan bersamaan | Simpan terakhir yang berlaku |
| EC-03 | Tenant belum pernah mengatur tampilan | Semua field kosong; antarmuka memakai tema default aplikasi |
| EC-04 | Pengguna keluar dari mode ubah tanpa simpan | Tema dikembalikan ke nilai tersimpan terakhir |
12. API Contract
| Action | Method | Endpoint | Ref |
|---|---|---|---|
| Detail tampilan | GET | /api/appearance | US-01 |
| Ubah tampilan | PUT | /api/appearance | US-02 |
| Log aktivitas | GET | /api/appearance/activity-logs/cursor | US-03 |
| Data inisialisasi tenant (company + appearance) | GET | /public/init | BR-04 |
13. Dependencies
PRD terkait
- Company (Perusahaan) — berbagi data inisialisasi tenant yang sama (
/public/init). - Activity Logs — sumber log aktivitas.
Efek ke modul lain
- Tema diterapkan ke seluruh aplikasi tenant-dashboard, termasuk halaman auth.