Mesin Poin Loyalty Terintegrasi ESB

Mesin poin loyalty customer yang diintegrasikan ke ESB ERP pihak ketiga, lengkap dengan portal konsumen, ledger append-only, dan manajemen kadaluarsa poin berbasis FIFO.

Java 25
Spring Boot 4.1
PostgreSQL
Flyway
Spring Security

Klien: Kafe, Jakarta Timur
Tahun: 2026
Peran: Backend Engineer — arsitektur, domain, integrasi ESB, dan portal konsumen

Masalah

ESB ERP pihak ketiga membutuhkan mitra yang menyediakan endpoint poin loyalty sesuai kontrak mereka — ESB yang memanggil, bukan sebaliknya. Sistem penerima ini harus mengelola saldo poin secara akurat, tahan pemanggilan ulang, dan siap diaudit, sambil sepenuhnya tunduk pada spesifikasi integrasi yang sudah ditetapkan pihak ESB — dan sekaligus memberi konsumen akhir cara mandiri untuk memeriksa poin mereka.

Pendekatan

Dibangun dengan arsitektur berlapis (domain bebas framework, lalu application, lalu infrastructure) sehingga aturan poin bisa diuji tanpa menyalakan aplikasi. Ledger poin bersifat append-only — poin tidak pernah diubah langsung, koreksi dilakukan lewat entry pembalik (reversal) yang menunjuk transaksi asal. Setiap perubahan poin membawa kunci idempotensi supaya pemanggilan ulang dari ESB tidak pernah menggandakan poin. Portal konsumen dibangun terpisah total dari dashboard staf, sampai ke kerangka halamannya.

Hasil

Earning (poin dari transaksi), reversal (pembatalan saat transaksi di-void), dan burn (pemakaian poin) sudah berjalan dan sesuai spesifikasi ESB
Portal konsumen aktif — pelanggan bisa masuk sendiri untuk melihat saldo poin dan riwayat transaksinya
Skema kadaluarsa poin per-lot dengan algoritma FIFO sudah dirancang di lapisan domain
Login staf backoffice dilengkapi verifikasi dua langkah (OTP) dan proteksi terhadap percobaan login bertubi-tubi

Konteks integrasi

Sistem ini adalah mesin poin loyalty customer untuk sebuah kafe di Jakarta Timur, berperan sebagai penerima, bukan pemrakarsa: ESB ERP pihak ketiga yang memanggil sistem ini setiap kali ada transaksi, penukaran poin (disebut coin dalam istilah ESB), atau pengecekan saldo — bukan sebaliknya. Konsekuensinya, tidak ada proses sinkronisasi keluar atau antrean pengiriman data; setiap saldo selalu dihitung real-time saat diminta.

Karena posisinya sebagai penerima panggilan pihak ketiga, sistem ini sepenuhnya tunduk pada spesifikasi kontrak yang ditetapkan ESB — termasuk aturan yang secara desain umum terasa tidak lazim (misalnya kode status HTTP tertentu untuk kasus validasi), tapi tetap diikuti karena itu bagian dari kontrak integrasi.

Di sisi lain, konsumen akhir butuh cara sendiri untuk melihat poinnya tanpa bertanya ke kasir — karena itu dibangun juga portal konsumen yang terpisah total dari dashboard staf.

Prinsip desain yang ditegakkan

Ledger append-only. Poin tidak pernah di-update langsung. Setiap perubahan adalah baris baru; koreksi memakai entry pembalik (reversal) yang menunjuk transaksi asal, sehingga riwayat penuh selalu bisa ditelusuri.
Idempotensi di titik masuk. Setiap perubahan poin membawa kunci unik. Kalau ESB memanggil ulang permintaan yang sama, hasilnya tetap sama — tidak ada poin dobel.
Domain bebas dari framework. Aturan perhitungan poin ditulis sebagai Java murni, tanpa bergantung pada Spring atau database, sehingga bisa diuji secara terisolasi.
Aturan poin adalah data, bukan kode. Persentase perolehan poin, basis perhitungan, periode berlaku, dan cakupan per outlet disimpan di tabel aturan — menambah skema poin baru tidak berarti mengubah alur inti.
Saldo tidak pernah negatif. Kalau pembalikan poin melebihi saldo yang tersedia, sistem menarik sebatas yang ada dan mencatat kekurangannya — permintaan ESB tidak pernah digagalkan begitu saja, karena ESB akan terus mencoba ulang.

Modul yang dibangun

Mesin poin (loyalty) — perhitungan perolehan poin, pembalikan saat transaksi dibatalkan, pemakaian poin, dan pencarian data member, seluruhnya di balik kontrak API sesuai spesifikasi ESB.
Portal konsumen — beranda dan halaman program bisa diakses tanpa masuk (agar calon anggota bisa membaca programnya lebih dulu), sementara profil dan pengaturan akun memerlukan login dan menampilkan saldo poin beserta riwayat transaksi milik konsumen sendiri.
Manajemen akses staf (iam) — autentikasi untuk dashboard internal, dilengkapi verifikasi dua langkah (OTP), pembatasan berdasarkan IP/jam kerja, dan penguncian otomatis setelah percobaan login yang gagal berulang.
Fondasi bersama (shared) — konfigurasi keamanan, audit otomatis setiap perubahan data, dan penanganan galat terstandar di seluruh sistem.

Status pengerjaan

Sistem sudah selesai dan berjalan untuk klien. Sebagai produk yang dipakai aktif, pengembangan berikutnya mengikuti permintaan penambahan fitur dari klien dari waktu ke waktu.