Referral

Halaman Referral mengelola program referral untuk mendorong customer mengajak orang lain berbelanja. Dibangun di atas Referral.jsx (745 baris) dengan sistem code generation unik, commission tracking otomatis, leaderboard, dan withdrawal system. Setiap participant mendapat kode referral 8-karakter yang bisa dibagikan melalui WhatsApp, Facebook, Twitter, LinkedIn, atau Email. Setiap referral sukses tercatat dan commission otomatis masuk ke balance.

Arsitektur Komponen

Ringkasan Modul

Modul Referral merupakan salah satu fitur marketing utama dalam SNISHOP ERP yang memungkinkan setiap pengguna menjadi affiliate dan mendapatkan komisi dari setiap referensi berhasil. Sistem ini mencakup:

Code Generation — Pembuatan kode referral unik 8-karakter secara otomatis untuk setiap pengguna
Commission Tracking — Pencatatan dan kalkulasi komisi secara real-time berdasarkan pembelian referee
Leaderboard — Peringkat referrer teraktif untuk mendorong kompetisi sehat (gamifikasi)
Multi-Channel Sharing — Distribusi link referral melalui 5 kanal: WhatsApp, Facebook, Twitter, LinkedIn, dan Email
Withdrawal System — Pencairan saldo komisi ke rekening bank dengan approval workflow
Admin Settings — Konfigurasi commission rate per plan langganan

Entity Relationship Diagram

Entity Schema Tables

User (Referral Fields)

Field-field pada entity User yang berkaitan langsung dengan sistem referral dan komisi.

Field	Tipe	Required	Default	Deskripsi
`referral_code`	string	Tidak	—	Kode referral unik milik user, digunakan sebagai parameter referral link
`referred_by`	string	Tidak	—	ID user yang mereferensikan user ini saat mendaftar (FK ke User)
`commission_balance`	number	Tidak	`0`	Saldo komisi dari referral yang dapat ditarik (withdraw)
`total_earnings`	number	Tidak	`0`	Total komisi yang pernah diterima secara akumulasi (sejarah penghasilan)
`balance`	number	Tidak	`0`	Saldo deposit umum untuk membeli membership atau addon
`admin_commission_balance`	number	Tidak	`0`	Saldo komisi admin basic dari proses transaksi produk digital

Referral

Entity yang merekam setiap hubungan referral antara referrer dan referee.

Field	Tipe	Required	Default	Deskripsi
`referrer_id`	string (FK → User)	Ya	—	ID pengguna yang mengundang (referrer)
`referee_id`	string (FK → User)	Ya	—	ID pengguna yang diundang (referee)
`referee_email`	string	Ya	—	Email pengguna yang diundang
`referee_name`	string	Tidak	—	Nama pengguna yang diundang
`description`	string (max 1000)	Tidak	—	Catatan tambahan mengenai referral ini
`status`	enum	Tidak	`signed_up`	Status undangan: `signed_up` atau `purchased`

ReferralCode

Entity yang menyimpan kode referral unik yang di-generate untuk setiap pengguna.

Field	Tipe	Required	Default	Deskripsi
`code`	string	Ya	—	Kode referral unik (8 karakter, uppercase)
`user_id`	string (FK → User)	Ya	—	ID user pemilik kode referral
`user_email`	string	Tidak	—	Email user pemilik kode
`user_name`	string	Tidak	—	Nama user pemilik kode
`description`	string (max 1000)	Tidak	—	Catatan atau pesan promosi yang menyertai kode referral ini
`is_active`	boolean	Tidak	`true`	Status aktif kode; jika `false`, kode tidak bisa digunakan untuk referral baru

Commission

Entity yang merekam setiap transaksi komisi yang dihasilkan dari referral yang berhasil melakukan pembelian.

Field	Tipe	Required	Default	Deskripsi
`referrer_id`	string (FK → User)	Ya	—	ID pengguna yang menerima komisi
`referee_id`	string (FK → User)	Ya	—	ID pengguna yang melakukan pembelian
`purchase_id`	string	Tidak	—	ID dari transaksi pembelian terkait (misal: ID UpgradeRequest)
`purchase_amount`	number	Ya	—	Jumlah pembelian yang menjadi dasar perhitungan komisi
`commission_rate`	number	Ya	—	Persentase komisi yang diterapkan (misal: 0.50 untuk 50%)
`commission_amount`	number	Ya	—	Jumlah komisi yang didapat (hasil kalkulasi: `purchase_amount * commission_rate`)
`plan_purchased`	string	Tidak	—	Paket yang dibeli oleh referee (misal: `Pro`, `Business`)
`purchase_type`	enum	Tidak	—	Jenis pembelian: `first_time` atau `renewal`
`description`	string (max 1000)	Tidak	—	Catatan detail mengenai komisi ini
`status`	enum	Tidak	`unpaid`	Status komisi: `unpaid`, `paid_to_balance`, atau `rejected`

ReferralSetting

Entity konfigurasi yang menentukan commission rate untuk setiap plan langganan.

Field	Tipe	Required	Default	Deskripsi
`plan_key`	string	Ya	—	Kunci paket langganan terkait (misal: `free`, `pro`, `business`)
`description`	string (max 1000)	Tidak	—	Penjelasan mengenai pengaturan komisi referral untuk paket ini
`first_purchase_commission_rate`	number	Ya	`0.5`	Persentase komisi untuk pembelian pertama (misal: 0.50 untuk 50%)
`renewal_commission_rate`	number	Ya	`0.1`	Persentase komisi untuk pembelian kedua dan seterusnya (misal: 0.10 untuk 10%)

WithdrawalRequest

Entity yang mengelola permintaan penarikan saldo komisi oleh pengguna.

Field	Tipe	Required	Default	Deskripsi
`user_id`	string (FK → User)	Ya	—	ID pengguna yang meminta penarikan
`user_email`	string	Tidak	—	Email pengguna pemohon
`amount`	number	Ya	—	Jumlah yang ditarik (dalam Rupiah)
`bank_account_id`	string	Ya	—	ID rekening bank tujuan penarikan
`bank_account_details`	object	Tidak	—	Snapshot detail rekening bank saat penarikan dilakukan
`withdrawal_source`	enum	Tidak	`commission`	Sumber penarikan: `commission` (dari commission_balance) atau `admin_commission` (dari admin_commission_balance)
`description`	string (max 1000)	Tidak	—	Alasan atau keterangan tambahan dari pengguna mengenai penarikan ini
`status`	enum	Tidak	`pending`	Status permintaan: `pending`, `approved`, atau `rejected`
`admin_notes`	string	Tidak	—	Catatan dari admin yang memproses permintaan
`proof_of_transfer_url`	string	Tidak	—	URL bukti transfer dari admin setelah penarikan disetujui

MarketplaceCommissionSettings

Entity konfigurasi global untuk kebijakan komisi marketplace dan penarikan saldo.

Field	Tipe	Required	Default	Deskripsi
`commission_rate`	number	Ya	`10`	Persentase komisi marketplace (0-100)
`description`	string (max 1000)	Tidak	—	Penjelasan mengenai kebijakan komisi marketplace dan ketentuan penarikan saldo
`min_withdrawal`	number	Tidak	`100000`	Minimum penarikan saldo (dalam Rupiah)
`withdrawal_fee`	number	Tidak	`5000`	Biaya admin per penarikan (dalam Rupiah)
`is_active`	boolean	Tidak	`true`	Status aktif pengaturan komisi marketplace

Enum Reference Tables

Referral Status

Nilai	Deskripsi
`signed_up`	Referee telah mendaftar menggunakan kode referral, namun belum melakukan pembelian
`purchased`	Referee telah melakukan pembelian (pertama atau perpanjangan), komisi mulai diproses

Commission Status

Nilai	Deskripsi
`unpaid`	Komisi telah tercatat namun belum dibayarkan ke saldo pengguna
`paid_to_balance`	Komisi telah dibayarkan dan ditambahkan ke `commission_balance` pengguna
`rejected`	Komisi ditolak (misal: transaksi dibatalkan atau ditemukan kecurangan)

Commission Purchase Type

Nilai	Deskripsi
`first_time`	Pembelian pertama kali oleh referee — commission rate lebih tinggi
`renewal`	Perpanjangan subscription oleh referee — commission rate lebih rendah

Withdrawal Source

Nilai	Deskripsi
`commission`	Penarikan dari `commission_balance` (komisi referral biasa)
`admin_commission`	Penarikan dari `admin_commission_balance` (komisi admin basic dari transaksi)

Withdrawal Request Status

Nilai	Deskripsi
`pending`	Permintaan penarikan menunggu review dan approval admin
`approved`	Permintaan disetujui, admin sedang atau telah mentransfer dana
`rejected`	Permintaan ditolak oleh admin (dengan catatan alasan penolakan)

ReferralCode Active Status

Nilai	Deskripsi
`true`	Kode referral aktif dan dapat digunakan oleh calon referee baru
`false`	Kode referral dinonaktifkan, tidak bisa digunakan untuk referral baru

User Role

Nilai	Deskripsi
`admin`	Administrator dengan akses penuh ke pengaturan referral dan approval withdrawal
`user`	Pengguna biasa yang dapat berpartisipasi dalam program referral

Subscription Plan

Nilai	Deskripsi
`free`	Paket gratis tanpa fitur premium
`pro`	Paket profesional dengan fitur lanjutan
`business`	Paket bisnis dengan akses fitur company
`advanced`	Paket tingkat lanjut dengan fitur lengkap
`enterprise`	Paket enterprise dengan akses tanpa batas

Subscription Status

Nilai	Deskripsi
`active`	Langganan aktif dan berjalan normal
`paused`	Langganan dijeda sementara
`cancelled`	Langganan dibatalkan

State Diagrams

Referral Status Lifecycle

Commission Status Lifecycle

Withdrawal Request Status Lifecycle

ReferralCode Lifecycle

Sequence Diagrams

Flow 1: Membuat dan Membagikan Referral Link

Flow 3: Payout / Penarikan Komisi

Code Generation Algorithm

Kode referral dihasilkan dari karakter set khusus untuk menghindari kebingungan visual:

Character set: 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
Length: 8 characters
Total kemungkinan: 34^8 = ~1.785 triliun kombinasi

Karakter yang dikecualikan: I (mirip 1), O (mirip 0) — untuk menghindari kesalahan input manual oleh referee. Implementasi pseudo-code:

const CHARSET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
const CODE_LENGTH = 8;

function generateReferralCode() {
    let code;
    do {
        code = Array.from({ length: CODE_LENGTH }, () =>
            CHARSET[Math.floor(Math.random() * CHARSET.length)]
        ).join('');
    } while (existingCodes.has(code)); // Ensure uniqueness
    return code;
}

Referral Flow Lengkap

Validation Rules

Rule	Deskripsi	Implementasi
Code format	8 karakter, uppercase, dari character set `ABCDEFGHJKLMNPQRSTUVWXYZ23456789`	Validasi di frontend saat input manual
Self-referral	User tidak bisa menggunakan kode referral miliknya sendiri	Check: `code.user_id !== current_user.id`
Double-referral	User yang sudah pernah di-referral tidak bisa di-referral lagi	Check: `Referral WHERE referee_id = current_user` tidak ada
Active check	Kode harus memiliki `is_active = true`	Query: `ReferralCode WHERE code = ref AND is_active = true`
Minimum withdrawal	Penarikan minimal sesuai `MarketplaceCommissionSettings.min_withdrawal`	Validasi di frontend dan backend
Balance check	Jumlah penarikan tidak boleh melebihi `commission_balance`	Validasi: `amount <= User.commission_balance`
Description limit	Maksimal 1000 karakter untuk field description di semua entity	Validasi maxLength di schema

Commission Structure

Sistem komisi menggunakan model tiered rate berdasarkan jenis pembelian dan plan yang dibeli:

Tipe	Rate	Deskripsi	Contoh Kalkulasi
`first_time`	`first_purchase_commission_rate` dari ReferralSetting	Komisi dari pembelian pertama referee — rate lebih tinggi untuk insentif	Plan Pro (Rp 200.000) × 50% = Rp 100.000
`renewal`	`renewal_commission_rate` dari ReferralSetting	Komisi dari perpanjangan subscription referee — rate lebih rendah	Plan Pro (Rp 200.000) × 10% = Rp 20.000

Formula komisi:

commission_amount = purchase_amount × commission_rate

Dimana commission_rate diambil dari ReferralSetting berdasarkan plan_key yang dibeli dan jenis pembelian (first_time atau renewal). Contoh konfigurasi ReferralSetting:

Plan Key	First Purchase Rate	Renewal Rate
`pro`	0.50 (50%)	0.10 (10%)
`business`	0.40 (40%)	0.08 (8%)
`advanced`	0.30 (30%)	0.05 (5%)
`enterprise`	0.25 (25%)	0.05 (5%)

Stats Dashboard

Dashboard menampilkan metrik-metrik kunci untuk memantau performa referral:

Metrik	Rumus	Sumber Data
Total Earnings	`SUM(commission.commission_amount) WHERE referrer_id = current_user`	Commission entity
Commission Balance	`User.commission_balance`	User entity
Successful Referrals	`COUNT(Referral) WHERE referrer_id = current_user AND status = 'purchased'`	Referral entity
Pending Referrals	`COUNT(Referral) WHERE referrer_id = current_user AND status = 'signed_up'`	Referral entity
My Rank	Peringkat dari `listReferralLeaderboard`	Leaderboard function
Conversion Rate	`successful / (successful + pending) × 100%`	Kalkulasi frontend

Withdrawal System

Ketentuan Penarikan

Setting	Nilai	Sumber
Minimum penarikan	Sesuai `MarketplaceCommissionSettings.min_withdrawal` (default: Rp 100.000)	MarketplaceCommissionSettings
Biaya admin	Sesuai `MarketplaceCommissionSettings.withdrawal_fee` (default: Rp 5.000)	MarketplaceCommissionSettings
Sumber dana	`commission` atau `admin_commission`	WithdrawalRequest.withdrawal_source

Proses Penarikan

Leaderboard

Leaderboard di-refresh otomatis setiap 10 detik bersamaan dengan data referral lainnya untuk memastikan peringkat selalu terkini. Algoritma ranking:

Hitung jumlah referral dengan status = 'purchased' per referrer
Urutkan secara descending (terbanyak ke tersedikit)
Assign rank berdasarkan posisi
Tampilkan dengan ikon berbeda untuk top 3

Channel	Method	Format URL
WhatsApp	Deep link WhatsApp	`whatsapp://send?text=...`
Facebook	Facebook share dialog	`https://www.facebook.com/sharer/sharer.php?u=...`
Twitter	Twitter intent URL	`https://twitter.com/intent/tweet?text=...`
LinkedIn	LinkedIn share URL	`https://www.linkedin.com/sharing/share-offsite/?url=...`
Email	Mailto link	`mailto:?subject=...&body=...`

Format referral link: {origin}?ref={code} Contoh: https://snishop.my.canva.site/?ref=AB3D5F7K

Auto-Refresh

Data referral di-refresh otomatis setiap 10 detik untuk tracking realtime. Ini mencakup:

Daftar referral (history)
Statistik dashboard (total earnings, balance, rank)
Leaderboard (peringkat terbaru)
Commission history (komisi baru yang masuk)

RBAC Permission Table

Referral Module Access

Aksi	User (role: user)	Admin (role: admin)	Keterangan
Lihat kode referral sendiri	✅	✅	Setiap user bisa melihat kode referral miliknya
Bagikan referral link	✅	✅	Semua user bisa berpartisipasi
Lihat referral history	✅	✅	Hanya referral milik sendiri
Lihat commission history	✅	✅	Hanya komisi milik sendiri (sebagai referrer atau referee)
Ajukan withdrawal	✅	✅	Selama saldo mencukupi
Lihat leaderboard	✅	✅	Semua user bisa melihat peringkat
Lihat semua referral (global)	❌	✅	Admin bisa melihat seluruh referral di sistem
Kelola ReferralSetting	❌	✅	Hanya admin yang bisa mengubah commission rate
Approve/reject withdrawal	❌	✅	Hanya admin yang bisa memproses withdrawal
Nonaktifkan referral code	❌	✅	Admin bisa menonaktifkan kode tertentu
Lihat semua commission (global)	❌	✅	Admin bisa audit seluruh komisi

RLS (Row-Level Security) — Commission Entity

Commission entity memiliki RLS rules yang lebih detail:

Operasi	Kondisi Akses
Create	User adalah referrer ATAU referee ATAU user ber-role admin
Read	User adalah referrer ATAU referee ATAU user ber-role admin
Update	User adalah referrer ATAU referee ATAU user ber-role admin
Delete	User adalah referrer ATAU referee ATAU user ber-role admin

RLS — WithdrawalRequest Entity

Operasi	Kondisi Akses
Create	User adalah pemilik request (`user_id`) ATAU email cocok ATAU user ber-role admin
Read	User adalah pemilik request ATAU email cocok ATAU user ber-role admin
Update	User adalah pemilik request ATAU email cocok ATAU user ber-role admin
Delete	User adalah pemilik request ATAU email cocok ATAU user ber-role admin

ReferralCodeModal (260 baris)

Modal yang muncul saat user signup dengan referral code: Detail validasi di ReferralCodeModal:

Format check — Kode harus 8 karakter uppercase dari character set yang valid
Active check — Query ReferralCode untuk memastikan is_active = true
Self-referral check — Pastikan code.user_id !== current_user.id
Double-referral check — Pastikan belum ada Referral dengan referee_id = current_user.id
Existence check — Pastikan kode benar-benar ada di database

Integrasi dengan Entity Lain

PricingPlan

Setiap plan dalam PricingPlan dapat memiliki konfigurasi commission rate yang berbeda melalui ReferralSetting. Plan yang tersedia:

Plan Key	Nama	Deskripsi
`free`	Free	Paket gratis — tidak ada komisi referral
`pro`	Pro	Paket profesional
`business`	Business	Paket bisnis
`advanced`	Advanced	Paket tingkat lanjut
`enterprise`	Enterprise	Paket enterprise

Subscription

Ketika referee membeli subscription, sistem akan:

Lookup Referral untuk menemukan referrer
Lookup ReferralSetting berdasarkan plan_key subscription
Tentukan purchase_type (first_time atau renewal)
Hitung commission_amount berdasarkan rate
Create record Commission dengan status unpaid
Update Referral.status menjadi purchased

ProductOrder

Untuk produk digital, ProductOrder memiliki field product_commission_rate yang menyimpan commission rate saat order dibuat, serta admin_commission_amount untuk komisi admin basic.

Cara Akses

Dari sidebar, klik menu Marketing > Referral. Memerlukan user yang sudah login.

Flow Penggunaan

Buka halaman Referral dari sidebar — lihat kode referral unik kamu di atas halaman
Bagikan kode referral melalui WhatsApp, Facebook, Twitter, LinkedIn, atau Email — link berformat {origin}?ref={code}
Orang yang mendaftar menggunakan kode kamu otomatis tercatat sebagai referral dengan status signed_up
Saat referral melakukan pembelian pertama, status berubah ke purchased dan komisi dihitung berdasarkan ReferralSetting
Pantau stats dashboard untuk melihat total earnings, successful referrals, dan rank di leaderboard
Tarik saldo komisi jika sudah mencapai minimum withdrawal yang ditentukan di MarketplaceCommissionSettings

Tips

Optimalkan commission rate — Buat rate yang menarik tapi tetap menguntungkan secara bisnis. Commission rate yang terlalu kecil tidak memotivasi referrer untuk aktif berbagi
Promosikan program referral secara aktif di semua channel — banyak customer tidak tahu program ini ada. Manfaatkan email marketing dan notifikasi in-app
Manfaatkan leaderboard untuk gamifikasi — ranking mendorong kompetisi sehat antar referrer. Pertimbangkan reward tambahan untuk top referrer bulanan
Evaluasi program secara berkala — sesuaikan rate jika perlu berdasarkan ROI. Analisis conversion rate dari signed_up ke purchased untuk mengukur efektivitas
Monitor withdrawal requests secara rutin — proses penarikan dengan cepat untuk menjaga kepercayaan peserta program
Gunakan description field di ReferralCode untuk membuat pesan promosi yang menarik saat membagikan kode
Pastikan minimum withdrawal masuk akal — terlalu tinggi akan mengecilkan partisipasi, terlalu rendah akan membebani operasional

Troubleshooting

Masalah	Kemungkinan Penyebab	Solusi
Kode referral tidak bisa digunakan	Kode sudah dinonaktifkan (`is_active = false`)	Admin perlu mengaktifkan kembali kode
Komisi tidak masuk setelah pembelian	Referral status masih `signed_up`	Pastikan referee telah menyelesaikan pembelian
Withdrawal ditolak	Saldo tidak mencukupi atau data rekening tidak valid	Periksa saldo dan lengkapi data rekening bank
Self-referral error	User mencoba menggunakan kode sendiri	Gunakan kode referral dari user lain
Double-referral error	User sudah pernah di-referral sebelumnya	Satu user hanya bisa di-referral satu kali
Link referral tidak berfungsi	Parameter `ref` tidak ada di URL	Pastikan format link: `{origin}?ref={code}`

​title: “Referral” description: “Program referral dengan code generation, commission tracking, leaderboard, multi-channel sharing, dan withdrawal system di SNISHOP ERP.”

​Referral

​Arsitektur Komponen

​Ringkasan Modul

​Entity Relationship Diagram

​Entity Schema Tables

​User (Referral Fields)

​Referral

​ReferralCode

​Commission

​ReferralSetting

​WithdrawalRequest

​MarketplaceCommissionSettings

​Enum Reference Tables

​Referral Status

​Commission Status

​Commission Purchase Type

​Withdrawal Source

​Withdrawal Request Status

​ReferralCode Active Status

​User Role

​Subscription Plan

​Subscription Status

​State Diagrams

​Referral Status Lifecycle

​Commission Status Lifecycle

​Withdrawal Request Status Lifecycle

​ReferralCode Lifecycle

​Sequence Diagrams

​Flow 1: Membuat dan Membagikan Referral Link

​Flow 2: Tracking Konversi Referral (Signup → Purchase)

​Flow 3: Payout / Penarikan Komisi

​Code Generation Algorithm

​Referral Flow Lengkap

​Validation Rules

​Commission Structure

​Stats Dashboard

​Withdrawal System

​Ketentuan Penarikan

​Proses Penarikan

​Leaderboard

​5 Share Channels

​Auto-Refresh

​RBAC Permission Table

​Referral Module Access

​RLS (Row-Level Security) — Commission Entity

​RLS — WithdrawalRequest Entity

​ReferralCodeModal (260 baris)

​Integrasi dengan Entity Lain

​PricingPlan

​Subscription

​ProductOrder

​Cara Akses

​Flow Penggunaan

​Tips

​Troubleshooting

title: “Referral” description: “Program referral dengan code generation, commission tracking, leaderboard, multi-channel sharing, dan withdrawal system di SNISHOP ERP.”

Referral

Arsitektur Komponen

Ringkasan Modul

Entity Relationship Diagram

Entity Schema Tables

User (Referral Fields)

Referral

ReferralCode

Commission

ReferralSetting

WithdrawalRequest

MarketplaceCommissionSettings

Enum Reference Tables

Referral Status

Commission Status

Commission Purchase Type

Withdrawal Source

Withdrawal Request Status

ReferralCode Active Status

User Role

Subscription Plan

Subscription Status

State Diagrams

Referral Status Lifecycle

Commission Status Lifecycle

Withdrawal Request Status Lifecycle

ReferralCode Lifecycle

Sequence Diagrams

Flow 1: Membuat dan Membagikan Referral Link

Flow 2: Tracking Konversi Referral (Signup → Purchase)

Flow 3: Payout / Penarikan Komisi

Code Generation Algorithm

Referral Flow Lengkap

Validation Rules

Commission Structure

Stats Dashboard

Withdrawal System

Ketentuan Penarikan

Proses Penarikan

Leaderboard

5 Share Channels

Auto-Refresh

RBAC Permission Table

Referral Module Access

RLS (Row-Level Security) — Commission Entity

RLS — WithdrawalRequest Entity

ReferralCodeModal (260 baris)

Integrasi dengan Entity Lain

PricingPlan

Subscription

ProductOrder

Cara Akses

Flow Penggunaan

Tips

Troubleshooting