title: “Customer Membership — Status Membership Pelanggan” description: “Tampilan customer-facing untuk status membership: tier saat ini, progress bar upgrade, benefit aktif, riwayat poin dari CustomerLoyaltyLedger, dan integrasi real-time dengan POS.”

Customer Membership — Status Membership Pelanggan

Halaman Customer Membership adalah tampilan customer-facing yang menunjukkan status loyalty pelanggan berdasarkan data Customer (40+ fields) dan CustomerMembership (tier definition). Pelanggan bisa melihat tier mereka saat ini, progress menuju tier berikutnya dengan progress bar visual, benefit yang aktif, dan riwayat lengkap perolehan serta penggunaan poin dari CustomerLoyaltyLedger. Halaman ini tidak memiliki komponen React terpisah yang besar — ia mengkomposisikan data dari beberapa entitas dan menampilkannya dalam format yang mudah dipahami pelanggan.

Entity Relationship Diagram

Penjelasan Relasi

Relasi	Kardinalitas	Deskripsi
`Customer` → `CustomerMembership`	Many-to-One	Banyak pelanggan bisa berada pada tier yang sama. Field `membership_level_id` di `Customer` merujuk ke `id` di `CustomerMembership`.
`Customer` → `CustomerLoyaltyLedger`	One-to-Many	Satu pelanggan memiliki banyak entri ledger (setiap kali earn, redeem, atau adjust).
`Customer` → `CompanyPOSTransaction`	One-to-Many	Satu pelanggan memiliki banyak transaksi POS.
`CompanyPOSTransaction` → `CustomerLoyaltyLedger`	One-to-Many	Satu transaksi POS bisa memicu satu atau lebih entri ledger (misal: earn + tier_upgrade sekaligus).

Arsitektur Data

Entity Schema — CustomerMembership (Detail Lengkap)

Entitas CustomerMembership mendefinisikan seluruh konfigurasi tier loyalty — mulai dari skema perolehan, ambang batas, hingga jenis reward yang tersedia. Setiap perusahaan (company_id) bisa memiliki beberapa tier yang diurutkan berdasarkan field order.

Field Identitas & Visual

Field	Tipe	Default	Wajib	Deskripsi
`id`	UUID	auto	Ya	Primary key unik untuk setiap tier
`company_id`	UUID	—	Ya	Foreign key ke perusahaan pemilik program loyalty
`level_name`	String	—	Ya	Nama tampilan tier, contoh: “Silver”, “Gold”, “Platinum”, “Diamond”
`level_key`	String	—	Ya	Key unik untuk referensi programatis (contoh: `silver`, `gold`, `platinum`). Bersifat unique per company.
`icon`	String	—	Tidak	Emoji ikon tier (contoh: 🥉🥈🥇💎)
`color`	String	—	Tidak	Kode warna hex untuk badge tier (contoh: `#FFD700`)
`description`	String	—	Tidak	Penjelasan lengkap mengenai keuntungan dan syarat keanggotaan pada level ini (maks. 1000 karakter)
`order`	Number	`0`	Tidak	Urutan level dalam hierarki — semakin tinggi nilainya, semakin premium tier tersebut
`is_active`	Boolean	`true`	Tidak	Status aktif tier. Tier non-aktif tidak bisa dijadikan tier baru pelanggan, tetapi pelanggan yang sudah berada di tier ini tetap mempertahankannya.

Field Skema Loyalty (Scheme Configuration)

Field	Tipe	Default	Deskripsi
`scheme_type`	Enum	`"points"`	Skema loyalty yang berlaku pada tier ini. Pilihan: `points`, `stamp`, `spending`, `visits`, `hybrid`
`points_threshold`	Number	`10000`	Ambang batas belanja untuk memperoleh poin (dalam Rupiah). Contoh: Rp 10.000 = setiap kelipatan Rp 10.000 dapat poin.
`points_per_threshold`	Number	`1`	Jumlah poin yang diperoleh per threshold tercapai.
`stamps_required`	Number	`10`	Jumlah stamp yang dibutuhkan untuk reward atau naik level.
`stamp_per_transaction`	Number	`1`	Jumlah stamp yang diperoleh per transaksi eligible.
`min_purchase`	Number	`0`	Minimum total pembelian (lifetime_value) untuk mencapai tier ini. Digunakan sebagai kriteria auto-upgrade.

Field Reward System

Field	Tipe	Default	Deskripsi
`reward_type`	Enum	`"none"`	Jenis reward yang dapat ditukarkan: `none`, `discount_percentage`, `discount_amount`, `free_product`
`reward_value`	Number	`0`	Nilai reward — bisa berupa persentase diskon (jika `reward_type=discount_percentage`) atau nominal Rupiah (jika `discount_amount`)
`reward_product_id`	UUID	—	ID produk yang diberikan gratis jika `reward_type=free_product`
`reward_product_name`	String	—	Nama produk reward gratis (untuk tampilan)
`min_redemption_points`	Number	`0`	Minimal poin yang harus dimiliki pelanggan sebelum bisa melakukan penukaran reward
`expiry_days`	Number	—	Masa kedaluwarsa poin dalam hari. Jika diisi, poin yang tidak digunakan akan hangus setelah N hari.

Field Benefit & Privilege

Field	Tipe	Default	Deskripsi
`discount_percentage`	Number	`0`	Persentase diskon otomatis (0-100) yang diterapkan saat transaksi POS
`points_multiplier`	Number	`1`	Multiplier perolehan poin. `1` = normal, `1.5` = 1.5x, `2` = double points
`free_delivery`	Boolean	`false`	Apakah tier ini mendapat gratis ongkir
`priority_support`	Boolean	`false`	Akses prioritas ke support via WhatsApp dedicated
`birthday_bonus`	Number	`0`	Jumlah poin bonus yang diberikan di hari ulang tahun pelanggan
`benefits`	Array[String]	`[]`	Daftar benefit kustom (teks bebas) yang ditampilkan ke pelanggan

Contoh Konfigurasi Tier Lengkap

{
  "level_name": "Gold",
  "level_key": "gold",
  "icon": "🥇",
  "color": "#FFD700",
  "scheme_type": "points",
  "order": 2,
  "min_purchase": 5000000,
  "discount_percentage": 10,
  "points_multiplier": 1.5,
  "points_threshold": 10000,
  "points_per_threshold": 1,
  "min_redemption_points": 500,
  "reward_type": "discount_amount",
  "reward_value": 50000,
  "free_delivery": true,
  "priority_support": true,
  "birthday_bonus": 200,
  "benefits": ["Akses menu eksklusif", "Undangan event khusus member"],
  "expiry_days": 365,
  "is_active": true
}

Entity Schema — CustomerLoyaltyLedger (Detail Lengkap)

Entitas CustomerLoyaltyLedger adalah buku besar (ledger) mutasi loyalty yang mencatat setiap perubahan poin dan stamp pelanggan. Setiap baris merepresentasikan satu event loyalty dengan snapshot saldo sebelum dan sesudahnya, sehingga memungkinkan audit trail lengkap.

Field Identitas & Referensi

Field	Tipe	Wajib	Deskripsi
`id`	UUID	Ya	Primary key entri ledger
`company_id`	UUID	Ya	Foreign key ke perusahaan
`customer_id`	UUID	Ya	Foreign key ke `Customer` — pemilik transaksi loyalty
`customer_name`	String	Tidak	Nama customer saat transaksi (denormalized untuk performa reporting)
`customer_phone`	String	Tidak	Nomor telepon customer saat transaksi (denormalized)
`transaction_id`	UUID	Tidak	Referensi ke `CompanyPOSTransaction.id` — transaksi POS yang memicu event
`transaction_number`	String	Tidak	Nomor struk / receipt number (denormalized dari transaksi POS)
`idempotency_key`	UUID	Ya	Key unik untuk mencegah double crediting / double posting. Jika event yang sama dikirim dua kali (misal retry network), hanya satu yang diproses.

Field Event & Skema

Field	Tipe	Default	Deskripsi
`event_type`	Enum	—	Tipe event mutasi loyalty (lihat tabel enum di bawah)
`scheme_type`	Enum	`"points"`	Skema loyalty yang berlaku saat event ini terjadi

Enum event_type:

Nilai	Deskripsi	Kapan Terjadi
`earn`	Perolehan poin/stamp dari transaksi	Setelah transaksi POS selesai dan terverifikasi
`redeem`	Penukaran poin/stamp untuk reward	Pelanggan menukarkan poin untuk diskon atau produk gratis
`return_reversal`	Pembatalan poin akibat retur/void	Transaksi asli di-void atau diretur setelah poin sudah dicatat
`tier_upgrade`	Pencatatan perubahan tier	Pelanggan naik atau turun tier
`manual_adjustment`	Penyesuaian manual oleh admin	Admin/operator mengoreksi poin secara manual (misal: komplain pelanggan)

Field Snapshot Saldo (Points)

Field	Tipe	Default	Deskripsi
`points_delta`	Number	`0`	Perubahan poin: positif (+) untuk earn, negatif (-) untuk redeem/reversal
`points_before`	Number	`0`	Saldo poin sebelum event ini diproses
`points_after`	Number	`0`	Saldo poin setelah event ini diproses. Harus konsisten: `points_after = points_before + points_delta`

Field Snapshot Saldo (Stamps)

Field	Tipe	Default	Deskripsi
`stamps_delta`	Number	`0`	Perubahan stamp: positif (+) untuk earn, negatif (-) untuk redeem
`stamps_before`	Number	`0`	Saldo stamp sebelum event
`stamps_after`	Number	`0`	Saldo stamp setelah event

Field Transaksi & Audit

Field	Tipe	Default	Deskripsi
`eligible_amount`	Number	`0`	Nilai transaksi yang sah (eligible) untuk perhitungan poin. Bisa berbeda dari total transaksi jika ada produk yang tidak termasuk program loyalty.
`reason`	String	—	Alasan atau keterangan mutasi (contoh: “Earned from INV-20260110-0042”, “Manual adjustment — komplain poin hilang”)
`deficit_points`	Number	`0`	Defisit poin yang terjadi jika poin sudah terpakai (redeem) sebelum transaksi asli di-void. Jika > 0, berarti pelanggan memiliki “utang poin”.
`requires_manual_review`	Boolean	`false`	Flag yang di-set `true` jika transaksi reversal menghasilkan saldo negatif dan butuh review manual oleh admin.
`reward_details`	Object	—	Detail reward jika event adalah `redeem` (lihat sub-table di bawah)
`performed_by`	String	—	Email atau ID operator yang memproses event ini
`actor_role`	String	—	Role aktor: `owner`, `admin`, `cashier`
`finance_record_id`	UUID	—	ID `FinancialRecord` yang terhubung — diisi saat event redeem mem-posting biaya reward (COGS) ke modul keuangan
`created_at`	DateTime	auto	Waktu event tercatat di server

Sub-field reward_details:

Sub-field	Tipe	Deskripsi
`reward_type`	String	Jenis reward yang ditukarkan
`discount_amount`	Number	Nominal diskon yang diberikan
`discount_percentage`	Number	Persentase diskon yang diberikan
`product_id`	UUID	ID produk gratis (jika `reward_type=free_product`)
`product_name`	String	Nama produk gratis
`cost_points`	Number	Jumlah poin yang diperlukan untuk reward ini
`cost_stamps`	Number	Jumlah stamp yang diperlukan untuk reward ini

State Machine — Tier Progression

Aturan Transisi Tier

Transisi	Trigger	Kondisi
No Tier → Silver	Transaksi POS pertama yang eligible	`lifetime_value >= Silver.min_purchase` ATAU `membership_points >= Silver.points_threshold` ATAU `stamps >= Silver.stamps_required`
Silver → Gold	Akumulasi belanja/poin	`lifetime_value >= Gold.min_purchase` ATAU `membership_points >= Gold.points_threshold`
Gold → Platinum	Akumulasi belanja/poin	`lifetime_value >= Platinum.min_purchase` ATAU `membership_points >= Platinum.points_threshold`
Platinum → Diamond	Akumulasi belanja/poin	`lifetime_value >= Diamond.min_purchase` ATAU `membership_points >= Diamond.points_threshold`
Downgrade (misal Gold → Silver)	Review manual admin	Admin melakukan downgrade berdasarkan `loyalty_review_notes` dan evaluasi kebijakan
Upgrade dicatat	Setiap transisi tier	Buat entri `CustomerLoyaltyLedger` dengan `event_type=tier_upgrade`, update `Customer.last_tier_upgrade_date`, `last_tier_upgrade_reason`, `last_tier_upgrade_by`

Penanganan Loyalty Deficit

Ketika transaksi di-void setelah poin dari transaksi tersebut sudah terpakai (diredeem), sistem mencatat defisit:

Perbandingan Skema Loyalty

Sistem SNISHOP ERP mendukung 5 jenis skema loyalty yang dikonfigurasi per tier melalui field scheme_type di CustomerMembership. Setiap skema memiliki karakteristik, formula perolehan, dan kasus penggunaan yang berbeda.

Aspek	Points	Stamp	Spending	Visits	Hybrid
Konsep	Kumpulkan poin dari belanja	Kumpulkan stempel per transaksi	Akumulasi nominal belanja	Hitung frekuensi kunjungan	Kombinasi beberapa skema
Field utama	`points_threshold`, `points_per_threshold`	`stamps_required`, `stamp_per_transaction`	`min_purchase`	`min_purchase` (sebagai visit count proxy)	Semua field di atas
Formula earn	`floor(eligible_amount / points_threshold) × points_per_threshold × points_multiplier`	`stamp_per_transaction` per transaksi eligible	Langsung tambah `eligible_amount` ke `lifetime_value`	+1 per transaksi	Gabungan semua
Formula progress	`membership_points / next_tier.points_threshold × 100%`	`stamps / next_tier.stamps_required × 100%`	`lifetime_value / next_tier.min_purchase × 100%`	`total_orders / next_tier.min_purchase × 100%`	`max(all_progress)`
Cocok untuk	Restoran casual, F&B umum	Coffee shop, warung, bakery	Fine dining, restoran premium	Salon, barbershop, laundry	Enterprise F&B multi-konsep
Keuntungan	Fleksibel, mudah dipahami	Sederhana, visual (seperti kartu stempel)	Mendorong spending lebih tinggi	Mendorong frekuensi kunjungan	Komprehensif, adil
Kelemahan	Perlu hitung konversi poin	Tidak membedakan nominal belanja	Tidak mendorong frekuensi	Tidak membedakan nominal	Kompleks, perlu monitoring lebih
Contoh	Belanja Rp 10.000 = 1 poin	Setiap beli kopi = 1 stamp, 10 stamp = free coffee	Belanja Rp 5jt = Silver, Rp 15jt = Gold	10 kunjungan = Silver, 25 = Gold	Gabungan poin + visit count

Formula Perhitungan Poin per Skema

# Skema Points
earned_points = floor(eligible_amount / points_threshold) × points_per_threshold × points_multiplier

# Contoh: Belanja Rp 85.000, threshold Rp 10.000, per_threshold 1 poin, multiplier 1.5x
earned_points = floor(85000 / 10000) × 1 × 1.5 = 8 × 1.5 = 12 poin

# Skema Stamp
earned_stamps = stamp_per_transaction (jika eligible_amount > 0)

# Skema Spending
# Tidak ada poin/stamp — langsung akumulasi ke lifetime_value
# Progress = lifetime_value / next_tier.min_purchase × 100%

# Skema Visits
visit_count += 1 (per transaksi eligible)
# Progress = visit_count / next_tier.min_purchase × 100%

# Skema Hybrid
# Hitung semua skema di atas, progress = max(all_percentages)

Sequence Diagram — Loyalty Point Earn Flow

Sequence Diagram — Loyalty Point Redeem Flow

Sequence Diagram — Return/Reversal Flow

Akses Halaman

Metode	Detail
URL	`/customer-membership`
Sidebar	Menu CRM → Customer Membership
Customer Portal	Via self-service dashboard

Informasi yang Ditampilkan

Status Tier Saat Ini

Info	Sumber Data	Format
Nama Tier	`Customer.membership_level_name`	Text (contoh: “Gold”)
Ikon Tier	`CustomerMembership.icon`	Emoji (🥉🥈🥇💎)
Warna Badge	`CustomerMembership.color`	Hex (#FFD700)
Sejak	`Customer.membership_since`	Date (15 Mar 2025)
Poin Saat Ini	`Customer.membership_points`	Number (2.450)
Lifetime Points	`Customer.lifetime_points`	Number (total pernah dikumpulkan)
Total Belanja	`Customer.lifetime_value`	Rupiah (Rp 7.250.000)

Progress Upgrade

Formula progress per skema:

Skema	Formula	Contoh
spending	`lifetime_value / next_tier.min_purchase × 100%`	7.25jt / 15jt = 48.3%
stamp	`stamps / next_tier.stamps_required × 100%`	7 / 10 = 70%
points	`membership_points / next_tier.points_required × 100%`	2450 / 5000 = 49%
visits	`visit_count / next_tier.visits_required × 100%`	15 / 20 = 75%
hybrid	`max(all_progress_percentages)`	Max dari semua skema

Benefit Aktif

Benefit	Indikator	Sumber
Discount %	✓ 10%	`CustomerMembership.discount_percentage`
Points Multiplier	✓ 1.5x	`CustomerMembership.points_multiplier`
Free Delivery	✓ Aktif	`CustomerMembership.free_delivery`
Priority Support	✓ Aktif	`CustomerMembership.priority_support`
Birthday Bonus	✓ Aktif	`CustomerMembership.birthday_bonus`
Custom Benefits	Daftar kustom	`CustomerMembership.benefits[]`

Riwayat Poin — CustomerLoyaltyLedger

Field	Tipe	Deskripsi
`customer_id`	UUID	Reference ke Customer
`event_type`	Enum	`earn` / `redeem` / `return_reversal` / `tier_upgrade` / `manual_adjustment`
`scheme_type`	Enum	`points` / `stamp` / `spending` / `visits` / `hybrid`
`points_delta`	Number	+50 (earn) atau -100 (redeem)
`points_before`	Number	Saldo poin sebelum event (audit trail)
`points_after`	Number	Saldo poin setelah event (audit trail)
`stamps_delta`	Number	+1 (earn stamp) atau -10 (redeem stamp)
`stamps_before`	Number	Saldo stamp sebelum event
`stamps_after`	Number	Saldo stamp setelah event
`eligible_amount`	Number	Nilai transaksi yang sah untuk perhitungan poin
`transaction_id`	UUID	Link ke CompanyPOSTransaction
`transaction_number`	String	Nomor struk / receipt number
`idempotency_key`	UUID	Pencegah double-posting
`reward_details`	Object	Detail reward jika event_type = redeem
`deficit_points`	Number	Defisit jika void setelah poin terpakai
`requires_manual_review`	Boolean	Flag butuh review admin
`performed_by`	String	Operator yang memproses
`actor_role`	String	Role: owner, admin, cashier
`finance_record_id`	UUID	Link ke FinancialRecord (COGS reward)
`reason`	String	Deskripsi/alasan mutasi
`created_at`	DateTime	Waktu pencatatan

Integrasi dengan POS

Alur Data Integrasi POS → CRM

Perbedaan dengan Company Membership

Aspek	Company Membership	Customer Membership
Scope	Konfigurasi tier (admin)	Status pelanggan (customer-facing)
Komponen	`MembershipLevelManager` — 821 baris	Composited view
User	Admin/Owner	Pelanggan / Kasir (lookup)
Fungsi	Setup program loyalty	Lihat status dan progress
Data	`CustomerMembership` entity (definition)	`Customer` + `CustomerMembership` (instance)
URL	`/company-membership`	`/customer-membership`
Akses	Admin only (RLS)	Customer-scoped
Write	CRUD tier definitions	Read-only (data derived from transactions)

Entitas Terkait

Entitas	Peran	Fields Relevan
`Customer`	Data pelanggan (tier, poin, LTV)	`membership_level_id`, `membership_points`, `lifetime_value`, `membership_since`, `stamps`, `lifetime_points`, `has_negative_points`, `loyalty_deficit_points`, `last_tier_upgrade_date`
`CustomerMembership`	Definisi tier dan benefit	`level_name`, `level_key`, `scheme_type`, `discount_percentage`, `points_multiplier`, `min_purchase`, `points_threshold`, `points_per_threshold`, `stamps_required`, `stamp_per_transaction`, `reward_type`, `reward_value`, `min_redemption_points`, `expiry_days`, `free_delivery`, `priority_support`, `birthday_bonus`, `benefits`
`CustomerLoyaltyLedger`	Riwayat transaksi poin/stamp	`event_type`, `scheme_type`, `points_delta`, `points_before`, `points_after`, `stamps_delta`, `eligible_amount`, `transaction_id`, `reward_details`, `deficit_points`, `requires_manual_review`, `idempotency_key`, `performed_by`, `finance_record_id`
`CompanyPOSTransaction`	Sumber transaksi yang trigger loyalty	`total_amount`, `member_id`, `payment_status`, `transaction_number`, `transaction_date`
`POSMember`	Data member di konteks POS (mirror Customer untuk loyalty)	`membership_tier`, `points`, `stamps`, `total_spent`, `visit_count`, `discount_percentage`, `has_negative_points`, `loyalty_deficit_points`

Tips

Progress bar adalah motivator utama — pastikan pelanggan selalu bisa melihat seberapa dekat mereka ke tier berikutnya
Riwayat poin memberikan transparansi — pelanggan bisa verifikasi setiap earn dan redeem
Birthday bonus meningkatkan engagement — pastikan Customer.birthday diisi saat registrasi
Export riwayat poin berguna untuk customer service saat ada komplain tentang poin yang hilang
Integrasi POS → CRM harus real-time — pelanggan yang baru transaksi harus langsung lihat poin bertambah
Idempotency key mencegah double-credit saat ada retry network — setiap event loyalty memiliki key unik
Loyalty deficit perlu ditangani segera — flag requires_manual_review di ledger menandai transaksi yang butuh rekonsiliasi admin
Skema hybrid memberikan fleksibilitas tertinggi tetapi memerlukan monitoring lebih — pastikan semua sub-skema terkonfigurasi dengan benar
Audit trail di CustomerLoyaltyLedger (points_before, points_after) memungkinkan rekonstruksi penuh riwayat loyalty pelanggan kapan saja
Finance integration — setiap redeem yang menghasilkan reward tercatat di FinancialRecord melalui finance_record_id, memastikan COGS reward terakuntansi dengan benar

​title: “Customer Membership — Status Membership Pelanggan” description: “Tampilan customer-facing untuk status membership: tier saat ini, progress bar upgrade, benefit aktif, riwayat poin dari CustomerLoyaltyLedger, dan integrasi real-time dengan POS.”

​Customer Membership — Status Membership Pelanggan

​Entity Relationship Diagram

​Penjelasan Relasi

​Arsitektur Data

​Entity Schema — CustomerMembership (Detail Lengkap)

​Field Identitas & Visual

​Field Skema Loyalty (Scheme Configuration)

​Field Reward System

​Field Benefit & Privilege

​Contoh Konfigurasi Tier Lengkap

​Entity Schema — CustomerLoyaltyLedger (Detail Lengkap)

​Field Identitas & Referensi

​Field Event & Skema

​Field Snapshot Saldo (Points)

​Field Snapshot Saldo (Stamps)

​Field Transaksi & Audit

​State Machine — Tier Progression

​Aturan Transisi Tier

​Penanganan Loyalty Deficit

​Perbandingan Skema Loyalty

​Formula Perhitungan Poin per Skema

​Sequence Diagram — Loyalty Point Earn Flow

​Sequence Diagram — Loyalty Point Redeem Flow

​Sequence Diagram — Return/Reversal Flow

​Akses Halaman

​Informasi yang Ditampilkan

​Status Tier Saat Ini

​Progress Upgrade

​Benefit Aktif

​Riwayat Poin — CustomerLoyaltyLedger

​Integrasi dengan POS

​Alur Data Integrasi POS → CRM

​Perbedaan dengan Company Membership

​Entitas Terkait

​Tips