Lompat ke konten utama
StableTerakhir diperbarui: 9 Okt 2026, 09.28

Manajemen Pengguna, Hak Akses & Model Dual-Axis RBAC

Seiring bertumbuhnya organisasi bisnis dari satu toko kecil menjadi perusahaan dengan puluhan staf customer service dan manajer cabang, risiko kebocoran data sensitif dan penyalahgunaan wewenang meningkat pesat. DagangBot mengimplementasikan arsitektur kontrol akses tingkat lanjut: Dual-Axis Role-Based Access Control (RBAC).

Stable

1. Ikhtisar & Nilai Bisnis

Pendekatan RBAC konvensional hanya membatasi aksi (misal: "Boleh mengedit katalog produk"). Namun, dalam bisnis retail multi-cabang, hal tersebut belum cukup. Staf di Bandung tidak boleh melihat omset penjualan atau data pelanggan cabang Surabaya. Model Dual-Axis DagangBot memadukan dua dimensi penguncian secara serentak:

  • Sumbu 1 - Hak Akses Aksi (Permission Axis): Menentukan apa yang dapat dilakukan pengguna terhadap sumber daya sistem (read, create, update, delete, export).
  • Sumbu 2 - Cakupan Cabang (Branch Scope Axis): Menentukan di cabang fisik mana saja pengguna tersebut diizinkan melihat atau memanipulasi data (ALL_BRANCHES vs cabang spesifik).
  • Pencegahan Akses Berlebih (Principle of Least Privilege): Memastikan bahwa staf hanya dapat mengakses modul yang relevan. Misalnya, kasir tidak bisa melihat pengaturan integrasi API atau log penagihan (billing).
  • Log Jejak Aktivitas (Audit Trail): Setiap perubahan penting pada konfigurasi akan direkam pada audit log (hanya baca).
Prinsip Isolasi Tenant & Cabang

Di lapisan database, sistem menerapkan PostgreSQL Row-Level Security (RLS) berdasarkan klaim user_id, tenant_id, dan branch_id yang tertera pada token JWT sesi pengguna.

2. Alur Visual & Antarmuka

Berikut adalah tampilan tabel manajemen staf pengguna dan editor konfigurasi hak akses modul (Dual-Axis RBAC):

Daftar pengguna dan staf toko dengan status peran dan cabang
Antarmuka daftar staf pengguna dan penugasan cabang
Editor izin RBAC matriks hak akses modul sistem
Editor konfigurasi hak akses granular (Dual-Axis RBAC)

3. Panduan Langkah-demi-Langkah

Ikuti alur berikut untuk mengundang anggota tim baru dan menetapkan perannya:

  1. 1

    Langkah 1: Akses Menu Manajemen Tim

    Buka dasbor merchant di bilah menu kiri, pilih Pengaturan → Pengguna & Staf. Anda akan melihat daftar anggota tim yang aktif saat ini beserta peran masing-masing.

  2. 2

    Langkah 2: Klik Tombol Undang Anggota Tim

    Klik tombol biru + Undang Pengguna. Masukkan alamat email staf yang valid dan nama lengkap mereka.

  3. 3

    Langkah 3: Pilih Peran (Role) Sumbu Izin

    Pilih salah satu peran standar yang tersedia:

    • Owner / Administrator: Hak akses penuh ke seluruh modul, keuangan, dan pengaturan API. Memiliki kapabilitas GrantsAllResources (akses semua) dan CanManageRBAC.
    • Branch Manager: Akses laporan, katalog, dan pesanan terbatas pada cabangnya sendiri.
    • CS / Agen Penjualan: Hanya memiliki akses ke Live Inbox percakapan dan modul Takeover CRM.
    • Kasir (Cashier): Akses pembuatan invoice transaksi dan pemeriksaan bukti transfer.
  4. 4

    Langkah 4: Tentukan Cakupan Cabang (Scope Axis) & Kirim

    Pilih cabang tempat staf tersebut bertugas (contoh: Cabang Jakarta Selatan). Klik Kirim Undangan. Tautan aktivasi akun akan dikirimkan ke email staf tersebut secara otomatis.

4. Parameter & Spesifikasi Matriks Hak Akses

Antarmuka Manajemen Tim dan Editor Konfigurasi Izin memetakan parameter Role yang diinterpretasikan oleh lapisan otorisasi dan keamanan pada sistem backend. Tabel di bawah merangkum parameter dan matriks hak akses nyata (resource keys) beserta efeknya pada sistem:

Modul (Resource Key) Aksi Sistem Keterangan Efek di Aplikasi dan API
billing_usage read Izinkan melihat log pemakaian token pada menu kuota dan tagihan. Tanpa ini, halaman akan menampilkan Error 403 Forbidden.
billing read, create, update Izinkan manajemen penagihan tingkat perusahaan, top-up, dan invoice. Semua rute penagihan membutuhkan izin ini.
users read, create, update, delete Izinkan menambah staf baru, menetapkan/mengubah Role, dan mencabut sesi pengguna.
orders read, create, update Izinkan membaca, membuat, dan memodifikasi status pesanan, serta validasi manual struk transaksi dari pelanggan.
analytics read, export Izinkan membaca komponen visualisasi dashboard tingkat cabang dan mengunduh laporan (CSV) melalui menu ekspor laporan.
wa_instances read, create, update, delete Memberikan akses untuk memanipulasi pengaturan koneksi gerbang WhatsApp, sinkronisasi template WA, rotasi sesi, serta penyelarasan kapabilitas fungsional jaringan (notification atau chat_cs).
fraud read, update Memberikan izin manajerial untuk melihat log Anti-Fraud Shield, membaca riwayat peringatan kritis kebocoran nomor rekening pribadi staf, serta memberikan izin mengotorisasi aturan resolusi pengecualian (whitelist).
platform_rbac read, create, update Akses pengelolaan matriks perizinan tingkat toko (dikhususkan bagi Pemilik Toko / Owner). Staf biasa tidak mendapatkan kapabilitas ini.
branches read, update, delete Hak prerogatif untuk membuka cabang ritel baru dan mengelola alokasi pemisahan pangkalan data pelanggan dari tiap gerai fisik.

Matriks Izin, Peran Bawaan, dan Penolakan Akses (403)

Sistem otentikasi membagi pengguna ke dalam peran bawaan (built-in) yang immutable seperti owner, dan peran kustom tingkat staf. Matriks izin dibentuk berdasarkan kombinasi Modul (Resource) dan Aksi (Action) (misal: create, read, update, delete). Hak akses juga dikontrol oleh Cakupan Cabang (Scope Axis) yang menentukan apakah staf dapat melihat data seluruh cabang atau hanya cabangnya saja.

Evaluasi kelayakan perubahan izin ditangani oleh layanan otorisasi peran (RBAC). Jika pengguna melanggar aturan pengelolaan matriks hak akses, sistem memunculkan respons 403 Forbidden dengan galat nyata berikut:

  • ErrOwnerImmutable403: "owner permissions are immutable: peran owner bersifat immutable dan tidak dapat diubah".
  • ErrCannotManageRBAC403: "peran Anda tidak memiliki wewenang mengubah matriks izin" (dimunculkan saat peran pengguna aktif tidak memiliki deklarasi can_manage_rbac).
  • ErrRoleNotJunior403: "hanya peran yang lebih junior yang dapat diubah" (pengguna mencoba mengedit peran dengan tingkat yang sama atau lebih tinggi).
  • ErrGrantExceedsOwn403: "izin yang diberikan melebihi izin pengelola".

Setiap perubahan hak akses oleh pengelola wajib tercatat dalam log melalui fungsi internal writeAuditLog, yang merekam identitas staf, matriks izin baru, serta informasi perangkat (user-agent) untuk keperluan jejak audit yang tidak bisa dimanipulasi.

Pembatasan Aksi Penghapusan (Immutability)

Sebagian besar aksi delete (hapus permanen) pada tabel data krusial (seperti pesanan e-commerce, catatan laporan transaksi pembayaran finance_global, log tagihan billing) secara arsitektural dinonaktifkan keras (hard-disabled) di tingkat keamanan peladen terlepas dari konfigurasi roles UI, guna mencegah penghapusan jejak manipulasi audit yang dapat merusak integritas keamanan pelaporan keuangan (Immutable Audit Log).

5. Kasus Tepi (Edge Cases)

Dalam operasional organisasi perusahaan tingkat menengah dan atas, banyak situasi tidak lazim (edge cases) yang ditangani oleh komponen Dual-Axis RBAC. Berikut cara sistem menghadapi skenario tersebut:

Skenario Anomali Operasional Respons Arsitektur Peladen Penjelasan Mekanisme Resolusi Penanganan Lanjutan
Pergantian Cabang Mendadak Sesi pengguna otomatis gugur sementara Apabila manajer menetapkan perpindahan seorang agen CS dari cabang Jakarta ke cabang Bali melalui BranchAssignmentModal, claim parameter branch_id pada payload token JWT milik agen menjadi tidak berlaku. Layar staf akan otomatis dialihkan ke halaman otentikasi (sejenak) untuk memaksa negosiasi penyegaran token JWT (Silent Token Refresh) yang memuat status cabang terbarunya.
Pencabutan Izin Modul (Revoke Permission) Saat Digunakan Permintaan (Request) Ditolak (403 Forbidden) Jika Owner mencentang hilang (hapus) hak akses orders:update bagi peran Cashier ketika kasir tersebut sedang menekan tombol "Setujui Pesanan", middleware otorisasi peladen yang mengevaluasi kebijakan peran seketika langsung mencegat request payload dan mengembalikan status penolakan keamanan.
Akun Staf Utama Ditangguhkan (Suspended Tenant User) Sesi Berakhir Menyeluruh (Global Session Kill) Saat status kepegawaian dinonaktifkan total dari daftar User di tabulasi profil utama, TenantSuspendGuard menyebarkan sinyal peristiwa penghentian (event kill-switch). Setiap sambungan WebSocket Hub percakapan atas nama staf bersangkutan serta status kredensial otentikasinya akan diputus paksa tanpa menunggu waktu kedaluwarsa normal sisa token API.

6. Relasi & Integrasi Hubungan Modular

Sistem kontrol akses terkait erat dengan banyak subsistem lainnya dalam DagangBot:

  • Isolasi RLS (Row-Level Security) PostgreSQL: Matriks di atas tidak hanya berkerja di tingkat antarmuka, tetapi diikat langsung sebagai klausul WHERE paksa pada database. Cabang A tidak dapat querying pesanan Cabang B meski meng-hack API.
  • WebSocket & Real-Time Sync: Aktivitas dari staf pada satu cabang (seperti mengubah pesanan) dikomunikasikan secara live lewat WebSocket (billing_usage, ws_ticket), namun pesannya difilter oleh perizinan branch_id penerima agar tidak terjadi kebocoran informasi ke cabang lain.
  • Audit & Penagihan (Billing): Staf yang membuat pesanan dengan hak aksesnya akan dicatat oleh sistem tagihan (modul billing) untuk rekap pemotongan kuota layanan bulanan.

7. Pemecahan Masalah (Troubleshooting) Kesalahan Sistem Otentikasi

Gejala Penyebab Solusi Tindakan
Staf CS mengeluh tidak bisa melihat riwayat pesanan (Tombol pesanan abu-abu atau Error 403) Peran staf disetel ke CS Agent namun belum memiliki izin read pada resource orders. Edit peran staf pada editor RBAC, centang izin aksi read pada modul Pesanan & Commerce.
Manajer cabang tidak melihat menu laporan keuangan tokonya Fitur laporan keuangan diblokir sepenuhnya, tidak ada izin read di modul analytics. Berikan akses modul analytics:read kepada Branch Manager (ini akan secara otomatis ter-scope pada cabangnya).
Tautan undangan email pengguna gagal divalidasi atau kedaluwarsa Staf tidak mengklik tautan email OTP/Aktivasi dalam batas waktu aktif wajar. Buka daftar pengguna, klik ikon titik tiga di samping nama staf terkait, dan pilih Kirim Ulang Undangan.
Mantan staf yang sudah dipecat (resign) masih bisa menggunakan API sistem Sesi login token JWT (Refresh Identity) masih beredar aktif di perangkat mantan staf karena akunnya hanya dibiarkan. Masuk ke dasbor, ubah status staf menjadi Nonaktif (Revoke). Ini memicu sesi token staf gugur pada detik itu juga melalui revocation guard RBAC.

8. Referensi Terkait Pustaka Pengetahuan

content/docs/features/rbac-users.mdx
Terakhir diperbarui: 9 Okt 2026, 09.28

Dokumentasi teknis DagangBot