Roles & Permissions (Peran & Izin)
| Code | SET-ROL |
| Module | Settings |
| Type | Master data (akses) |
| Status | Implemented |
| Priority | P0 — MVP |
| Process | Setup tenant |
| API | [URL Postman] |
1. Overview
Peran adalah kumpulan hak akses (permission) yang diberikan ke pengguna. Admin membuat peran seperti “Kepala Toko” atau “Purchasing”, lalu memilih hak akses yang dimilikinya dari katalog yang disusun bertingkat: Modul → Fitur → Aksi. Pengguna bisa punya lebih dari satu peran, dan hak aksesnya adalah gabungan semua perannya.
Setiap hak akses punya kunci berformat modul:fitur:aksi:scope, misalnya purchase:purchase-order:submit:store. Scope any berarti berlaku untuk semua data; scope store berarti terbatas pada toko. Kunci inilah yang diperiksa di setiap halaman dan aksi aplikasi.
Hasil yang diharapkan: tenant bisa mengatur siapa boleh melakukan apa tanpa perubahan kode, dengan granularitas sampai level aksi.
2. Problem
- Tugas staf berbeda-beda; memberi semua akses ke semua orang berisiko.
- Hak akses yang hanya dibedakan per modul terlalu kasar, misalnya staf boleh membuat PO tetapi tidak boleh mengajukannya.
- Mengatur hak akses per orang tidak bisa diskalakan; perlu dikelompokkan per peran.
3. Goals & Non-goals
Goals
- Admin bisa membuat peran dengan hak akses sampai level aksi. Indikator: setiap aksi di aplikasi dikendalikan oleh satu kunci permission.
- Peran mudah disusun. Indikator: pilih semua per modul atau per fitur, plus pencarian aksi.
- Peran mudah diperiksa. Indikator: detail peran hanya menampilkan modul dan fitur yang punya hak akses terpilih.
Non-goals
- Membuat permission baru dari UI (katalog permission berasal dari BE)
- Hak akses per pengguna di luar peran
- Pembatasan per toko tertentu di level peran (scope
storemengikuti penugasan toko)
4. User Scenarios
| Role | Scenario |
|---|---|
| Owner | Membuat peran “Kasir” yang hanya boleh mengakses modul Sales |
| Owner | Membuat peran “Purchasing” dengan semua aksi PO kecuali Tutup |
| Admin | Memeriksa hak akses peran “Kepala Toko” sebelum menugaskannya ke pengguna baru |
| Owner | Menghapus peran lama yang sudah tidak dipakai |
5. User Flow
- Nama peran — Wajib diisi.
- Modul — Setiap modul tampil sebagai tab (vertikal di desktop, horizontal bisa di-scroll di mobile). Checkbox pada tab memilih atau melepas semua aksi di modul itu; klik ulang tab yang aktif juga melakukan hal yang sama.
- Fitur & aksi — Di dalam modul, fitur tampil sebagai kartu yang bisa dilipat, dengan checkbox pilih-semua per fitur, jumlah aksi terpilih, dan kotak pencarian aksi. Setiap aksi punya checkbox sendiri.
- Validasi — Minimal satu hak akses harus dipilih.
- Tersimpan — Toast sukses, kembali ke daftar peran.
- Penugasan — Peran dipilih untuk pengguna di menu Pengguna.
Alternative paths
- Mode lihat — hanya menampilkan modul dan fitur yang punya aksi terpilih, tanpa checkbox. Bila tidak ada, tampil “Data tidak ditemukan”.
- Hapus peran — satuan atau massal dari daftar, setelah konfirmasi.
6. User Stories
Prioritas: P0 wajib untuk rilis, P1 penting, P2 kalau sempat.
US-01 — Membuat peran (P0)
Sebagai owner, saya ingin membuat peran dengan hak akses tertentu, agar bisa diberikan ke pengguna.
| ID | Kriteria penerimaan |
|---|---|
| AC-01.1 | Form berisi nama peran dan pemilih hak akses bertingkat Modul → Fitur → Aksi. |
| AC-01.2 | Nama peran wajib; minimal satu hak akses wajib dipilih. |
| AC-01.3 | Checkbox modul memilih/melepas semua aksi di modul; checkbox fitur memilih/melepas semua aksi di fitur. |
| AC-01.4 | Setiap fitur menampilkan jumlah aksi dan kotak pencarian aksi; semua fitur terbuka saat pertama dimuat. |
| AC-01.5 | Setelah berhasil, toast sukses tampil dan pengguna diarahkan ke daftar peran. |
US-02 — Melihat detail peran (P0)
Sebagai admin, saya ingin melihat hak akses sebuah peran, agar yakin sebelum menugaskannya.
| ID | Kriteria penerimaan |
|---|---|
| AC-02.1 | Detail hanya menampilkan modul dan fitur yang punya minimal satu aksi terpilih. |
| AC-02.2 | Checkbox tidak tampil dan tab modul tidak bisa mengubah pilihan. |
US-03 — Mengubah peran (P0)
Sebagai owner, saya ingin mengubah nama atau hak akses peran, agar sesuai kebutuhan terbaru.
| ID | Kriteria penerimaan |
|---|---|
| AC-03.1 | Tombol Ubah Data hanya tampil untuk pengguna dengan izin update. |
| AC-03.2 | Validasi sama dengan pembuatan; tombol simpan aktif hanya jika ada perubahan. |
| AC-03.3 | Perubahan hak akses berlaku untuk semua pengguna yang memiliki peran tersebut. |
US-04 — Daftar peran (P0)
Sebagai owner, saya ingin melihat semua peran, agar mudah mengelolanya.
| ID | Kriteria penerimaan |
|---|---|
| AC-04.1 | Kolom: nama peran dan jumlah hak akses. |
| AC-04.2 | Pencarian kata kunci dan paginasi. |
| AC-04.3 | Aksi baris: Lihat, Ubah, Hapus sesuai izin; hapus massal dari baris terpilih. |
US-05 — Menghapus peran (P1)
Sebagai owner, saya ingin menghapus peran yang tidak dipakai.
| ID | Kriteria penerimaan |
|---|---|
| AC-05.1 | Hapus satuan dan massal memerlukan konfirmasi dan izin delete. |
| AC-05.2 | Bila BE menolak (misalnya peran masih dipakai), pesan error tampil sebagai toast. |
7. Document Structure
Header
| Field | Required | Default | Notes |
|---|---|---|---|
| Nama Peran | Ya | — | Teks bebas |
Hak Akses (permission_ids) | Ya, minimal 1 | — | Array id aksi (number) |
Katalog hak akses (dari BE, read-only)
| Level | Field | Notes |
|---|---|---|
| Modul | name, features[] | Misalnya purchase, settings |
| Fitur | name, actions[] | Misalnya purchase-order |
| Aksi | id, name | id disimpan di peran; name ditampilkan dan bisa dicari |
8. Status Lifecycle
Tidak berlaku. Peran tidak punya status; peran ada atau dihapus.
9. Permissions & Actions
Permissions
| Action | Permission | Syarat tambahan |
|---|---|---|
| Lihat daftar peran | settings:role:list:any | — |
| Lihat detail peran | settings:role:view:any | — |
| Buat peran | settings:role:create:any | — |
| Ubah peran | settings:role:update:any | — |
| Hapus peran | settings:role:delete:any | — |
FE menyembunyikan aksi yang tidak diizinkan; 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 Peran wajib memiliki nama dan minimal satu hak akses.
- BR-02 Kunci permission berformat
modul:fitur:aksi:scope; scopeanyuntuk semua data,storeuntuk data toko tempat pengguna ditugaskan. - BR-03 Hak akses efektif pengguna adalah gabungan hak akses semua perannya.
- BR-04 Katalog permission (modul, fitur, aksi) didefinisikan BE dan tidak bisa diubah dari UI.
- BR-05 FE memeriksa permission di server sebelum merender halaman (redirect ke
/unauthorizedbila tidak berizin) dan menyembunyikan aksi yang tidak diizinkan; BE tetap menegakkan permission di setiap endpoint. - BR-06 Menu sidebar hanya menampilkan item yang permission-nya dimiliki pengguna.
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 | Menghapus peran yang masih dipakai pengguna | Ditentukan BE (menolak, atau pengguna kehilangan hak akses peran itu) |
| EC-02 | Menghapus atau mengurangi hak akses peran milik admin yang sedang login | FE tidak mencegah; BE harus mencegah tenant kehilangan semua akses Settings |
| EC-03 | Hak akses peran diubah saat penggunanya sedang login | Berlaku pada pemeriksaan permission berikutnya (render halaman atau panggilan API) |
| EC-04 | Nama peran duplikat | Ditentukan BE (validasi unik); error tampil pada field |
| EC-05 | Katalog permission kosong | Tampil “Data tidak ditemukan” di pemilih hak akses |
| EC-06 | Perubahan peran tidak tercatat | Peran belum memiliki log aktivitas di UI |
12. API Contract
| Action | Method | Endpoint | Ref |
|---|---|---|---|
| Daftar peran (paginasi, cari) | GET | /api/roles/paginate | US-04 |
| Daftar peran (cursor) | GET | /api/roles/cursor | — |
| Semua peran (opsional dengan hak akses) | GET | /api/roles | — |
| Detail peran | GET | /api/roles/:id | US-02 |
| Buat peran | POST | /api/roles | US-01 |
| Ubah peran | PUT | /api/roles/:id | US-03 |
| Hapus peran | DELETE | /api/roles/:id | US-05 |
| Hapus peran massal | DELETE | /api/roles/bulk | US-05 |
Katalog hak akses bertingkat (is_hierarchical=true) | GET | /api/permissions | AC-01.1 |
| Cek permission pengguna login (server-side) | POST | /auth/check-permission | BR-05 |
13. Dependencies
PRD terkait
- Users — peran ditugaskan ke pengguna.
- Semua modul — setiap halaman dan aksi dijaga kunci permission.
Efek ke modul lain
- Perubahan peran langsung memengaruhi menu sidebar dan aksi yang tersedia bagi semua pengguna pemilik peran tersebut.