Dokumentasi Sistem
Annual Pass

1Ikhtisar

Annual Pass adalah sistem keanggotaan tahunan Taman Safari: satu pembelian, kunjungan sepuasnya selama 12 bulan, plus diskon F&B dan wahana. Terdiri atas portal pelanggan, CMS admin, dan API yang menghubungkan ke DOKU (pembayaran), ESB (POS F&B), GlobalTix (tiket), NetSuite (akuntansi), dan aplikasi Taman Safari (login).

Alamat

Alur singkat

1. Pelanggan beli Annual Pass di portal, bayar lewat DOKU (VA/QRIS/kartu).
2. Setelah lunas, Annual Pass aktif dan setiap anggota keluarga dapat Member ID sendiri.
3. Sebelum berkunjung, pelanggan membuat reservasi tanggal, lalu konfirmasi (H-1 atau hari-H) → terbit QR Masuk.
4. Di gerbang, petugas memindai QR Masuk; di kasir F&B/wahana, pelanggan menunjukkan QR Member ID untuk diskon.
5. Transaksi F&B dari ESB masuk ke sistem; laporan terlihat di CMS.

2Istilah

3Beli Annual Pass Pengguna

Dari portal pelanggan. Bisa tanpa daftar lebih dulu; akun terbentuk otomatis saat pembelian, atau login dulu lewat email/HP, Google, atau Apple.

Langkah

1. Buka portal → Lihat Paket / Pilih Pass.
2. Pilih taman: Satu Taman (Bogor/Prigen/Batang/Bali) atau Multi Taman (satu pass untuk beberapa taman).
3. Untuk siapa: Student, Couple, Family, dll.
4. Pilih paket → halaman checkout: data pemegang, anggota keluarga, metode bayar.
5. Setujui syarat → bayar.

Paket keluarga dewasa/anak

Paket Family bisa berisi komposisi, misalnya 2 dewasa + 1 anak (1–5 th). Umur dihitung saat beli. Di bawah umur minimum anak gratis dan tidak dihitung; di atas umur maksimum anak dihitung dewasa. Pemegang pass selalu dewasa.

4Pembayaran Pengguna

Pembayaran lewat DOKU. Tersedia Virtual Account (VA), QRIS, dan kartu, tergantung channel yang diaktifkan.

• Virtual Account: nomor VA tampil di halaman portal sendiri, lengkap dengan langkah bayar per bank. Berlaku 60 menit.
• Halaman pembayaran berpindah sendiri setelah pembayaran diterima; status juga dikirim lewat email.
• Jika belum selesai bayar, saat login kembali akan ada pengingat untuk melanjutkan.

5Keluarga & tambah orang Pengguna

Satu Annual Pass berlaku untuk satu keluarga. Tiap anggota punya Member ID sendiri.

Tambah orang di luar paket

Saat checkout atau dari menu Keluarga, pelanggan bisa menambah orang di luar kapasitas paket: Tambah dewasa, Tambah anak, atau Upgrade slot anak ke dewasa (bila anak sudah di atas umur anak). Pada paket berkomposisi, sistem memilih opsi termurah dari tanggal lahir yang diisi.

"Isi nanti"

Pelanggan boleh memilih Isi nanti untuk nama anggota, tetapi tetap bisa menambah/upgrade orang (bayar sekarang, nama diisi belakangan dari menu Keluarga).

Diskon tambah orang

Makin banyak orang ditambah, makin besar diskonnya (diatur per produk di CMS). Contoh: tambah 1–4 orang diskon 5%, tambah 5+ diskon 10%.

6Reservasi & QR Masuk Pengguna

1. Menu Kunjungan → Buat Reservasi → pilih taman & tanggal.
2. Pada H-1 atau hari-H, tekan "Saya akan datang" untuk konfirmasi kedatangan.
3. Setelah konfirmasi, QR Masuk terbuka. Di gerbang, tunjukkan QR ke petugas.

• QR Masuk berganti tiap 30 detik dan hanya berlaku di hari kunjungan — mencegah QR disebar.
• QR tetap bisa dibuka walau sinyal hilang, asalkan sudah pernah dibuka sekali saat online (mode offline).
• QR hanya terbuka di area taman (geofence), sebagai pengaman tambahan.

7QR Member ID di kasir Pengguna

Untuk belanja F&B dan wahana di kasir ESB — berbeda dengan QR Masuk.

1. Beri tahu kasir bahwa Anda member Annual Pass.
2. Buka Ringkasan → tekan "QR Member ID untuk kasir" (atau ketuk Member ID).
3. Kasir memindai QR itu, atau mengetik Member ID tanpa tanda strip (mis. TSI482917365).
4. Diskon member langsung terpotong di struk.
5. Beberapa menit kemudian struknya muncul di Transaksi › Belanja F&B.

8Belanja, akun, aplikasi Pengguna

• Belanja F&B: rincian struk (item, outlet, taman, diskon) di menu Transaksi.
• Foto profil: dipakai petugas gerbang mengenali pemegang pass.
• Pasang aplikasi: portal bisa dipasang di layar HP seperti aplikasi (PWA). Di Android/Chrome muncul dialog pasang; di iPhone lewat Bagikan → "Tambahkan ke Layar Utama". Bila aplikasi TSI ada di App Store/Play Store, banner aplikasi juga muncul.
• Login Google/Apple dan akun aplikasi Taman Safari didukung (SSO).

9CMS — Akses & peran Admin

CMS dibuka di cms.tsi…. Menu yang tampil mengikuti peran.

10Produk & harga Admin

Membership Products → Create Product membuka Membership Builder (9 langkah).

11Diskon bertingkat & produk tersembunyi Admin

Skema diskon (Group Discount)

Tab Group Discount di samping Benefit type master. Buat skema dengan jumlah tingkat bebas (tombol + Add tier): tiap tingkat isi "dari berapa orang" dan "% diskon". Tingkat tertinggi yang tercapai yang dipakai. Di produk (Family Capacity) tinggal pilih skemanya; satu skema bisa dipakai banyak produk.

Produk tersembunyi (kampanye videotron)

Di Product Information, matikan "Show in the public catalog":

• Produk tidak muncul di /beli maupun halaman depan.
• Tetap bisa dibeli lewat link/QR langsung (muncul QR + tombol Copy setelah produk disimpan).
• Pakai untuk produk harga khusus di videotron dalam park; yang beli dari web biasa tetap harga publish.
• Di daftar produk muncul badge Hidden.

12Operasional Admin

13Integrasi & setelan Super Admin

Integration Settings

Menu System › Integration Settings: ganti konfigurasi integrasi tanpa membuka server. Per tab: DOKU (Sandbox/Production + Client ID/Secret), ESB, GlobalTix, NetSuite, Aplikasi TSI & Cognito, Email, WhatsApp. Nilai rahasia disimpan terenkripsi (hanya 4 karakter terakhir yang tampil). Menyimpan memuat ulang API ±10 detik.

Unit Credentials

Akun GlobalTix/ESB berbeda per taman diisi di Unit Credentials; tanpa itu, unit memakai akun bawaan dari server.

14Arsitektur Teknis

nginx di depan menangani HTTPS (Let's Encrypt) dan mem-proxy tiap subdomain ke port di atas. Service dijalankan systemd (tsi-api, tsi-web, tsi-dashboard, tsi-face) di VPS Ubuntu dengan akses root. Database PostgreSQL 16.

15Struktur kode Teknis

/srv/tsi-membership/repo
├─ api/                Go: cmd/api, internal/{handler,service,models,...}
├─ web/                Portal pelanggan (SvelteKit)
├─ dashboard/          CMS (SvelteKit)
├─ db/migrations/      0000NN_*.up.sql / .down.sql  (urut, idempoten)
├─ scripts/            deploy, e2e, bersihkan-data-uji, ganti-domain-gambar
├─ docs/               dokumen + situs ini (docs/situs/)
├─ update.sh           deploy: pull, build, migrasi, restart, health check
└─ setup.sh            setup sekali jalan

16Deploy & migrasi Teknis

# Deploy satu komponen (otomatis: pull, build, migrasi, restart, cek sehat)
/srv/tsi-membership/repo/update.sh --only api --force
/srv/tsi-membership/repo/update.sh --only web --force
/srv/tsi-membership/repo/update.sh --only dashboard --force

• Migrasi SQL di db/migrations/, dijalankan otomatis oleh update.sh --only api. pg_dump cadangan diambil sebelum migrasi.
• Setiap migrasi punya .up.sql dan .down.sql, memakai IF NOT EXISTS agar aman diulang.
• Nomor & kode: Member/Membership/Reservation acak dengan Luhn; nomor transaksi sekuensial (TRX-YYYY-NNNNNN).

Variabel lingkungan penting (api/.env)

17Integrasi (detail) Teknis

QR offline

Token TSIO1.<rsv>.<unit>.<window>.<code>, window = unix/30, code = 10 hex pertama HMAC-SHA256(secret, "rsv|unit|window"), toleransi ±2 window. Validator gerbang bisa memeriksanya tanpa internet.

18Keamanan & lisensi Teknis

• Password di-hash bcrypt; tak pernah disimpan polos.
• HTTPS/TLS semua lalu lintas; API hanya lewat nginx.
• Kredensial integrasi dienkripsi AES-256-GCM dengan INTEGRATION_KEY.
• Query berparameter (aman dari SQL injection); akses per peran.
• Audit log untuk perubahan penting.
• License lock: di produksi, binary API menolak jalan tanpa lisensi Ed25519 yang sah untuk domainnya dan masih dalam masa sewa. Kunci privat penerbit lisensi dipegang Liburania (tidak di repo/server). Melindungi kode dari pemakaian di luar kontrak.

19Go-live & pindah server Teknis

Perlu VPS Ubuntu 24.04 dengan akses root (bukan hosting PHP managed). Butuh PostgreSQL, Go, Node, nginx, systemd.

1. Siapkan server, clone repo, isi api/.env (bawa INTEGRATION_KEY & OIDC_SIGNING_KEY sama; buat LICENSE_KEY untuk domain baru).
2. Restore database, jalankan scripts/bersihkan-data-uji.sh (buang data uji, simpan setelan) dan scripts/ganti-domain-gambar.sh.
3. Pasang service + nginx + SSL (template di scripts/server-baru/), update.sh --force.
4. Daftarkan alamat baru di DOKU (Notification URL), ESB, GlobalTix, Cognito (callback), aplikasi TSI.
5. Smoke test; aktifkan DOKU production dari CMS saat channel siap.