fix: migration

feat(enakgame): weekly leaderboard
GET /customer/enakgame/leaderboard ranks the customers of an organization by the EnakCoin they won from games in one week, Monday to Sunday in Asia/Jakarta. Only completed, unflagged sessions count, by the week they started; entry cost is not subtracted. Equal totals rank by who reached theirs first, so no two customers share a rank. Optional date (any day of the week, this week by default), game_id and limit (10, at most 100). The response holds the top ranks and, under me, the customer asking wherever they rank. Other customers are shown by a masked name: the first word whole, the others by their first letter; a word with a digit keeps only its first character. The EnakGame web game shows it: integration-enakgame.md §10 (checklist now §11) and RFC §11. The DB test needs TEST_DATABASE_URL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-12 22:07:22 +07:00 · 2026-10-12 16:15:02 +07:00 · 2026-10-09 22:59:58 +07:00 · 2026-10-09 22:59:27 +07:00 · 2026-10-09 22:58:24 +07:00 · 2026-10-09 22:58:02 +07:00
43 changed files with 3190 additions and 1520 deletions
@@ -1,377 +0,0 @@
 # API EnakPoint & EnakCoin
 30 Sep 2026
 Semua endpoint EnakPoint (`POINT`, hanya untuk ditukar ke voucher) dan EnakCoin (`COIN`, untuk game dan ditukar ke EnakPoint) ada di bawah base URL `/api/v1`, memakai satu format response, dan semua jumlah berupa bilangan bulat.
 > **Perubahan 7 Okt 2026:** bayar order dengan EnakPoint sudah dihapus, karena EnakPoint sekarang hanya bisa ditukar ke voucher: tidak bisa dipakai sebagai alat bayar dan tidak bisa dicairkan ([`enakgame-prd.md`](./enakgame-prd.md) §3.2). Endpoint dan field yang ikut dihapus ada di Referensi → Endpoint dan field yang dihapus.
 ## Konvensi umum
 | Klien | Autentikasi | Prefix |
 | --- | --- | --- |
 | Customer app / self-order | `Authorization: Bearer <token customer>` | `/api/v1/customer` |
 | POS | Token user (kasir/manager) | `/api/v1` |
 | Dashboard | Token user, role Admin atau Manager | `/api/v1/marketing`, `/api/v1/outlets` |
 **Format response.** Sukses: `{"success": true, "data": {…}, "errors": null}`. Gagal: `{"success": false, "data": null, "errors": [{"code": "304", "entity": "wallet_service", "cause": "…"}]}`. Tampilkan `cause` sebagai alasan penolakan.
 | `code` | HTTP | Arti |
 | --- | --- | --- |
 | `303`, `310` | 400 | Body atau parameter tidak lengkap / salah format |
 | `304` | 400 | Ditolak aturan bisnis (saldo kurang, di luar batas, dst.) |
 | `404` | 404 | Tidak ditemukan, juga untuk data milik customer atau organisasi lain |
 | `429` | 429 | OTP diminta ulang terlalu cepat |
 | `PIN_NOT_SET` | 403 | Customer belum membuat PIN |
 | `PIN_INVALID` | 400 | PIN salah |
 | `PIN_LOCKED` | 423 | PIN terkunci 30 menit setelah 5 kali salah |
 | `TRANSFER_BLOCKED` | 403 | Transfer ditahan 24 jam setelah reset PIN |
 | `900` | 500 | Kesalahan server |
 **Error PIN** membawa `data` yang tidak `null`: `{"code": "PIN_INVALID", "remaining_attempts": 3}`, `{"code": "PIN_LOCKED", "locked_until": "…"}`, atau `{"code": "TRANSFER_BLOCKED", "transfer_blocked_until": "…"}`. Endpoint yang menerima `pin` bisa mengembalikan salah satunya. PIN selalu dikirim sebagai string 6 digit.
 **Idempotency.** Exchange dan transfer wajib header `Idempotency-Key` (maks. 50 karakter, `X-Idempotency-Key` juga diterima): satu key per percobaan, dan key yang sama dipakai ulang saat retry. Retry mengembalikan hasil pertama dengan `replayed: true`.
 **Waktu.** Tanggal kedaluwarsa dan filter tanggal memakai WIB. Saldo berlaku sampai 23:59:59 WIB pada tanggal kedaluwarsanya.
 ## Customer app: saldo & riwayat
 | Method | Path | Keterangan |
 | --- | --- | --- |
 | GET | `/customer/wallet` | Saldo, nilai rupiah, kedaluwarsa terdekat, 5 mutasi terakhir |
 | GET | `/customer/wallet/transactions` | Riwayat mutasi, dengan pagination dan filter |
 | GET | `/customer/wallet/expiring` | Saldo yang akan kedaluwarsa, per currency dan tanggal |
 | PUT | `/customer/devices` | Daftarkan token FCM device |
 | DELETE | `/customer/devices/:device_id` | Hapus device saat logout |
 | GET | `/customer/outlets` | Outlet aktif di organisasi customer, dengan `earns_points`, `earns_coins` |
 | GET | `/customer/orders` | Riwayat order customer (`page`, `limit`), dengan `points_earned` / `coins_earned` |
 | GET | `/customer/orders/:id` | Detail order: item, pembayaran, EnakPoint/EnakCoin yang didapat; order customer lain → `404` |
 Registrasi (`POST /customer-auth/register/start`) menerima `organization_id` opsional: bila tidak dikirim dan hanya ada satu organisasi, customer masuk ke organisasi itu. Contoh request dan response lengkap untuk outlet dan order ada di [`mobile-customer-enakpoint.md`](./mobile-customer-enakpoint.md) §4.4–§4.5.
 ### GET /customer/wallet
 ```json
 {
  "point_balance": 12500,
  "coin_balance": 8,
  "point_value": 1,
  "point_discount_value": 12500,
  "nearest_expiring": {
    "point": { "amount": 150, "date": "2026-12-31" },
    "coin": null
  },
  "recent_transactions": [ "… sama seperti item riwayat …" ]
 }
 ```
 - `point_balance` / `coin_balance` = saldo yang bisa dipakai sekarang.
 - `point_discount_value` = `point_balance × point_value`; tampilkan sebagai "setara potongan Rp …", bukan saldo uang.
 - `nearest_expiring.point` / `.coin` bernilai `null` bila tidak ada yang akan kedaluwarsa.
 ### GET /customer/wallet/transactions
 | Query | Tipe | Keterangan |
 | --- | --- | --- |
 | `page` | int | Default 1 |
 | `limit` | int | 1–100, default 20 |
 | `currency` | `POINT` \| `COIN` | Opsional |
 | `type` | string | Satu tipe atau beberapa dipisah koma, mis. `EARN,TRANSFER_IN` |
 | `from`, `to` | `YYYY-MM-DD` | Tanggal WIB, inklusif |
 ```json
 {
  "data": [
    {
      "id": "…",
      "currency": "POINT",
      "type": "EARN",
      "amount": 875,
      "balance_after": 12500,
      "description": "Belanja #ORD-0123 di Outlet Kemang",
      "source": { "type": "ORDER", "id": "…" },
      "outlet_id": "…",
      "group_id": null,
      "expires_at": "2026-12-31T23:59:59+07:00",
      "lots": [{ "amount": 875, "remaining": 875, "expires_at": "2026-12-31T23:59:59+07:00" }],
      "created_at": "2026-09-30T12:01:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 }
 }
 ```
 `amount` bertanda (+ menambah, − mengurangi). Penambahan membawa `source`, pengurangan membawa `destination`, keduanya `{ type, id }`. Dua baris exchange atau transfer berbagi `group_id`. Daftar tipe ada di bagian Referensi.
 ### GET /customer/wallet/expiring
 ```json
 {
  "point": [
    { "amount": 150, "date": "2026-10-31" },
    { "amount": 200, "date": "2026-12-31" }
  ],
  "coin": []
 }
 ```
 Terurut dari tanggal terdekat. Daftar kosong berarti tidak ada yang akan kedaluwarsa.
 ### PUT /customer/devices
 ```json
 { "device_id": "a1b2c3", "fcm_token": "…", "platform": "android", "app_version": "2.4.0" }
 ```
 Panggil setelah login dan setiap kali FCM memberi token baru. `device_id` dan `fcm_token` wajib; `platform` = `android` | `ios` | `web`. Satu token hanya milik satu customer: customer lain yang mendaftarkan token yang sama mengambil alih HP itu. Response: `{ "device_id": "a1b2c3" }`.
 ## Customer app: PIN
 PIN 6 digit wajib untuk exchange dan transfer; minta customer membuatnya saat pertama kali melakukan aksi itu.
 | Method | Path | Body | Response |
 | --- | --- | --- | --- |
 | GET | `/customer/pin/status` | – | `{ "has_pin", "locked_until", "transfer_blocked_until" }` |
 | POST | `/customer/pin/otp` | `{ "purpose": "pin_setup" }` atau `"pin_reset"` | `{ "purpose", "otp_token", "expires_at" }` |
 | POST | `/customer/pin` | `{ "otp_token", "otp_code", "pin", "confirm_pin" }` | Status PIN |
 | PUT | `/customer/pin` | `{ "old_pin", "pin", "confirm_pin" }` | Status PIN |
 | POST | `/customer/pin/reset` | `{ "otp_token", "otp_code", "pin", "confirm_pin" }` | Status PIN |
 1. **Buat PIN:** minta OTP dengan `purpose: "pin_setup"` (dikirim lewat WhatsApp), lalu `POST /customer/pin` dengan `otp_token` dari response OTP dan kode yang diterima customer.
 2. **Lupa PIN:** minta OTP dengan `purpose: "pin_reset"`, lalu `POST /customer/pin/reset`. Reset membuka kunci PIN, tapi transfer keluar ditahan 24 jam; exchange tetap bisa.
 3. **Ganti PIN:** `PUT /customer/pin` dengan PIN lama.
 PIN baru ditolak `304` bila bukan 6 digit, konfirmasinya beda, semua digit sama (`111111`), berurutan (`123456`, `654321`), atau sama dengan tanggal lahir (`DDMMYY` / `YYMMDD`). OTP yang diminta terlalu cepat dijawab `429`. Penanganan `PIN_INVALID`, `PIN_LOCKED`, dan `TRANSFER_BLOCKED` ada di Konvensi umum.
 ## Customer app: exchange, transfer, game
 | Method | Path | PIN | Idempotency-Key |
 | --- | --- | --- | --- |
 | GET | `/customer/wallet/exchange/preview?coins=` | – | – |
 | POST | `/customer/wallet/exchange` | Ya | Wajib |
 | GET | `/customer/wallet/transfer/recipient?phone=` | – | – |
 | POST | `/customer/wallet/transfer` | Ya | Wajib |
 | POST | `/customer/enakgame/sessions` | – | Wajib |
 ### GET /customer/wallet/exchange/preview?coins=30
 ```json
 { "coin_amount": 10, "point_amount": 3, "coin_balance": 35, "coins": 30, "points": 9, "valid": true }
 ```
 Kurs: `coin_amount` EnakCoin = `point_amount` EnakPoint (default 1 : 1). Bila `valid: false`, tampilkan `reason`.
 ### POST /customer/wallet/exchange
 Body `{ "coins": 30, "pin": "482913" }`. Response:
 ```json
 {
  "group_id": "…",
  "coins": 30,
  "points": 9,
  "coin_amount": 10,
  "point_amount": 3,
  "lots": [{ "amount": 9, "expires_at": "2026-12-31T23:59:59+07:00" }],
  "coin_balance": 5,
  "point_balance": 9,
  "replayed": false
 }
 ```
 `coins` harus kelipatan `coin_amount`; jumlah yang salah ditolak `304` sebelum PIN dicek. Exchange tidak bisa dibatalkan. EnakPoint hasil tukar tidak bisa hidup lebih lama dari EnakCoin asalnya (lihat `lots`).
 ### GET /customer/wallet/transfer/recipient?phone=081234561234
 ```json
 { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" }
 ```
 Nomor di luar organisasi atau tidak terdaftar → `404`. Diri sendiri, customer walk-in, atau nonaktif → `304`.
 ### POST /customer/wallet/transfer
 Body `{ "currency": "POINT", "amount": 120, "recipient_phone": "081234561234", "pin": "482913" }`. Response:
 ```json
 {
  "group_id": "…",
  "currency": "POINT",
  "amount": 120,
  "recipient": { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" },
  "lots": [
    { "amount": 100, "expires_at": "2026-12-31T23:59:59+07:00" },
    { "amount": 20, "expires_at": null }
  ],
  "balance": 30,
  "replayed": false
 }
 ```
 `currency` = `POINT` atau `COIN`. Batas organisasi (transfer aktif, minimal, maksimal per transaksi, batas harian per currency yang reset tengah malam WIB) ditolak `304` sebelum PIN dicek. Transfer final. Saldo membawa tanggal kedaluwarsa aslinya ke penerima (`lots`), dan penerima mendapat push `WALLET_TRANSFER_IN`.
 ### Game (EnakGame)
 `POST /customer/spin`, `GET /customer/games`, dan `GET /customer/ferris-wheel` sudah dihapus. Semua game, termasuk spin, dimainkan lewat `/customer/enakgame`:
 - `GET /customer/enakgame/games`: game aktif dengan `entry_cost` (EnakCoin per main) dan, untuk spin, `prizes` (segmen roda).
 - `POST /customer/enakgame/sessions` dengan `{ "game_id": "…" }` dan `Idempotency-Key`: memotong `entry_cost`.
 - `POST /customer/enakgame/sessions/:id/complete`: server menghitung hadiah EnakCoin; untuk spin, response berisi `prize` (segmen yang keluar).
 Alur spin lengkap ada di [`enakgame-spin.md`](./enakgame-spin.md).
 ## POS: earning, void, dan refund
 EnakPoint bukan payment method: tidak ada lagi tipe `point`, dan `POST /payments` memakai `amount` seperti pembayaran lain. Response order membawa `points_earned` dan `coins_earned` untuk struk. Saat order di-void atau direfund, EnakPoint dan EnakCoin yang didapat dari order itu ikut ditarik (`EARN_REVERSAL`); bila saldo sudah terpakai, ditarik sebanyak yang ada dan refund tetap jalan.
 ## Dashboard
 Semua endpoint dashboard butuh role Admin atau Manager, dan semuanya dibatasi ke organisasi user yang login. Rincian layar ada di [`backoffice-enakpoint.md`](./backoffice-enakpoint.md).
 | Method | Path | Keterangan |
 | --- | --- | --- |
 | GET, PUT | `/outlets/:outlet_id/loyalty-settings` | Earning EnakPoint dan EnakCoin per outlet |
 | GET, PUT | `/marketing/loyalty-settings` | Nilai EnakPoint, kurs, transfer, kedaluwarsa (`?dry_run=true` untuk preview) |
 | GET | `/marketing/loyalty-settings/history` | Riwayat perubahan setting (`page`, `limit`, `outlet_id`) |
 | GET | `/marketing/customers/:id/wallet` | Saldo, lot aktif, riwayat dengan nama asli |
 | POST | `/marketing/customers/:id/wallet/adjust` | Koreksi saldo manual |
 | GET | `/marketing/wallet-transactions/:id/trace` | Telusuri asal saldo per butir |
 | DELETE | `/marketing/customers/:id/pin` | Hapus PIN customer |
 | GET | `/marketing/customers/:id/security-events` | Log keamanan PIN (`page`, `limit`) |
 Pada kedua `PUT` setting, field yang tidak dikirim tetap memakai nilai sekarang; field yang tidak dikenal ditolak.
 ### /outlets/:outlet_id/loyalty-settings
 ```json
 {
  "point": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 100, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null },
  "coin": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 25000, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null }
 }
 ```
 Response menambahkan `outlet_id`, `point_value`, `point_cashback_percent` (default di atas = 1%), dan `changes` pada PUT. `earn_mode` adalah `PER_AMOUNT` (setiap `earn_per_amount` rupiah mendapat `earn_value`) atau `PERCENTAGE` (`earn_percent` persen dari basis). Validasi: `earn_per_amount > 0`, `earn_value ≥ 0`, `earn_percent` 0–100 dengan maks. 2 angka desimal. Objek `point_payment` sudah dihapus; `PUT` yang masih mengirimnya ditolak `310` (field tidak dikenal).
 ### /marketing/loyalty-settings
 ```json
 {
  "point_value": 1,
  "exchange": { "coin_amount": 1, "point_amount": 1 },
  "transfer": { "enabled": true, "min_amount": 1, "max_per_transaction": null, "daily_limit": null },
  "point_expiry": {
    "enabled": false,
    "mode": "FIXED_DATE",
    "fixed_dates": ["12-31"],
    "grace_months": 3,
    "period": 12,
    "unit": "MONTH",
    "end_of_month": false,
    "reminder_days": 7
  },
  "coin_expiry": { "…": "sama dengan point_expiry" },
  "enakgame": { "user_daily_limit": 0, "global_daily_limit": 0 }
 }
 ```
 | Field kedaluwarsa | Dipakai mode | Nilai |
 | --- | --- | --- |
 | `mode` | – | `FIXED_DATE` (hangus di tanggal tetap tiap tahun) atau `ROLLING` (umur sejak didapat) |
 | `fixed_dates` | `FIXED_DATE` | `MM-DD`, boleh lebih dari satu; `02-29` ditolak |
 | `grace_months` | `FIXED_DATE` | 0–24; saldo yang didapat kurang dari ini sebelum tanggal hangus ikut ke tanggal berikutnya |
 | `period`, `unit` | `ROLLING` | ≥ 1, `DAY` atau `MONTH` |
 | `end_of_month` | `ROLLING` | Dibulatkan ke akhir bulan |
 | `reminder_days` | keduanya | Hari sebelum hangus untuk pengingat; 0 = tanpa pengingat |
 Response menambahkan:
 - `impact`: saldo beredar dan nilai rupiahnya sebelum/sesudah perubahan `point_value` atau kurs.
 - `expiry_preview`: `{ "point", "coin" }`, kapan saldo yang didapat sekarang kedaluwarsa (`null` = tidak).
 - `expiry_activations`: bila perubahan ini menyalakan kedaluwarsa pertama kali, `[{ "currency", "lots", "amount", "expires_at" }]` saldo lama yang ikut diberi tanggal.
 - `changes` dan `dry_run`.
 ### POST /marketing/customers/:id/wallet/adjust
 ```json
 { "currency": "POINT", "amount": -500, "reason": "Komplain #45", "idempotency_key": "adj-45" }
 ```
 `amount` bertanda dan tidak boleh 0; `reason` wajib. Pengurangan yang melebihi saldo ditolak `304`. Response: `{ "transaction", "spendable_point_balance", "spendable_coin_balance", "replayed" }`.
 ### GET /marketing/wallet-transactions/:id/trace
 ```json
 {
  "transaction": { "id": "…", "customer": { "id": "…", "name": "Budi Santoso" }, "type": "TRANSFER_OUT", "amount": -30, "…": "…" },
  "lots": [
    {
      "amount": 30,
      "chain": [
        { "lot": { "id": "…", "expires_at": "…" }, "source": { "type": "TRANSFER_IN", "customer": { "name": "Budi Santoso" } } },
        { "lot": { "id": "…", "origin_lot_id": null }, "source": { "type": "EARN", "reference_type": "ORDER", "description": "Belanja #ORD-1", "customer": { "name": "Anita" } } }
      ]
    }
  ]
 }
 ```
 Pengurangan menampilkan lot yang dipakai; penambahan menampilkan lot yang dibuat. Tiap `chain` mundur lewat transfer atau exchange sampai lot pertama dari `EARN`, `ADJUSTMENT`, atau `MIGRATION`.
 ### PIN customer
 `DELETE /marketing/customers/:id/pin` dengan `{ "reason": "…" }` memaksa customer membuat PIN baru lewat OTP; admin tidak bisa membuat, mengganti, atau melihat PIN. `security-events` mengembalikan `PIN_SET`, `PIN_CHANGED`, `PIN_RESET`, `PIN_FAILED`, `PIN_LOCKED`, `PIN_REMOVED_BY_ADMIN` beserta waktu, IP, dan perangkat.
 ## Referensi
 ### Tipe mutasi (`type`)
 | `type` | Arah | Arti | `source` / `destination` |
 | --- | --- | --- | --- |
 | `EARN` | + | Didapat dari order lunas | `ORDER` |
 | `EARN_REVERSAL` | − | Ditarik karena order di-void/refund | `ORDER` |
 | `EXCHANGE_OUT` | − | EnakCoin ditukar | `WALLET_TX` (baris `EXCHANGE_IN`) |
 | `EXCHANGE_IN` | + | EnakPoint hasil tukar | `WALLET_TX` (baris `EXCHANGE_OUT`) |
 | `TRANSFER_OUT` | − | Dikirim ke customer lain | `WALLET_TX` (baris `TRANSFER_IN`) |
 | `TRANSFER_IN` | + | Diterima dari customer lain | `WALLET_TX` (baris `TRANSFER_OUT`) |
 | `GAME_SPEND` | − | Main game (EnakCoin saja) | `GAME_PLAY` |
 | `EXPIRE` | − | Hangus karena kedaluwarsa | `LOT` |
 | `ADJUSTMENT` | + / − | Koreksi admin | `USER` |
 | `MIGRATION` | + | Saldo dari sistem lama | `LEGACY_POINTS` / `LEGACY_TOKENS` |
 ### Notifikasi push (FCM)
 Semua nilai `data` berupa string. Push hanya sampai ke device yang terdaftar lewat `PUT /customer/devices`.
 | `data.type` | Kapan | Isi `data` lainnya |
 | --- | --- | --- |
 | `WALLET_TRANSFER_IN` | Menerima transfer | `transaction_id`, `group_id`, `currency`, `amount` |
 | `WALLET_EXPIRING` | `reminder_days` hari sebelum hangus, sekali per tanggal | `currency`, `amount`, `expiry_date` |
 | `WALLET_EXPIRED` | Saldo baru saja hangus | `currency`, `amount` |
 | `PIN_LOCKED` | PIN terkunci setelah 5 kali salah | `locked_until` (RFC3339, UTC) |
 ### Endpoint dan field deprecated
 Masih jalan dan membaca wallet, tapi akan dihapus setelah semua versi aplikasi pindah. Semua yang bernama token (`/customer/tokens`, `total_tokens`, `tokens_history`, `token_used`, `tokens_remaining`, campaign `TOKENS`) sudah dihapus; pakai `coin_balance`, `coins_used`, `coins_remaining`, dan `COINS`.
 | Lama | Pengganti |
 | --- | --- |
 | `GET /customer/points` | `GET /customer/wallet` → `point_balance` |
 | `total_points`, `points_history`, `last_updated` di `/customer/wallet` | `point_balance`, `recent_transactions` |
 ### Endpoint dan field yang dihapus
 Bayar dengan EnakPoint dihapus pada 7 Okt 2026 karena EnakPoint sekarang hanya untuk voucher ([`enakgame-prd.md`](./enakgame-prd.md) §3.2). Tidak ada penggantinya; jangan dipanggil lagi.
 | Dihapus | Catatan |
 | --- | --- |
 | `POST /customer/wallet/payment-code` | Kode bayar untuk kasir |
 | `POST /customer/orders/:id/pay-with-points` | Bayar order dari app / self-order |
 | `GET /orders/:id/point-payment/preview` | Batas pembayaran EnakPoint di POS |
 | Payment method tipe `point`; field `points` dan `payment_code` di `POST /payments` | `amount` kembali wajib seperti pembayaran lain |
 | `points_used`, `point_value` di response pembayaran dan di `payments` pada `GET /customer/orders/:id` | – |
 | `accepts_point_payment` di `GET /customer/outlets` | – |
 | `point_payment` (`accept_payment`, `min_payment_points`, `max_payment_percent`) di `/outlets/:outlet_id/loyalty-settings` | `PUT` yang masih mengirimnya ditolak `310` |
 | `summary.point_amount`, `summary.points_used`, `summary.total_with_points`, serta `points_used` dan `counts_as_cash_in` per baris di analytics payment method | `summary.total_amount` kembali total semua method; persentase dihitung dari total itu |
 | Tipe mutasi `PAYMENT` dan `PAYMENT_REFUND` | Tidak ditulis lagi |
 Panduan alur lengkap per tim ada di [`integration-enakpoint.md`](./integration-enakpoint.md).
@@ -1,299 +0,0 @@
 # Backoffice EnakPoint & EnakCoin
 30 Sep 2026
 Backoffice perlu tujuh layar untuk mengelola program loyalitas: setting per outlet, setting per organisasi (termasuk kedaluwarsa), wallet customer, telusuri mutasi, PIN customer, riwayat setting, dan biaya main game.
 > **Perubahan 7 Okt 2026:** bayar dengan EnakPoint sudah dihapus karena EnakPoint sekarang hanya bisa ditukar ke voucher, tidak bisa dipakai sebagai alat bayar dan tidak bisa dicairkan ([`enakgame-prd.md`](./enakgame-prd.md) §3.2). Akibatnya setting outlet tidak lagi punya `point_payment`, method "EnakPoint" (tipe `point`) tidak ada lagi di Payment Method, dan laporan per payment method tidak lagi membawa `point_amount`, `points_used`, `total_with_points`, atau `counts_as_cash_in`; `summary.total_amount` kembali total semua method.
 ## Layar yang perlu dibuat
 Semua endpoint di bawah base URL `/api/v1`, butuh login user dengan role Admin atau Manager, dan otomatis dibatasi ke organisasi user tersebut. Data customer atau outlet organisasi lain dijawab `404`.
 | Layar | Endpoint | Tempat di menu |
 | --- | --- | --- |
 | Setting loyalitas outlet | `GET` / `PUT /outlets/:outlet_id/loyalty-settings` | Outlet → detail outlet → tab Loyalitas |
 | Setting loyalitas organisasi | `GET` / `PUT /marketing/loyalty-settings` (+ `?dry_run=true`) | Marketing → Loyalitas → Pengaturan |
 | Riwayat perubahan setting | `GET /marketing/loyalty-settings/history` | Marketing → Loyalitas → Riwayat |
 | Wallet customer | `GET /marketing/customers/:id/wallet`, `POST …/wallet/adjust` | Customer → detail customer → tab Wallet |
 | Telusuri mutasi | `GET /marketing/wallet-transactions/:id/trace` | Dibuka dari baris riwayat wallet |
 | PIN & keamanan customer | `DELETE /marketing/customers/:id/pin`, `GET …/security-events` | Customer → detail customer → tab Keamanan |
 | Biaya main game | `entry_cost` di `/marketing/enakgame/games` | Marketing → EnakGame → game |
 Penempatan menu di atas adalah usulan; sesuaikan dengan struktur backoffice yang ada.
 **Istilah di layar.** EnakPoint (`POINT`) adalah saldo yang hanya bisa ditukar ke voucher, bukan alat bayar; EnakCoin (`COIN`) untuk main game dan bisa ditukar ke EnakPoint. Nilai rupiah EnakPoint selalu ditulis "setara potongan Rp …", tidak pernah "saldo Rp …", karena saldo tidak bisa dicairkan.
 **Format response.** Sukses `{ "success": true, "data": … }`; gagal `{ "success": false, "errors": [{ "code", "entity", "cause" }] }`. Tampilkan `cause` sebagai pesan (lihat bagian Pesan error).
 ## Setting loyalitas outlet
 Tiap outlet mengatur sendiri berapa EnakPoint dan EnakCoin yang didapat dari order. Semua nilai default mati sampai owner menyalakannya.
 `GET /outlets/:outlet_id/loyalty-settings` → isi form. `PUT` ke path yang sama dengan objek yang sama untuk menyimpan; field yang tidak dikirim tetap, field tak dikenal ditolak (termasuk `point_payment` yang sudah dihapus).
 ```json
 {
  "point": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 100, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null },
  "coin": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 25000, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null }
 }
 ```
 | Field | Label usulan | Tipe | Default | Validasi |
 | --- | --- | --- | --- | --- |
 | `point.enabled` / `coin.enabled` | Beri EnakPoint / EnakCoin | toggle | mati | – |
 | `earn_mode` | Cara hitung: per nominal / persentase | pilihan `PER_AMOUNT` / `PERCENTAGE` | `PER_AMOUNT` | salah satu dari keduanya |
 | `earn_per_amount` | Setiap belanja Rp … (mode `PER_AMOUNT`) | Rp | 100 (point), 25.000 (coin) | > 0 |
 | `earn_value` | … mendapat (mode `PER_AMOUNT`) | angka | 1 | ≥ 0 |
 | `earn_percent` | … % dari belanja (mode `PERCENTAGE`) | %, boleh desimal | 1 | 0–100, maks. 2 angka desimal |
 | `min_order_amount` | Minimal belanja | Rp | 0 | ≥ 0 |
 | `max_per_order` | Maksimal per order | angka, boleh kosong | kosong = tanpa batas | ≥ 0 |
 **Cashback efektif.** Response membawa `point_cashback_percent` dan `point_value`. Tampilkan persentase di samping field earning EnakPoint, mis. "setara cashback 1%", dan hitung ulang di sisi klien saat owner mengetik: `earn_value × point_value ÷ earn_per_amount × 100`, atau pada mode `PERCENTAGE`: `earn_percent × point_value`. Tujuannya agar owner tidak salah membaca skala (1 per Rp 100 bukan 1 per Rp 1).
 **Mode earning.** Tampilkan hanya field mode yang dipilih (`earn_per_amount` + `earn_value`, atau `earn_percent`). Field mode lain tetap tersimpan di server, jadi tidak perlu dikosongkan saat owner berpindah mode. Pada mode `PERCENTAGE` jumlah yang didapat adalah `floor(basis × earn_percent ÷ 100)`, mis. 2,5% dari Rp 87.500 = 2.187 EnakPoint.
 **Contoh di bawah form.** "Belanja Rp 87.500 mendapat 875 EnakPoint dan 3 EnakCoin." Earning dihitung dari subtotal setelah diskon, sebelum pajak.
 Setelah `PUT`, response membawa `changes` (key yang berubah); tampilkan toast singkat, mis. "2 pengaturan disimpan".
 ## Setting loyalitas organisasi
 Nilai rupiah EnakPoint, kurs exchange, batas transfer, dan kedaluwarsa berlaku sama untuk semua outlet, jadi diatur sekali per organisasi. Mengubah nilai EnakPoint atau kurs langsung mengubah daya beli semua saldo customer, jadi layar ini wajib menampilkan dampaknya sebelum disimpan.
 ```json
 {
  "point_value": 1,
  "exchange": { "coin_amount": 1, "point_amount": 1 },
  "transfer": { "enabled": true, "min_amount": 1, "max_per_transaction": null, "daily_limit": null },
  "point_expiry": { "…": "lihat bagian kedaluwarsa" },
  "coin_expiry": { "…": "lihat bagian kedaluwarsa" },
  "enakgame": { "user_daily_limit": 0, "global_daily_limit": 0 }
 }
 ```
 | Field | Label usulan | Default | Validasi |
 | --- | --- | --- | --- |
 | `point_value` | Nilai 1 EnakPoint (Rp) | 1 | ≥ 1 |
 | `exchange.coin_amount` : `exchange.point_amount` | Kurs tukar: … EnakCoin = … EnakPoint | 1 : 1 | keduanya ≥ 1 |
 | `transfer.enabled` | Izinkan transfer antar customer | aktif | – |
 | `transfer.min_amount` | Minimal per transfer | 1 | ≥ 1 |
 | `transfer.max_per_transaction` | Maksimal per transfer | kosong = tanpa batas | ≥ 1 |
 | `transfer.daily_limit` | Batas harian per customer | kosong = tanpa batas | ≥ 1, dihitung per currency, reset tengah malam WIB |
 | `enakgame.user_daily_limit` | Maksimal EnakCoin dari EnakGame per customer per hari | 0 = tanpa batas | ≥ 0, reset tengah malam WIB |
 | `enakgame.global_daily_limit` | Maksimal EnakCoin dari EnakGame seluruh organisasi per hari | 0 = tanpa batas | ≥ 0, reset tengah malam WIB |
 ### Alur simpan
 1. Owner mengubah form.
 2. Tombol Simpan memanggil `PUT /marketing/loyalty-settings?dry_run=true` dengan objek yang diubah. Tidak ada yang tersimpan.
 3. Bila `changes` kosong, beri tahu "tidak ada perubahan" dan berhenti.
 4. Tampilkan dialog konfirmasi berisi `changes`, `impact` (bila `point_value` atau kurs berubah), dan `expiry_activations` (bila ada, lihat bagian kedaluwarsa).
 5. Konfirmasi memanggil `PUT` yang sama tanpa `dry_run`.
 ### Dialog dampak
 `impact` berisi saldo beredar organisasi dan nilainya sebelum/sesudah:
 | Field `impact` | Tampilkan sebagai |
 | --- | --- |
 | `outstanding_points` | EnakPoint beredar |
 | `point_rupiah_before` → `point_rupiah_after` | Setara potongan Rp … → Rp … |
 | `outstanding_coins` | EnakCoin beredar |
 | `coins_as_points_before` → `coins_as_points_after` | Bila semua ditukar: … EnakPoint → … EnakPoint |
 | `coin_rupiah_before` → `coin_rupiah_after` | Setara potongan Rp … → Rp … |
 Contoh kalimat: "Menaikkan nilai EnakPoint dari Rp 1 ke Rp 2 membuat 1.250.000 EnakPoint yang beredar setara potongan Rp 2.500.000 (sebelumnya Rp 1.250.000)." Perubahan hanya berlaku ke depan: exchange yang sudah terjadi memakai kurs saat itu.
 ## Pengaturan kedaluwarsa
 Kedaluwarsa diatur terpisah untuk EnakPoint (`point_expiry`) dan EnakCoin (`coin_expiry`) dengan salah satu dari dua model; defaultnya mati, dan bila dinyalakan defaultnya hangus setiap 31 Desember.
 ```json
 "point_expiry": {
  "enabled": true,
  "mode": "FIXED_DATE",
  "fixed_dates": ["12-31"],
  "grace_months": 3,
  "period": 12,
  "unit": "MONTH",
  "end_of_month": false,
  "reminder_days": 7
 }
 ```
 | Field | Tampil saat | Label usulan | Validasi |
 | --- | --- | --- | --- |
 | `enabled` | selalu | Saldo bisa kedaluwarsa | – |
 | `mode` | aktif | Model: Tanggal tetap / Sejak didapat | `FIXED_DATE` atau `ROLLING` |
 | `fixed_dates` | `FIXED_DATE` | Tanggal hangus setiap tahun | minimal satu, format `MM-DD`, `02-29` ditolak |
 | `grace_months` | `FIXED_DATE` | Periode tanggung (bulan) | 0–24, default 3 |
 | `period` + `unit` | `ROLLING` | Berlaku selama … hari/bulan | period ≥ 1, `DAY` atau `MONTH` |
 | `end_of_month` | `ROLLING` | Bulatkan ke akhir bulan | – |
 | `reminder_days` | aktif | Ingatkan customer … hari sebelumnya | ≥ 0, 0 = tanpa pengingat |
 **Tanggal tetap (`FIXED_DATE`).** Semua saldo hangus di tanggal yang sama, mis. 31 Desember, atau 30 Juni dan 31 Desember untuk dua kali setahun. Saldo yang didapat kurang dari `grace_months` sebelum tanggal itu ikut ke tanggal berikutnya, jadi saldo yang didapat 1 Oktober dengan tanggung 3 bulan hangus 31 Desember tahun depan. Untuk input `fixed_dates`, pakai pemilih tanggal+bulan tanpa tahun.
 **Sejak didapat (`ROLLING`).** Tiap saldo berlaku `period` hari atau bulan sejak masuk, mis. 12 bulan. Dengan `end_of_month`, saldo yang didapat 14 Maret 2026 hangus 31 Maret 2027.
 **Preview.** Response `GET`, `PUT`, dan dry run membawa `expiry_preview.point` dan `.coin`: kapan saldo yang didapat sekarang akan kedaluwarsa (`null` = tidak). Tampilkan di bawah form: "EnakPoint yang didapat hari ini kedaluwarsa pada 31 Des 2026." Karena dihitung dari nilai yang dikirim, dry run bisa dipakai untuk memperbarui preview saat owner mengubah pilihan.
 **Menyalakan pertama kali.** Saldo lama yang belum punya tanggal ikut diberi tanggal, dengan masa berlaku penuh: tanggal hangus kedua berikutnya (`FIXED_DATE`) atau satu periode sejak hari ini (`ROLLING`). Dry run mengembalikan `expiry_activations`; tampilkan di dialog konfirmasi dengan kalimat tegas, mis. "1.250.000 EnakPoint milik customer yang ada sekarang akan kedaluwarsa pada 31 Des 2027. Tindakan ini tidak bisa dibatalkan dengan mematikan kedaluwarsa."
 | Field `expiry_activations[]` | Arti |
 | --- | --- |
 | `currency` | `POINT` atau `COIN` |
 | `lots` | Jumlah paket saldo yang diberi tanggal |
 | `amount` | Total saldo yang diberi tanggal |
 | `expires_at` | Tanggal kedaluwarsanya |
 **Aturan lain yang perlu dijelaskan di layar:**
 - Mengubah model atau masa berlaku hanya berlaku untuk saldo yang masuk setelahnya.
 - Mematikan kedaluwarsa tidak membatalkan tanggal yang sudah terjadwal.
 - Saldo yang ditransfer atau ditukar membawa tanggal kedaluwarsa aslinya.
 - Saldo hangus tanpa kompensasi apa pun. Customer mendapat pengingat push `reminder_days` hari sebelumnya dan notifikasi saat hangus.
 ## Wallet customer
 Tab Wallet di detail customer dipakai untuk menangani komplain: melihat saldo dan asal-usulnya, mengoreksi saldo, dan menelusuri satu mutasi sampai ke order asalnya.
 ### Saldo, lot, dan riwayat
 `GET /marketing/customers/:id/wallet?page=1&limit=20&currency=POINT&type=TRANSFER_OUT,EARN&from=2026-09-01&to=2026-09-30` (semua query opsional, sama seperti riwayat di aplikasi customer)
 ```json
 {
  "customer": { "id": "…", "name": "Budi Santoso", "phone": "081234561234" },
  "point_balance": 12650,
  "coin_balance": 8,
  "spendable_point_balance": 12500,
  "spendable_coin_balance": 8,
  "lots": [
    { "id": "…", "currency": "POINT", "original_amount": 875, "remaining_amount": 875, "expires_at": "2026-12-31T23:59:59+07:00", "expired": false, "source_transaction_id": "…", "origin_lot_id": null, "created_at": "…" }
  ],
  "transactions": {
    "data": [
      {
        "id": "…", "currency": "POINT", "type": "TRANSFER_OUT", "amount": -120, "balance_after": 12650,
        "description": "Transfer ke An*** (08**-****-5678)",
        "destination": { "type": "WALLET_TX", "id": "…" },
        "counterparty": { "id": "…", "name": "Anita Rahma" },
        "created_by": null, "outlet": null, "reason": null, "metadata": {},
        "created_at": "…"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 }
  }
 }
 ```
 - **Saldo:** tampilkan `spendable_*` sebagai saldo utama. `point_balance` / `coin_balance` bisa sedikit lebih besar selama ada lot yang sudah lewat tanggal tapi belum diproses job kedaluwarsa (paling lama sekitar 15 menit).
 - **Lot:** tabel paket saldo yang masih berisi, urut dari yang paling cepat kedaluwarsa. Beri tanda untuk `expired: true`.
 - **Riwayat:** sama dengan riwayat customer, ditambah nama asli yang disamarkan untuk customer: `counterparty` (lawan transfer), `created_by` (admin pelaku adjustment), `outlet`, `reason`, dan `metadata` (kurs, rumus earning, shortfall).
 ### Adjustment manual
 `POST /marketing/customers/:id/wallet/adjust`
 ```json
 { "currency": "POINT", "amount": -500, "reason": "Komplain #45", "idempotency_key": "adj-7f3c" }
 ```
 | Field | Aturan |
 | --- | --- |
 | `currency` | `POINT` atau `COIN` |
 | `amount` | Bertanda, tidak boleh 0. Positif menambah, negatif mengurangi |
 | `reason` | Wajib; tampil di riwayat customer sebagai "Koreksi oleh admin: …" |
 | `idempotency_key` | Opsional tapi disarankan: buat satu nilai saat dialog dibuka, supaya klik ganda tidak mengoreksi dua kali |
 Pengurangan yang melebihi saldo yang bisa dipakai ditolak `304`. Adjustment tambah mengikuti aturan kedaluwarsa organisasi. Response: `{ "transaction", "spendable_point_balance", "spendable_coin_balance", "replayed" }`. Beri catatan di dialog bahwa adjustment tidak disertai pembayaran uang, sehingga alasan tidak boleh "pencairan".
 ### Telusuri mutasi
 Dari baris riwayat mana pun, tombol Telusuri memanggil `GET /marketing/wallet-transactions/:id/trace`.
 ```json
 {
  "transaction": { "id": "…", "customer": { "id": "…", "name": "Budi Santoso" }, "currency": "POINT", "type": "TRANSFER_OUT", "amount": -30, "description": "Transfer ke Ri*** (08**-****-9012)", "reference_type": "WALLET_TX", "reference_id": "…", "created_at": "…" },
  "lots": [
    {
      "amount": 30,
      "chain": [
        { "lot": { "id": "…", "expires_at": "…", "origin_lot_id": "…" }, "source": { "type": "TRANSFER_IN", "customer": { "name": "Budi Santoso" }, "description": "Transfer dari An*** (08**-****-5678)" } },
        { "lot": { "id": "…", "origin_lot_id": null }, "source": { "type": "EARN", "customer": { "name": "Anita Rahma" }, "reference_type": "ORDER", "reference_id": "…", "description": "Belanja #ORD-1 di Outlet Kemang" } }
      ]
    }
  ]
 }
 ```
 Tampilkan tiap `lots[]` sebagai rantai dari atas ke bawah: jumlah yang lewat lot itu, lalu setiap langkah `chain` dengan pemilik, tipe, dan deskripsinya. Langkah terakhir selalu `EARN`, `ADJUSTMENT`, atau `MIGRATION`; bila `reference_type` = `ORDER`, jadikan tautan ke detail order. Mutasi keluar menampilkan lot yang dipakai; mutasi masuk menampilkan lot yang dibuatnya.
 ## PIN, riwayat setting, dan game
 ### PIN & keamanan customer
 Admin tidak bisa membuat, mengganti, atau melihat PIN customer; satu-satunya aksi adalah menghapusnya, misalnya bila customer kehilangan akses, sehingga customer harus membuat PIN baru lewat OTP di aplikasi.
 - `DELETE /marketing/customers/:id/pin` dengan body `{ "reason": "Customer ganti nomor HP" }`. `reason` wajib. Tampilkan dialog konfirmasi dengan input alasan.
 - `GET /marketing/customers/:id/security-events?page=1&limit=20` untuk tab Keamanan:
 ```json
 {
  "data": [
    { "id": "…", "event": "PIN_LOCKED", "actor_user": null, "reason": null, "ip_address": "103.10.0.7", "user_agent": "EnakApp/2.4 (Android 14)", "created_at": "…" }
  ],
  "pagination": { "page": 1, "limit": 20, "total_count": 5, "total_pages": 1 }
 }
 ```
 | `event` | Label usulan |
 | --- | --- |
 | `PIN_SET` | PIN dibuat |
 | `PIN_CHANGED` | PIN diganti |
 | `PIN_RESET` | PIN direset lewat OTP (transfer ditahan 24 jam) |
 | `PIN_FAILED` | PIN salah dimasukkan |
 | `PIN_LOCKED` | PIN terkunci 30 menit |
 | `PIN_REMOVED_BY_ADMIN` | PIN dihapus admin (`actor_user`, `reason` terisi) |
 ### Riwayat perubahan setting
 `GET /marketing/loyalty-settings/history?page=1&limit=20` untuk setting organisasi; tambah `&outlet_id=…` untuk riwayat satu outlet.
 ```json
 { "id": "…", "organization_id": "…", "outlet_id": null, "key": "loyalty.point.value", "old_value": "1", "new_value": "2", "changed_by": "…", "created_at": "…" }
 ```
 `old_value` `null` berarti sebelumnya masih nilai default. Tampilkan `key` dengan label yang sama seperti di form (mis. `loyalty.point.value` → "Nilai 1 EnakPoint"), dan `changed_by` sebagai nama user.
 ### Biaya main game
 Semua game (spin, raffle, minigame) memakai EnakCoin yang sama dan dikelola di `/marketing/enakgame/games`. Menu lama `/marketing/games`, `/marketing/game-prizes`, dan `/marketing/rewards` sudah dihapus. Biaya per main adalah `entry_cost` game (bilangan bulat ≥ 1), hadiahnya diatur di reward config game itu. Langkah membuat spin ada di [`enakgame-spin.md`](./enakgame-spin.md). Hadiah game juga bernilai rupiah secara tidak langsung, karena EnakCoin bisa ditukar ke EnakPoint.
 ## Pesan error dan checklist
 | `code` | HTTP | Kapan terjadi di backoffice | Yang ditampilkan |
 | --- | --- | --- | --- |
 | `303`, `310` | 400 | Body tidak valid, field tak dikenal di `PUT` setting, UUID salah | Pesan umum "Data tidak valid" + `cause` untuk developer |
 | `304` | 400 | Nilai di luar batas, adjustment melebihi saldo, alasan kosong | `cause` di dekat field atau di toast |
 | `404` | 404 | Customer, outlet, atau mutasi bukan milik organisasi ini | "Data tidak ditemukan" |
 | `900` | 500 | Kesalahan server | "Terjadi kesalahan, coba lagi" |
 Pesan `cause` saat ini berbahasa Inggris, mis. `invalid loyalty settings: loyalty.point.earn_per_amount must be at least 1`. Untuk validasi form, lebih baik cek batasnya di sisi klien (tabel di tiap bagian) dan tampilkan `cause` hanya sebagai cadangan.
 ### Checklist rilis
 - [ ] Form setting outlet menampilkan cashback efektif dan contoh earning.
 - [ ] Setting organisasi selalu lewat dry run dan dialog konfirmasi sebelum disimpan.
 - [ ] Dialog konfirmasi menampilkan `impact` saat nilai EnakPoint atau kurs berubah.
 - [ ] Dialog konfirmasi menampilkan `expiry_activations` saat kedaluwarsa dinyalakan pertama kali.
 - [ ] Preview "yang didapat hari ini kedaluwarsa pada …" tampil di bawah pengaturan kedaluwarsa.
 - [ ] Wallet customer menampilkan saldo yang bisa dipakai, lot, dan riwayat dengan nama asli.
 - [ ] Adjustment mewajibkan alasan dan mengirim `idempotency_key`.
 - [ ] Tombol Telusuri ada di setiap baris riwayat.
 - [ ] Hapus PIN mewajibkan alasan; tab Keamanan menampilkan log.
 - [ ] Form game EnakGame punya input `entry_cost`.
 - [ ] Semua nilai rupiah EnakPoint ditulis "setara potongan Rp …".
 Transfer belum boleh dirilis sebelum tinjauan legal (N3) selesai. Layar backoffice boleh disiapkan lebih dulu.
@@ -1,86 +0,0 @@
 # Spin sebagai Game EnakGame
 **Sumber:** [RFC EnakGame](rfc-enakgame.md) §14, task EG-1001
 **Pembaca:** admin organisasi dan tim backoffice / aplikasi customer
 Spin lama (`POST /customer/spin`) diganti dengan game EnakGame biasa: tipe `SPIN`,
 reward `PROBABILITY`, hadiah berupa EnakCoin. Spin dimainkan lewat endpoint session
 yang sama dengan game lain, sehingga ikut mendapat idempotency, refund otomatis, budget,
 event, dan Economy Guard.
 Tidak ada seeder: setiap organisasi membuat spin-nya sendiri lewat API admin di bawah.
 Semua langkah memakai token admin organisasi; langkah 2–4 butuh loyalty manager.
 ## Langkah Admin
 ### 1. Buat game
 `POST /api/v1/marketing/enakgame/games`
 ```json
 {
  "name": "Spin Harian",
  "slug": "spin",
  "type": "SPIN",
  "entry_cost": 5,
  "status": "ACTIVE",
  "thumbnail_url": "https://…/spin.png",
  "game_url": "https://…/spin/index.html"
 }
 ```
 `entry_cost` adalah EnakCoin yang dipotong setiap kali spin (minimal 1).
 ### 2. Buat reward config `PROBABILITY`
 `POST /api/v1/marketing/enakgame/games/:id/reward-configs`
 ```json
 {
  "reward_type": "PROBABILITY",
  "max_reward": 50,
  "rules": {
    "table": [
      { "weight": 50, "amount": 0,  "label": "Zonk" },
      { "weight": 30, "amount": 3,  "label": "3 Coin" },
      { "weight": 15, "amount": 10, "label": "10 Coin" },
      { "weight": 5,  "amount": 50, "label": "Jackpot" }
    ]
  },
  "reason": "Spin pertama"
 }
 ```
 - Satu baris `table` = satu segmen roda, urut searah gambar roda.
 - `weight` bilangan bulat ≥ 1. Peluang segmen = `weight` ÷ total weight (di atas: 50%,
  30%, 15%, 5%). Weight tidak pernah dikirim ke customer.
 - `amount` EnakCoin yang didapat (boleh 0). `label` opsional, maksimal 100 karakter,
  ditampilkan di roda.
 - `max_reward` minimal sebesar `amount` terbesar, kalau tidak hadiah besar terpotong.
 ### 3. Aktifkan config
 `POST /api/v1/marketing/enakgame/reward-configs/:id/activate`
 Mengganti hadiah nanti berarti membuat versi config baru lalu mengaktifkannya; session
 yang sedang berjalan tetap memakai versi saat dimulai.
 ### 4. Pastikan ada budget global bulan berjalan
 `POST /api/v1/marketing/enakgame/budgets` dengan `scope: "GLOBAL"`, bila belum ada. Tanpa
 budget global, customer tidak bisa memulai game apa pun.
 ## Alur di Aplikasi Customer
 1. `GET /api/v1/customer/enakgame/games`: game spin punya `prizes`, yaitu segmen roda
   (`entry`, `label`, `amount`) dalam urutan config. Gambar roda dari sini.
 2. `POST /api/v1/customer/enakgame/sessions` dengan `{"game_id": "…"}` dan header
   `Idempotency-Key`. Entry cost dipotong di sini.
 3. `POST /api/v1/customer/enakgame/sessions/:id/complete` dengan body `{}`. Server yang
   mengundi. Response berisi `prize` (`entry`, `label`, `amount`): putar roda sampai
   berhenti di segmen `entry` itu. `reward_total` adalah Coin yang benar-benar masuk,
   bisa lebih besar dari `prize.amount` karena event, atau lebih kecil karena limit
   harian (`limited_by`).
 Aplikasi tidak boleh mengundi sendiri atau mengirim hadiah: apa pun yang dikirim selain
 data hasil diabaikan.
@@ -0,0 +1,930 @@
 # Integrasi Backoffice: Loyalitas & EnakGame
 **Untuk:** tim backoffice (dashboard owner/admin) · **Base URL:** `/api/v1` · **Per:** 8 Okt 2026
 Kamu mengerjakan **backoffice** yang dipakai owner, admin, dan manager organisasi untuk
 mengelola program loyalitas: pengaturan EnakPoint & EnakCoin, wallet customer, voucher,
 dan EnakGame (game, hadiah, budget, event, analytics). Jangan mengarang endpoint,
 field, atau aturan yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan ke
 tim backend.
 Dokumen ini menggantikan `backoffice-enakpoint.md`, bagian dashboard di
 `integration-enakpoint.md` dan `api-enakpoint.md`, serta langkah admin di
 `enakgame-spin.md`. Alasan di balik aturannya ada di
 [`prd-point-coin.md`](./prd-point-coin.md), [`enakgame-prd.md`](./enakgame-prd.md), dan
 [`rfc-enakgame.md`](./rfc-enakgame.md).
 ---
 ## 1. Konvensi
 **Akses.** Semua endpoint butuh login user dan otomatis dibatasi ke organisasi user itu;
 data organisasi lain dijawab `404`.
 | Aksi | Role |
 |---|---|
 | Membaca semua data di dokumen ini, serta membuat/mengubah game | superadmin, admin, manager, owner, purchasing |
 | Mengubah reward config, budget, event, voucher, dan menerima rekomendasi | superadmin, admin, manager, owner (**loyalty manager**) |
 Sembunyikan tombol ubah untuk role yang tidak boleh; server tetap menolaknya (`403`).
 **Format response.** Sukses `{ "success": true, "data": … }`; gagal
 `{ "success": false, "errors": [{ "code", "entity", "cause" }] }`. Contoh response di
 dokumen ini adalah isi `data`. Daftar berhalaman isinya
 `{ "data": [ … ], "pagination": { "page", "limit", "total_count", "total_pages" } }`,
 jadi pada response mentah array-nya ada di `data.data`; `limit` maks. 100 (default 20).
 **Istilah di layar.** EnakPoint (`POINT`) adalah saldo yang hanya bisa ditukar ke
 voucher, bukan alat bayar; EnakCoin (`COIN`) untuk main game dan bisa ditukar ke
 EnakPoint. Nilai rupiah EnakPoint selalu ditulis "setara potongan Rp …", tidak pernah
 "saldo Rp …", karena saldo tidak bisa dicairkan.
 **Body ketat.** Endpoint EnakGame dan voucher (`/marketing/enakgame/*`, `/marketing/vouchers/*`) serta `PUT` setting menolak
 field yang tidak dikenal (`310`), supaya salah ketik tidak diam-diam diabaikan. Pada
 `PUT`, field yang tidak dikirim tetap memakai nilai sekarang.
 ---
 ## 2. Layar yang perlu dibuat
 | Layar | Endpoint | Tempat di menu (usulan) |
 |---|---|---|
 | Setting loyalitas outlet | `GET` / `PUT /outlets/:outlet_id/loyalty-settings` | Outlet → detail → tab Loyalitas |
 | Setting loyalitas organisasi | `GET` / `PUT /marketing/loyalty-settings` (+ `?dry_run=true`) | Marketing → Loyalitas → Pengaturan |
 | Riwayat perubahan setting | `GET /marketing/loyalty-settings/history` | Marketing → Loyalitas → Riwayat |
 | Wallet customer | `GET /marketing/customers/:id/wallet`, `POST …/wallet/adjust` | Customer → detail → tab Wallet |
 | Telusuri mutasi | `GET /marketing/wallet-transactions/:id/trace` | Dari baris riwayat wallet |
 | PIN & keamanan customer | `DELETE /marketing/customers/:id/pin`, `GET …/security-events` | Customer → detail → tab Keamanan |
 | Game | `/marketing/enakgame/games` | EnakGame → Game |
 | Hadiah game (reward config) | `/marketing/enakgame/games/:id/reward-configs`, `/reward-configs/:id/activate` | EnakGame → Game → tab Hadiah |
 | Budget + metrik + rekomendasi | `/marketing/enakgame/budgets` | EnakGame → Budget |
 | Event | `/marketing/enakgame/events` | EnakGame → Event |
 | Voucher + kode | `/marketing/vouchers` | Marketing → Voucher |
 | Analytics | `/marketing/enakgame/analytics/games`, `/analytics/economy` | EnakGame → Analytics |
 ---
 ## 3. Setting loyalitas outlet
 Tiap outlet mengatur sendiri berapa EnakPoint dan EnakCoin yang didapat dari order. Semua
 nilai default mati sampai owner menyalakannya.
 `GET /outlets/:outlet_id/loyalty-settings` → isi form. `PUT` ke path yang sama dengan
 objek yang sama untuk menyimpan.
 ```json
 {
  "point": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 100, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null },
  "coin": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 25000, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null }
 }
 ```
 | Field | Label usulan | Tipe | Default | Validasi |
 | --- | --- | --- | --- | --- |
 | `point.enabled` / `coin.enabled` | Beri EnakPoint / EnakCoin | toggle | mati | – |
 | `earn_mode` | Cara hitung: per nominal / persentase | `PER_AMOUNT` / `PERCENTAGE` | `PER_AMOUNT` | salah satu dari keduanya |
 | `earn_per_amount` | Setiap belanja Rp … (mode `PER_AMOUNT`) | Rp | 100 (point), 25.000 (coin) | > 0 |
 | `earn_value` | … mendapat (mode `PER_AMOUNT`) | angka | 1 | ≥ 0 |
 | `earn_percent` | … % dari belanja (mode `PERCENTAGE`) | %, boleh desimal | 1 | 0–100, maks. 2 angka desimal |
 | `min_order_amount` | Minimal belanja | Rp | 0 | ≥ 0 |
 | `max_per_order` | Maksimal per order | angka, boleh kosong | kosong = tanpa batas | ≥ 0 |
 **Cashback efektif.** Response membawa `point_cashback_percent` dan `point_value`.
 Tampilkan persentase di samping field earning EnakPoint, mis. "setara cashback 1%", dan
 hitung ulang di sisi klien saat owner mengetik: `earn_value × point_value ÷
 earn_per_amount × 100`, atau pada mode `PERCENTAGE`: `earn_percent × point_value`.
 **Mode earning.** Tampilkan hanya field mode yang dipilih. Field mode lain tetap
 tersimpan di server. Pada mode `PERCENTAGE` jumlahnya `floor(basis × earn_percent ÷
 100)`, mis. 2,5% dari Rp 87.500 = 2.187 EnakPoint.
 **Contoh di bawah form.** "Belanja Rp 87.500 mendapat 875 EnakPoint dan 3 EnakCoin."
 Earning dihitung dari subtotal setelah diskon, sebelum pajak.
 Setelah `PUT`, response membawa `changes` (key yang berubah); tampilkan toast singkat.
 ---
 ## 4. Setting loyalitas organisasi
 Nilai rupiah EnakPoint, kurs exchange, batas transfer, kedaluwarsa, dan batas hadiah
 EnakGame berlaku sama untuk semua outlet. Mengubah nilai EnakPoint atau kurs langsung
 mengubah daya beli semua saldo customer, jadi layar ini wajib menampilkan dampaknya
 sebelum disimpan.
 ```json
 {
  "point_value": 1,
  "exchange": { "coin_amount": 1, "point_amount": 1 },
  "transfer": { "enabled": true, "min_amount": 1, "max_per_transaction": null, "daily_limit": null },
  "point_expiry": { "…": "lihat §5" },
  "coin_expiry": { "…": "lihat §5" },
  "enakgame": { "user_daily_limit": 0, "global_daily_limit": 0 }
 }
 ```
 | Field | Label usulan | Default | Validasi |
 | --- | --- | --- | --- |
 | `point_value` | Nilai 1 EnakPoint (Rp) | 1 | ≥ 1 |
 | `exchange.coin_amount` : `exchange.point_amount` | Kurs tukar: … EnakCoin = … EnakPoint | 1 : 1 | keduanya ≥ 1 |
 | `transfer.enabled` | Izinkan transfer antar customer | aktif | – |
 | `transfer.min_amount` | Minimal per transfer | 1 | ≥ 1 |
 | `transfer.max_per_transaction` | Maksimal per transfer | kosong = tanpa batas | ≥ 1 |
 | `transfer.daily_limit` | Batas harian per customer | kosong = tanpa batas | ≥ 1, per currency, reset tengah malam WIB |
 | `enakgame.user_daily_limit` | Maks. EnakCoin dari EnakGame per customer per hari | 0 = tanpa batas | ≥ 0, reset tengah malam WIB |
 | `enakgame.global_daily_limit` | Maks. EnakCoin dari EnakGame seluruh organisasi per hari | 0 = tanpa batas | ≥ 0, reset tengah malam WIB |
 Hadiah yang melewati batas harian **dipotong ke sisa batas**, tidak dibatalkan; bila
 sisanya 0, hadiahnya 0. Batas per game ada di `result_rules.daily_reward_limit` (§8.3).
 ### 4.1 Alur simpan
 1. Owner mengubah form.
 2. Tombol Simpan memanggil `PUT /marketing/loyalty-settings?dry_run=true` dengan objek
   yang diubah. Tidak ada yang tersimpan.
 3. Bila `changes` kosong, beri tahu "tidak ada perubahan" dan berhenti.
 4. Tampilkan dialog konfirmasi berisi `changes`, `impact` (bila `point_value` atau kurs
   berubah), dan `expiry_activations` (bila ada, §5).
 5. Konfirmasi memanggil `PUT` yang sama tanpa `dry_run`.
 ### 4.2 Dialog dampak
 | Field `impact` | Tampilkan sebagai |
 | --- | --- |
 | `outstanding_points` | EnakPoint beredar |
 | `point_rupiah_before` → `point_rupiah_after` | Setara potongan Rp … → Rp … |
 | `outstanding_coins` | EnakCoin beredar |
 | `coins_as_points_before` → `coins_as_points_after` | Bila semua ditukar: … EnakPoint → … EnakPoint |
 | `coin_rupiah_before` → `coin_rupiah_after` | Setara potongan Rp … → Rp … |
 Contoh: "Menaikkan nilai EnakPoint dari Rp 1 ke Rp 2 membuat 1.250.000 EnakPoint yang
 beredar setara potongan Rp 2.500.000 (sebelumnya Rp 1.250.000)." Perubahan hanya
 berlaku ke depan: exchange yang sudah terjadi memakai kurs saat itu.
 ---
 ## 5. Pengaturan kedaluwarsa
 Kedaluwarsa diatur terpisah untuk EnakPoint (`point_expiry`) dan EnakCoin
 (`coin_expiry`). Defaultnya mati; bila dinyalakan, defaultnya hangus setiap 31 Desember.
 ```json
 "point_expiry": {
  "enabled": true,
  "mode": "FIXED_DATE",
  "fixed_dates": ["12-31"],
  "grace_months": 3,
  "period": 12,
  "unit": "MONTH",
  "end_of_month": false,
  "reminder_days": 7
 }
 ```
 | Field | Tampil saat | Label usulan | Validasi |
 | --- | --- | --- | --- |
 | `enabled` | selalu | Saldo bisa kedaluwarsa | – |
 | `mode` | aktif | Model: Tanggal tetap / Sejak didapat | `FIXED_DATE` atau `ROLLING` |
 | `fixed_dates` | `FIXED_DATE` | Tanggal hangus setiap tahun | minimal satu, `MM-DD`, `02-29` ditolak |
 | `grace_months` | `FIXED_DATE` | Periode tanggung (bulan) | 0–24, default 3 |
 | `period` + `unit` | `ROLLING` | Berlaku selama … hari/bulan | period ≥ 1, `DAY` atau `MONTH` |
 | `end_of_month` | `ROLLING` | Bulatkan ke akhir bulan | – |
 | `reminder_days` | aktif | Ingatkan customer … hari sebelumnya | ≥ 0, 0 = tanpa pengingat |
 **Tanggal tetap (`FIXED_DATE`).** Semua saldo hangus di tanggal yang sama. Saldo yang
 didapat kurang dari `grace_months` sebelum tanggal itu ikut ke tanggal berikutnya: saldo
 1 Oktober dengan tanggung 3 bulan hangus 31 Desember tahun depan. Pakai pemilih
 tanggal+bulan tanpa tahun.
 **Sejak didapat (`ROLLING`).** Tiap saldo berlaku `period` hari atau bulan sejak masuk.
 Dengan `end_of_month`, saldo yang didapat 14 Maret 2026 hangus 31 Maret 2027.
 **Preview.** `GET`, `PUT`, dan dry run membawa `expiry_preview.point` dan `.coin`:
 kapan saldo yang didapat sekarang kedaluwarsa (`null` = tidak). Tampilkan "EnakPoint
 yang didapat hari ini kedaluwarsa pada 31 Des 2026." Dry run bisa dipakai untuk
 memperbarui preview saat owner mengubah pilihan.
 **Menyalakan pertama kali.** Saldo lama yang belum punya tanggal ikut diberi tanggal
 dengan masa berlaku penuh. Dry run mengembalikan `expiry_activations` (`currency`,
 `lots`, `amount`, `expires_at`); tampilkan di dialog konfirmasi dengan kalimat tegas,
 mis. "1.250.000 EnakPoint milik customer akan kedaluwarsa pada 31 Des 2027. Tindakan ini
 tidak bisa dibatalkan dengan mematikan kedaluwarsa."
 Aturan lain yang perlu dijelaskan di layar:
 - Mengubah model atau masa berlaku hanya berlaku untuk saldo yang masuk setelahnya.
 - Mematikan kedaluwarsa tidak membatalkan tanggal yang sudah terjadwal.
 - Saldo yang ditransfer atau ditukar membawa tanggal kedaluwarsa aslinya.
 - Saldo hangus tanpa kompensasi. Customer mendapat push `reminder_days` hari sebelumnya
  dan saat hangus.
 ---
 ## 6. Wallet customer
 Tab Wallet di detail customer dipakai untuk menangani komplain: melihat saldo dan
 asal-usulnya, mengoreksi saldo, dan menelusuri satu mutasi sampai ke asalnya.
 ### 6.1 Saldo, lot, dan riwayat
 `GET /marketing/customers/:id/wallet?page=1&limit=20&currency=POINT&type=TRANSFER_OUT,EARN&from=2026-09-01&to=2026-09-30`
 (semua query opsional; tanggal WIB, inklusif)
 ```json
 {
  "customer": { "id": "…", "name": "Budi Santoso", "phone": "081234561234" },
  "point_balance": 12650,
  "coin_balance": 8,
  "spendable_point_balance": 12500,
  "spendable_coin_balance": 8,
  "lots": [
    { "id": "…", "currency": "POINT", "original_amount": 875, "remaining_amount": 875, "expires_at": "2026-12-31T23:59:59+07:00", "expired": false, "source_transaction_id": "…", "origin_lot_id": null, "created_at": "…" }
  ],
  "transactions": {
    "data": [
      {
        "id": "…", "currency": "POINT", "type": "TRANSFER_OUT", "amount": -120, "balance_after": 12650,
        "description": "Transfer ke An*** (08**-****-5678)",
        "destination": { "type": "WALLET_TX", "id": "…" },
        "counterparty": { "id": "…", "name": "Anita Rahma" },
        "created_by": null, "outlet": null, "reason": null, "metadata": {},
        "created_at": "…"
      }
    ],
    "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 }
  }
 }
 ```
 - **Saldo:** tampilkan `spendable_*` sebagai saldo utama. `point_balance` /
  `coin_balance` bisa sedikit lebih besar selama ada lot yang lewat tanggal tapi belum
  diproses job kedaluwarsa (paling lama sekitar 15 menit).
 - **Lot:** paket saldo yang masih berisi, urut dari yang paling cepat kedaluwarsa. Tandai
  `expired: true`.
 - **Riwayat:** ditambah nama asli yang disamarkan untuk customer: `counterparty`,
  `created_by` (admin pelaku adjustment), `outlet`, `reason`, dan `metadata`.
 | `type` | Mata uang | Label | `source` / `destination` |
 |---|---|---|---|
 | `EARN` / `EARN_REVERSAL` | keduanya | Dari belanja / Ditarik (void/refund) | `ORDER` |
 | `EXCHANGE_OUT` / `EXCHANGE_IN` | COIN / POINT | Tukar EnakCoin ke EnakPoint | `WALLET_TX` (baris pasangannya) |
 | `TRANSFER_OUT` / `TRANSFER_IN` | keduanya | Transfer antar customer | `WALLET_TX` (baris pasangannya) |
 | `GAME_SPEND` | COIN | Biaya main game | `GAME_SESSION` (data lama: `GAME_PLAY`) |
 | `GAME_SPEND_REFUND` | COIN | Biaya main dikembalikan | `GAME_SESSION` |
 | `GAME_REWARD` | COIN | Hadiah game (`metadata.budget_id`: budget yang membayar) | `GAME_SESSION` |
 | `REWARD_REDEEM` | POINT | Ditukar ke voucher | `REWARD_REDEMPTION` |
 | `REWARD_REDEEM_REFUND` | POINT | Penukaran voucher gagal, dikembalikan | `REWARD_REDEMPTION` |
 | `EXPIRE` | keduanya | Kedaluwarsa | `LOT` |
 | `ADJUSTMENT` | keduanya | Koreksi admin | `USER` |
 | `MIGRATION` | keduanya | Saldo dari sistem lama | `LEGACY_POINTS` / `LEGACY_TOKENS` |
 ### 6.2 Adjustment manual
 `POST /marketing/customers/:id/wallet/adjust`
 ```json
 { "currency": "POINT", "amount": -500, "reason": "Komplain #45", "idempotency_key": "adj-7f3c" }
 ```
 | Field | Aturan |
 | --- | --- |
 | `currency` | `POINT` atau `COIN` |
 | `amount` | Bertanda, tidak boleh 0. Positif menambah, negatif mengurangi |
 | `reason` | Wajib; tampil di riwayat customer sebagai "Koreksi oleh admin: …" |
 | `idempotency_key` | Opsional tapi disarankan: satu nilai saat dialog dibuka, supaya klik ganda tidak mengoreksi dua kali |
 Pengurangan yang melebihi saldo yang bisa dipakai ditolak `304`. Adjustment tambah
 mengikuti aturan kedaluwarsa organisasi. Response: `{ "transaction",
 "spendable_point_balance", "spendable_coin_balance", "replayed" }`. Beri catatan bahwa
 adjustment tidak disertai pembayaran uang, jadi alasan tidak boleh "pencairan".
 ### 6.3 Telusuri mutasi
 Tombol Telusuri di setiap baris riwayat memanggil
 `GET /marketing/wallet-transactions/:id/trace`.
 ```json
 {
  "transaction": { "id": "…", "customer": { "id": "…", "name": "Budi Santoso" }, "currency": "POINT", "type": "TRANSFER_OUT", "amount": -30, "description": "Transfer ke Ri*** (08**-****-9012)", "reference_type": "WALLET_TX", "reference_id": "…", "created_at": "…" },
  "lots": [
    {
      "amount": 30,
      "chain": [
        { "lot": { "id": "…", "expires_at": "…", "origin_lot_id": "…" }, "source": { "type": "TRANSFER_IN", "customer": { "name": "Budi Santoso" }, "description": "Transfer dari An*** (08**-****-5678)" } },
        { "lot": { "id": "…", "origin_lot_id": null }, "source": { "type": "EARN", "customer": { "name": "Anita Rahma" }, "reference_type": "ORDER", "reference_id": "…", "description": "Belanja #ORD-1 di Outlet Kemang" } }
      ]
    }
  ]
 }
 ```
 Tampilkan tiap `lots[]` sebagai rantai dari atas ke bawah: jumlah yang lewat lot itu,
 lalu setiap langkah `chain` dengan pemilik, tipe, dan deskripsinya. Langkah terakhir
 adalah asal pertama saldo, mis. `EARN`, `GAME_REWARD`, `ADJUSTMENT`, atau `MIGRATION`;
 bila `reference_type` = `ORDER`, jadikan tautan ke detail order. Mutasi keluar
 menampilkan lot yang dipakai; mutasi masuk menampilkan lot yang dibuatnya.
 ---
 ## 7. PIN dan riwayat setting
 ### 7.1 PIN & keamanan customer
 Admin tidak bisa membuat, mengganti, atau melihat PIN customer; satu-satunya aksi adalah
 menghapusnya (mis. customer ganti nomor HP), sehingga customer membuat PIN baru lewat OTP.
 - `DELETE /marketing/customers/:id/pin` dengan body `{ "reason": "Customer ganti nomor HP" }`.
  `reason` wajib; tampilkan dialog konfirmasi dengan input alasan.
 - `GET /marketing/customers/:id/security-events?page=1&limit=20` untuk tab Keamanan:
 ```json
 {
  "data": [
    { "id": "…", "event": "PIN_LOCKED", "actor_user": null, "reason": null, "ip_address": "103.10.0.7", "user_agent": "EnakApp/2.4 (Android 14)", "created_at": "…" }
  ],
  "pagination": { "page": 1, "limit": 20, "total_count": 5, "total_pages": 1 }
 }
 ```
 | `event` | Label usulan |
 | --- | --- |
 | `PIN_SET` | PIN dibuat |
 | `PIN_CHANGED` | PIN diganti |
 | `PIN_RESET` | PIN direset lewat OTP (transfer ditahan 24 jam) |
 | `PIN_FAILED` | PIN salah dimasukkan |
 | `PIN_LOCKED` | PIN terkunci 30 menit |
 | `PIN_REMOVED_BY_ADMIN` | PIN dihapus admin (`actor_user`, `reason` terisi) |
 ### 7.2 Riwayat perubahan setting
 `GET /marketing/loyalty-settings/history?page=1&limit=20` untuk setting organisasi;
 tambah `&outlet_id=…` untuk satu outlet.
 ```json
 { "id": "…", "organization_id": "…", "outlet_id": null, "key": "loyalty.point.value", "old_value": "1", "new_value": "2", "changed_by": "…", "created_at": "…" }
 ```
 `old_value` `null` berarti sebelumnya masih default. Tampilkan `key` dengan label yang
 sama seperti di form (mis. `loyalty.point.value` → "Nilai 1 EnakPoint",
 `enakgame.limit.user_daily` → "Maks. EnakCoin per customer per hari"), dan `changed_by`
 sebagai nama user.
 ---
 ## 8. EnakGame: game dan hadiah
 Semua game (spin, raffle, minigame) adalah game EnakGame: customer membayar `entry_cost`
 EnakCoin per main, dan hadiahnya EnakCoin yang dihitung server dari **reward config**
 game itu. Game client (Phaser) dibuat tim EnakGame dan di-host di `game_url`.
 ### 8.1 Game
 | Method | Path | Body / query |
 |---|---|---|
 | `POST` | `/marketing/enakgame/games` | Objek game |
 | `GET` | `/marketing/enakgame/games` | `?status=&search=&page=&limit=` (game `ARCHIVED` hanya tampil bila diminta lewat `status`) |
 | `GET` | `/marketing/enakgame/games/:id` | – |
 | `PUT` | `/marketing/enakgame/games/:id` | Field yang diubah saja; status tidak lewat sini |
 | `PUT` | `/marketing/enakgame/games/:id/status` | `{ "status": "INACTIVE", "reason": "…" }` |
 ```json
 {
  "name": "Spin Harian",
  "type": "SPIN",
  "slug": "spin",
  "description": "Putar roda setiap hari",
  "thumbnail_url": "https://…/spin.png",
  "game_url": "https://…/spin/index.html",
  "version": "1.2.0",
  "status": "DRAFT",
  "entry_cost": 5,
  "session_ttl_seconds": 600,
  "result_rules": { "max_score": 5000, "min_duration_seconds": 10, "daily_reward_limit": 10000 }
 }
 ```
 | Field | Label usulan | Validasi |
 |---|---|---|
 | `name` | Nama game | wajib, maks. 255 |
 | `type` | Jenis | `SPIN`, `RAFFLE`, `MINIGAME` (default `MINIGAME`) |
 | `slug` | Kode unik | huruf kecil, angka, tanda `-` tunggal, maks. 100, unik per organisasi |
 | `thumbnail_url`, `game_url` | Gambar, URL game | maks. 500; `game_url` dari tim EnakGame |
 | `version` | Versi game | maks. 50 |
 | `status` | Status awal | hanya saat buat: `DRAFT` (default), `ACTIVE`, `INACTIVE` |
 | `entry_cost` | Biaya main (EnakCoin) | ≥ 1; tidak ada game gratis |
 | `session_ttl_seconds` | Batas waktu satu main | 1–86.400 detik, default 600 |
 | `result_rules` | Validasi hasil (§8.3) | opsional |
 **Status game:**
 | `status` | Arti |
 |---|---|
 | `DRAFT` | Disiapkan, belum tampil di aplikasi |
 | `ACTIVE` | Tampil dan bisa dimainkan (butuh reward config aktif dan budget global, §9) |
 | `INACTIVE` | Disembunyikan. Session yang sedang berjalan direfund otomatis |
 | `ARCHIVED` | Pensiun permanen; tidak bisa diubah lagi. Game lama sebelum EnakGame berstatus ini |
 Mengubah `entry_cost` tidak memengaruhi session yang sudah berjalan.
 ### 8.2 Reward config (hadiah)
 Hadiah diatur sebagai **versi**: versi tidak pernah diedit; perubahan = versi baru, lalu
 diaktifkan. Satu game hanya punya satu versi `ACTIVE`; session memakai versi yang aktif
 saat dimulai.
 | Method | Path | Body |
 |---|---|---|
 | `GET` | `/marketing/enakgame/games/:id/reward-configs` | Semua versi, terbaru di atas |
 | `POST` | `/marketing/enakgame/games/:id/reward-configs` | `{ "reward_type", "rules", "max_reward", "effective_at", "reason" }` → versi baru `DRAFT` |
 | `POST` | `/marketing/enakgame/reward-configs/:id/activate` | `{ "reason": "…" }` → versi ini `ACTIVE`, versi aktif sebelumnya `RETIRED` |
 ```json
 {
  "id": "…", "game_id": "…", "version": 3, "reward_type": "FIXED", "rules": { "amount": 9 },
  "max_reward": 9, "status": "ACTIVE", "effective_at": "…", "created_by": "…", "reason": "…",
  "base_config_id": "…", "multiplier": 0.9, "budget_id": "…", "created_at": "…"
 }
 ```
 `base_config_id`, `multiplier`, dan `budget_id` hanya terisi pada versi yang dibuat
 Budget Controller (§9.3). Tampilkan badge "Disesuaikan Budget Controller × 0,90".
 Versi `RETIRED` tidak bisa diaktifkan lagi; untuk kembali, buat versi baru dengan aturan
 lama.
 **Empat jenis `reward_type`:**
 | `reward_type` | `rules` | Hasil yang dikirim game |
 |---|---|---|
 | `FIXED` | `{ "amount": 5 }` | Apa saja; selalu 5 |
 | `SCORE_BASED` | `{ "bands": [{ "min": 0, "max": 100, "amount": 1 }, { "min": 101, "amount": 20 }] }` | `score` |
 | `OUTCOME_BASED` | `{ "outcomes": { "PERFECT": 20, "GOOD": 10, "FAIL": 0 } }` | `outcome` |
 | `PROBABILITY` | `{ "table": [{ "weight": 1, "amount": 1000, "label": "Jackpot" }, { "weight": 999, "amount": 0, "label": "Zonk" }] }` | – (server mengundi) |
 - `SCORE_BASED`: band urut mulai dari 0, tanpa celah dan tanpa tumpang tindih; hanya band
  terakhir boleh tanpa `max`. Skor di luar semua band → hadiah 0.
 - `OUTCOME_BASED`: `outcome` yang tidak terdaftar → hadiah 0.
 - `PROBABILITY`: `weight` bilangan bulat ≥ 1; peluang = `weight` ÷ total weight.
  `label` opsional (maks. 100) dan tampil di roda spin. Customer melihat segmen dan
  hadiahnya, tidak pernah weight-nya.
 - Semua `amount` ≥ 0, EnakCoin bulat.
 - `max_reward`: batas atas hadiah **total** per main, termasuk tambahan event (§10).
  0 = tanpa batas. Bila lewat, yang dipotong lebih dulu adalah tambahan event dengan
  prioritas terendah.
 Tampilkan editor sesuai jenis (bukan textarea JSON) dan preview, mis. tabel peluang
 "Jackpot 0,1% · Zonk 99,9%" untuk `PROBABILITY`.
 ### 8.3 Validasi hasil (`result_rules`)
 Hasil dari game diperiksa server. Hasil yang tidak lolos tetap dicatat, tapi hadiahnya
 0 dan session ditandai mencurigakan.
 | Field | Arti |
 |---|---|
 | `max_score` | Skor maksimal yang masuk akal |
 | `min_duration_seconds` | Main lebih cepat dari ini dianggap curang |
 | `max_score_per_second` | Laju skor maksimal |
 | `outcomes` | Daftar `outcome` yang diterima; kosong = semua |
 | `daily_reward_limit` | Maks. EnakCoin yang boleh diberikan game ini per hari (seluruh customer) |
 Semua opsional. Isi bersama tim EnakGame, karena mereka tahu skor dan durasi wajar
 game-nya.
 ### 8.4 Membuat spin
 1. **Game:** `POST /marketing/enakgame/games` dengan
   `{ "name": "Spin Harian", "slug": "spin", "type": "SPIN", "entry_cost": 5, "status": "DRAFT", "thumbnail_url": "…", "game_url": "…" }`.
 2. **Hadiah:** `POST /marketing/enakgame/games/:id/reward-configs`:
   ```json
   {
     "reward_type": "PROBABILITY",
     "max_reward": 50,
     "rules": { "table": [
       { "weight": 50, "amount": 0,  "label": "Zonk" },
       { "weight": 30, "amount": 3,  "label": "3 Coin" },
       { "weight": 15, "amount": 10, "label": "10 Coin" },
       { "weight": 5,  "amount": 50, "label": "Jackpot" }
     ] },
     "reason": "Spin pertama"
   }
   ```
   Satu baris `table` = satu segmen roda, urut searah gambar roda. `max_reward` minimal
   sebesar `amount` terbesar; beri ruang lebih bila ingin event bisa menambah hadiah.
 3. **Aktifkan:** `POST /marketing/enakgame/reward-configs/:id/activate`.
 4. **Budget:** pastikan ada budget global bulan berjalan (§9.1).
 5. **Tayangkan:** `PUT /marketing/enakgame/games/:id/status` dengan `{ "status": "ACTIVE" }`.
 ---
 ## 9. Budget
 Budget adalah rupiah yang boleh dihabiskan organisasi untuk hadiah EnakGame. Biaya
 dihitung dari **voucher yang benar-benar ditukar**: saat customer menukar EnakPoint yang
 asalnya dari hadiah game (EnakCoin hadiah → ditukar ke EnakPoint → voucher), nilai
 voucher (`face_value`) dicatat sebagai biaya budget yang membayar hadiah itu. EnakPoint
 dari belanja tidak dihitung. Entry cost yang dibayar customer tidak menambah budget.
 ### 9.1 Budget global dan event
 | `scope` | Membayar | Aturan |
 |---|---|---|
 | `GLOBAL` | Hadiah dasar semua game | Satu per periode; periode tidak boleh tumpang tindih. **Tanpa budget global yang mencakup hari ini, customer tidak bisa mulai main.** Setiap hari sistem membuat budget bulan berikutnya dari budget yang sedang berjalan (jumlah dan threshold sama) bila belum ada |
 | `EVENT` | Tambahan hadiah dari satu event | Dipasang di event (§10) |
 | Method | Path | Body / query |
 |---|---|---|
 | `GET` | `/marketing/enakgame/budgets` | `?scope=GLOBAL&page=&limit=` |
 | `GET` | `/marketing/enakgame/budgets/:id` | – |
 | `POST` | `/marketing/enakgame/budgets` | Objek budget |
 | `PUT` | `/marketing/enakgame/budgets/:id` | Field yang diubah; `scope` tidak bisa berubah |
 | `DELETE` | `/marketing/enakgame/budgets/:id` | Hanya budget yang belum dipakai hadiah, event, atau reward config |
 ```json
 {
  "scope": "GLOBAL",
  "name": "Oktober 2026",
  "period_start": "2026-10-01",
  "period_end": "2026-10-31",
  "amount": 100000000,
  "thresholds": {
    "warning": 70, "critical": 90,
    "max_step_percent": 10, "min_multiplier_percent": 50, "max_multiplier_percent": 150, "cooldown_days": 7
  }
 }
 ```
 | Field | Label usulan | Validasi |
 |---|---|---|
 | `name` | Nama | wajib, maks. 255 |
 | `period_start`, `period_end` | Periode | `YYYY-MM-DD`, inklusif, akhir ≥ awal |
 | `amount` | Budget (Rp) | > 0 |
 | `thresholds.warning` / `.critical` | Ambang peringatan / kritis (%) | 0–100, warning ≤ critical; default 70 / 90 |
 | `thresholds.max_step_percent` | Maks. perubahan hadiah per rekomendasi (%) | 1–50; default 10 |
 | `thresholds.min_multiplier_percent` | Hadiah terendah (% dari yang ditulis admin) | 1–100; default 50 |
 | `thresholds.max_multiplier_percent` | Hadiah tertinggi (% dari yang ditulis admin) | 100–1000; default 150 |
 | `thresholds.cooldown_days` | Jeda antar rekomendasi diterima (hari) | 0–90; default 7 |
 Nilai default threshold dan guardrail masih **sementara**, menunggu keputusan bisnis
 (RFC §19.2 #4). Tampilkan default sebagai placeholder, bukan nilai yang tersimpan.
 ### 9.2 Metrik — `GET /marketing/enakgame/budgets/:id/metrics`
 ```json
 {
  "budget_id": "…", "scope": "GLOBAL", "period_start": "2026-10-01", "period_end": "2026-10-31",
  "as_of": "2026-10-21", "amount": 100000000,
  "realized_cost": 60000000, "remaining": 40000000, "utilization_percent": 60,
  "daily_burn": 5500000, "window_days": 7, "remaining_days": 10,
  "forecast_cost": 115000000, "forecast_remaining": -15000000, "forecast_utilization_percent": 115,
  "coin_issued": 1250000,
  "exposure": { "coins": 400000, "points": 90000 },
  "thresholds": { "warning": 70, "critical": 90 },
  "status": "CRITICAL"
 }
 ```
 | Field | Arti | Tampilkan sebagai |
 |---|---|---|
 | `realized_cost` | Biaya voucher yang sudah ditukar (Rp). Global: dalam periode; event: tanpa batas waktu | Terpakai |
 | `remaining`, `utilization_percent` | Sisa dan persen terpakai | Progress bar |
 | `daily_burn`, `window_days` | Rata-rata biaya per hari dalam `window_days` hari terakhir | Burn rate |
 | `forecast_cost`, `forecast_remaining` | Perkiraan biaya di akhir periode = realized + burn × `remaining_days` | Perkiraan; merah bila `forecast_remaining` negatif |
 | `coin_issued` | EnakCoin hadiah yang dibayar budget ini | – |
 | `exposure` | EnakCoin dan EnakPoint dari budget ini yang masih beredar: batas atas biaya yang masih bisa datang | "Masih bisa menjadi biaya" |
 | `status` | `HEALTHY`, `WARNING`, `CRITICAL`, `EXHAUSTED` | Badge hijau / kuning / oranye / merah |
 Status: `EXHAUSTED` bila realized ≥ budget; `CRITICAL` bila forecast melewati budget atau
 utilization/forecast ≥ critical; `WARNING` bila ≥ warning. Budget habis **belum
 menghentikan hadiah** (kebijakannya belum diputuskan), jadi tampilkan peringatan yang
 jelas.
 ### 9.3 Rekomendasi Budget Controller
 Untuk budget `GLOBAL`, sistem menghitung pengali hadiah supaya perkiraan biaya pas dengan
 budget. Tidak ada yang berubah sampai admin menerimanya.
 `GET /marketing/enakgame/budgets/:id/recommendation`
 ```json
 {
  "budget_id": "…",
  "state": "RECOMMENDED",
  "message": "forecast Rp115000000 against a budget of Rp100000000: multiply rewards by 0.90",
  "metrics": { "…": "sama seperti §9.2" },
  "guardrails": { "max_step_percent": 10, "min_multiplier_percent": 50, "max_multiplier_percent": 150, "cooldown_days": 7 },
  "target_multiplier": 0.7272,
  "multiplier": 0.9,
  "games": [
    {
      "game_id": "…", "game_name": "Tap Tap", "reward_config_id": "…", "version": 1, "base_config_id": "…",
      "reward_type": "FIXED", "current_multiplier": 1, "new_multiplier": 0.9,
      "current_rules": { "amount": 10 }, "new_rules": { "amount": 9 },
      "current_max_reward": 10, "new_max_reward": 9
    }
  ]
 }
 ```
 | `state` | Arti | Tampilan |
 |---|---|---|
 | `RECOMMENDED` | Ada rekomendasi yang bisa diterima | Tombol Terima aktif |
 | `NO_CHANGE` | Perkiraan sudah pas | "Hadiah tidak perlu diubah" |
 | `COOLDOWN` | Rekomendasi diterima kurang dari `cooldown_days` lalu | "Bisa diterima lagi pada {cooldown_until}"; tampilkan `games` sebagai gambaran |
 | `AT_LIMIT` | Semua game sudah di batas min/max | "Hadiah sudah di batas terendah/tertinggi" |
 | `INSUFFICIENT_DATA` | Belum ada biaya dalam `window_days` hari terakhir | "Belum cukup data" |
 | `OUT_OF_PERIOD` | Periode belum mulai atau tidak ada hari tersisa | "Periode tidak berjalan" |
 - `target_multiplier`: pengali yang membuat perkiraan pas dengan budget; `multiplier`:
  yang direkomendasikan, dibatasi `max_step_percent` dari 1 dan dibulatkan ke bawah ke
  dua desimal. Bisa di bawah 1 (hadiah turun) atau di atas 1 (hadiah naik).
 - `games`: perubahan per game. Pengali tiap game dihitung dari versi yang ditulis admin
  (`base_config_id`), dan dibatasi `min_multiplier_percent`–`max_multiplier_percent`.
  Semua jumlah dibulatkan ke bawah, jadi hadiah kecil bisa menjadi 0 (1 × 0,9 = 0).
  Tampilkan `current_rules` → `new_rules` berdampingan supaya admin melihatnya.
 - Budget `EVENT` ditolak (`304`): tambahan event diatur di event.
 **Terima:** `POST /marketing/enakgame/budgets/:id/recommendation/accept`
 ```json
 { "multiplier": 0.9, "reason": "Burn rate terlalu tinggi" }
 ```
 - Kirim `multiplier` yang ditampilkan. Bila rekomendasi sudah berubah sejak layar dibuka,
  server menolak (`304`) dan tidak mengubah apa pun: muat ulang rekomendasi.
 - Berhasil: setiap game di `games` mendapat versi reward config baru yang langsung
  `ACTIVE`, versi lama `RETIRED`. Response
  `{ "budget_id", "multiplier", "reward_configs": [ … ] }`.
 - Tercatat di audit dengan sumber Budget Controller. Mulai saat itu cooldown berlaku untuk
  seluruh organisasi.
 - Admin yang menulis versi baru sendiri untuk sebuah game memulai pengalinya dari 1 lagi.
 ---
 ## 10. Event
 Event (= campaign) membuat game tertentu memberi hadiah lebih selama periode tertentu.
 Tambahannya dibayar budget `EVENT` milik event itu.
 | Method | Path | Body / query |
 |---|---|---|
 | `GET` | `/marketing/enakgame/events` | `?status=&page=&limit=` |
 | `GET` | `/marketing/enakgame/events/:id` | – |
 | `POST` | `/marketing/enakgame/events` | Objek event |
 | `PUT` | `/marketing/enakgame/events/:id` | Field yang diubah |
 | `PUT` | `/marketing/enakgame/events/:id/status` | `{ "status": "ENDED", "reason": "…" }` |
 ```json
 {
  "name": "Ramadan 2x",
  "slug": "ramadan-2x",
  "description": "Hadiah dobel selama Ramadan",
  "banner_url": "https://…/ramadan.png",
  "start_at": "2027-02-17T00:00:00+07:00",
  "end_at": "2027-03-18T23:59:59+07:00",
  "timezone": "Asia/Jakarta",
  "priority": 10,
  "multiplier": 2,
  "bonus": null,
  "budget_id": "<id budget EVENT>",
  "reward_limit": 5000000,
  "user_daily_limit": 200,
  "game_ids": ["…", "…"],
  "status": "DRAFT"
 }
 ```
 | Field | Arti | Validasi |
 |---|---|---|
 | `start_at`, `end_at` | Periode berlaku | wajib, akhir setelah awal |
 | `timezone` | Zona waktu untuk tampilan | default `Asia/Jakarta` |
 | `multiplier` | Pengali hadiah dasar: 2 = hadiah dasar ditambah sekali lagi | ≥ 1, maks. 2 desimal |
 | `bonus` | Tambahan EnakCoin per main | ≥ 1 |
 | | | Minimal salah satu: `multiplier` > 1 atau `bonus` |
 | `priority` | Urutan bila beberapa event berlaku | angka lebih besar didahulukan |
 | `budget_id` | Budget `EVENT` organisasi ini | wajib |
 | `reward_limit` | Maks. tambahan EnakCoin selama event | ≥ 1, kosong = tanpa batas |
 | `user_daily_limit` | Maks. tambahan per customer per hari | ≥ 1, kosong = tanpa batas |
 | `game_ids` | Game yang ikut | minimal satu game organisasi ini |
 | `status` | Status awal | hanya saat buat: `DRAFT` (default) atau `ACTIVE` |
 **Status:** `DRAFT` → `ACTIVE` atau `CANCELLED`; `ACTIVE` → `ENDED` atau `CANCELLED`.
 Event `ACTIVE` hanya berlaku di antara `start_at` dan `end_at`.
 **Beberapa event sekaligus.** Tambahan setiap event dihitung dari hadiah dasar (tidak
 saling mengalikan), lalu dijumlahkan. Bila total melewati `max_reward` game, tambahan
 event berprioritas terendah dipotong lebih dulu. Main yang hadiah dasarnya 0 tidak
 mendapat tambahan event. Contoh: hadiah dasar 10, event 2x → 10 dari budget global +
 10 dari budget event.
 ---
 ## 11. Voucher
 Voucher adalah satu-satunya cara memakai EnakPoint: customer menukar EnakPoint
 (`point_cost`) dengan voucher di aplikasi, memakai PIN. Voucher berdiri sendiri, tidak
 di bawah EnakGame: EnakPoint dari belanja pun ditukar di sini. Hubungannya dengan EnakGame
 hanya di budget: bila EnakPoint yang ditukar berasal dari hadiah game, nilai vouchernya
 dicatat sebagai biaya budget (§9).
 ### 11.1 Voucher
 | Method | Path | Body / query |
 |---|---|---|
 | `GET` | `/marketing/vouchers` | `?status=&search=&page=&limit=` |
 | `GET` | `/marketing/vouchers/:id` | – |
 | `POST` | `/marketing/vouchers` | Objek voucher |
 | `PUT` | `/marketing/vouchers/:id` | Field yang diubah; `stock_mode` tidak bisa berubah |
 | `PUT` | `/marketing/vouchers/:id/status` | `{ "status": "ACTIVE", "reason": "…" }` |
 ```json
 {
  "name": "Kopi Susu Gratis",
  "description": "Berlaku untuk ukuran regular",
  "image_url": "https://…/kopi.png",
  "voucher_type": "FREE_ITEM",
  "face_value": 20000,
  "point_cost": 15000,
  "business_cost": 8000,
  "stock_mode": "CODE_POOL",
  "max_per_customer": 2,
  "valid_from": "2026-10-01T00:00:00+07:00",
  "valid_until": "2026-12-31T23:59:59+07:00",
  "terms": { "outlets": "Semua outlet", "notes": "Tidak bisa digabung promo lain" },
  "status": "DRAFT"
 }
 ```
 | Field | Arti | Validasi |
 |---|---|---|
 | `voucher_type` | Jenis | `FIXED_VALUE`, `PERCENTAGE`, `FREE_ITEM`, `MERCHANT_BENEFIT` |
 | `face_value` | Nilai voucher (Rp); **dihitung sebagai biaya budget** | > 0 |
 | `point_cost` | EnakPoint yang dibayar customer | > 0 |
 | `business_cost` | Biaya sebenarnya untuk laporan Finance; tidak dipakai budget | ≥ 0, opsional |
 | `stock_mode` | Asal voucher (lihat bawah) | `STATIC`, `CODE_POOL`, `EXTERNAL` |
 | `stock` | Stok, hanya `STATIC` | wajib untuk `STATIC`, ≥ 0 |
 | `provider`, `provider_ref` | Hanya `EXTERNAL` | `provider` wajib untuk `EXTERNAL` |
 | `max_per_customer` | Batas tukar per customer | ≥ 1, kosong = tanpa batas |
 | `valid_from`, `valid_until` | Masa bisa ditukar | akhir setelah awal |
 | `terms` | Syarat & ketentuan | objek JSON; sepakati bentuknya dengan tim aplikasi |
 | `status` | Status awal | hanya saat buat: `DRAFT` (default), `ACTIVE`, `INACTIVE` |
 | `stock_mode` | Cara kerja |
 |---|---|
 | `STATIC` | Stok berupa angka; customer mendapat voucher tanpa kode |
 | `CODE_POOL` | Setiap penukaran mengambil satu kode yang diimpor (§11.2); stok = kode `AVAILABLE` |
 | `EXTERNAL` | Kode dari penyedia luar. **Belum bisa dipakai**: belum ada penyedia yang tersambung, jadi voucher ini tidak tampil di katalog customer |
 **Status:** `DRAFT`, `ACTIVE` (tampil di katalog selama dalam masa berlaku dan ada stok),
 `INACTIVE`, `ARCHIVED` (permanen, tidak bisa diubah lagi).
 ### 11.2 Kode voucher (`CODE_POOL`)
 **Impor:** `POST /marketing/vouchers/:id/codes` dengan file CSV sebagai
 multipart field `file` (atau CSV sebagai body).
 ```csv
 code,expires_at
 KOPI-7F3C-2291,2026-12-31
 KOPI-8A1D-5530,
 ```
 - Kolom 1: kode (wajib, maks. 255). Kolom 2: kedaluwarsa, opsional, `YYYY-MM-DD`
  (berlaku sampai akhir hari WIB) atau RFC3339. Baris header `code` boleh ada.
 - Maks. 50.000 baris dan 16 MB per file. Kode yang sudah ada di pool atau berulang di file
  dilewati.
 ```json
 { "imported": 1998, "duplicate_count": 1, "duplicates": ["KOPI-7F3C-2291"], "invalid": [{ "line": 17, "reason": "…" }] }
 ```
 Tampilkan ringkasan: berapa masuk, berapa duplikat, dan baris yang gagal dengan nomor
 barisnya.
 **Daftar:** `GET /marketing/vouchers/:id/codes?status=AVAILABLE&page=1&limit=20`
 ```json
 {
  "counts": { "AVAILABLE": 1500, "REDEEMED": 480, "EXPIRED": 20 },
  "codes": { "data": [ { "id": "…", "code": "KOPI-…", "status": "AVAILABLE", "redemption_id": null, "expires_at": "…", "created_at": "…" } ], "pagination": { "…": "…" } }
 }
 ```
 Status kode: `AVAILABLE`, `RESERVED`, `REDEEMED`, `EXPIRED` (lewat `expires_at`,
 diproses tiap jam), `CANCELLED`. Tampilkan `counts` sebagai ringkasan stok di atas tabel,
 dan peringatan bila `AVAILABLE` hampir habis.
 ---
 ## 12. Analytics
 Rentang tanggal WIB, kedua ujung termasuk, maks. 366 hari. `from` dan `to` wajib.
 ### 12.1 Game — `GET /marketing/enakgame/analytics/games?from=2026-10-01&to=2026-10-31&game_id=`
 `game_id` opsional untuk satu game. Dihitung dari session yang **dimulai** dalam
 rentang.
 ```json
 {
  "from": "2026-10-01", "to": "2026-10-31",
  "totals": {
    "plays": 4200, "completed": 3900, "refunded": 12, "expired": 288, "flagged": 35, "players": 820,
    "average_score": 742.5, "average_reward": 6.2, "reward_per_play": 5.76,
    "coin_issued": 24180, "entry_cost_paid": 21000, "coin_refunded": 60
  },
  "games": [ { "game_id": "…", "game_name": "Spin Harian", "plays": 3000, "…": "field sama dengan totals" } ]
 }
 ```
 | Field | Label usulan |
 |---|---|
 | `plays` | Total main |
 | `completed`, `refunded`, `expired` | Selesai / dikembalikan / tidak selesai |
 | `flagged` | Hasil mencurigakan (gagal validasi, hadiah 0) |
 | `players` | Customer unik |
 | `average_score` | Rata-rata skor (`null` bila game tidak memakai skor) |
 | `average_reward`, `reward_per_play` | Rata-rata hadiah per main selesai / per main |
 | `coin_issued` | EnakCoin hadiah |
 | `entry_cost_paid`, `coin_refunded` | EnakCoin dibayar untuk main / dikembalikan |
 `games` urut dari yang paling banyak dimainkan.
 ### 12.2 Ekonomi — `GET /marketing/enakgame/analytics/economy?from=2026-10-01&to=2026-10-31`
 Dihitung dari semua mutasi wallet organisasi dalam rentang.
 ```json
 {
  "from": "2026-10-01", "to": "2026-10-31",
  "coin": { "generated": 52000, "game_rewards": 24180, "spent_on_games": 20940, "exchanged": 9000, "spent": 29940, "expired": 300, "outstanding": 61000 },
  "point": { "earned": 1800000, "exchanged": 2700, "redeemed": 900000, "expired": 15000, "balance": 4200000 },
  "by_type": [ { "currency": "COIN", "type": "GAME_REWARD", "credit": 24180, "debit": 0, "transactions": 3900 } ]
 }
 ```
 | Field | Arti |
 |---|---|
 | `coin.generated` | EnakCoin baru: hadiah game, belanja (dikurangi pembatalan), migrasi, adjustment tambah |
 | `coin.spent_on_games` | Entry cost dikurangi yang dikembalikan |
 | `coin.exchanged` | Ditukar ke EnakPoint |
 | `coin.outstanding` / `point.balance` | Dipegang customer di akhir rentang |
 | `point.earned` | Dari belanja, dikurangi pembatalan |
 | `point.exchanged` | Hasil tukar EnakCoin |
 | `point.redeemed` | Ditukar ke voucher, dikurangi penukaran yang gagal |
 | `by_type` | Rincian per tipe mutasi, termasuk transfer (yang tidak dihitung di angka utama) |
 ---
 ## 13. Belum tersedia
 Fitur berikut belum ada di backend; jangan dibuat layarnya dulu:
 - Daftar session main dan filter hasil mencurigakan (`flagged`) untuk admin.
 - Daftar penukaran voucher untuk admin.
 - Layar audit log (perubahan tetap tercatat di backend).
 - Kebijakan saat budget habis, dan mode otomatis Budget Controller.
 - Menandai voucher sudah dipakai di POS ([`integration-pos.md`](./integration-pos.md) §5).
 - Voucher `EXTERNAL` (belum ada penyedia).
 ---
 ## 14. Pesan error dan checklist
 | `code` | HTTP | Kapan terjadi | Yang ditampilkan |
 | --- | --- | --- | --- |
 | `303`, `310` | 400 | Body tidak valid, field tak dikenal, UUID salah | "Data tidak valid" + `cause` untuk developer |
 | `304` | 400 | Nilai di luar batas, aturan bisnis (slug terpakai, periode budget tumpang tindih, versi sudah pensiun, rekomendasi berubah, dst.) | `cause` di dekat field atau di toast |
 | – | 403 | Role tidak boleh mengubah (§1) | "Kamu tidak punya akses" |
 | `404` | 404 | Data bukan milik organisasi ini atau tidak ada | "Data tidak ditemukan" |
 | `900` | 500 | Kesalahan server | "Terjadi kesalahan, coba lagi" |
 Pesan `cause` berbahasa Inggris, mis. `thresholds.warning cannot be above
 thresholds.critical`. Cek batas di sisi klien (tabel di tiap bagian) dan tampilkan
 `cause` hanya sebagai cadangan.
 ### Checklist rilis
 **Loyalitas**
 - [ ] Form setting outlet menampilkan cashback efektif dan contoh earning.
 - [ ] Setting organisasi selalu lewat dry run dan dialog konfirmasi (`impact`, `expiry_activations`).
 - [ ] Preview kedaluwarsa tampil di bawah pengaturan kedaluwarsa.
 - [ ] Wallet customer: saldo yang bisa dipakai, lot, riwayat dengan nama asli, label semua tipe mutasi termasuk game dan voucher.
 - [ ] Adjustment mewajibkan alasan dan mengirim `idempotency_key`; Telusuri di setiap baris.
 - [ ] Hapus PIN mewajibkan alasan; tab Keamanan menampilkan log.
 - [ ] Semua nilai rupiah EnakPoint ditulis "setara potongan Rp …".
 **EnakGame**
 - [ ] Game: form lengkap, `entry_cost` ≥ 1, status, `result_rules`.
 - [ ] Reward config: editor per jenis, riwayat versi, aktivasi dengan alasan, badge versi Budget Controller.
 - [ ] Spin bisa dibuat end-to-end mengikuti §8.4.
 - [ ] Budget global per bulan, threshold dan guardrail, peringatan bila tidak ada budget global berjalan.
 - [ ] Metrik budget dengan status dan perkiraan; rekomendasi dengan perbandingan aturan lama/baru dan tombol Terima.
 - [ ] Event: form, status, budget `EVENT`, pilihan game.
 - [ ] Voucher: form per `stock_mode`, impor kode CSV dengan ringkasan, stok kode.
 - [ ] Analytics game dan ekonomi dengan pemilih rentang tanggal.
 - [ ] Tombol ubah disembunyikan untuk role yang bukan loyalty manager.
 Transfer antar customer belum boleh dirilis sebelum tinjauan legal (N3) selesai. Layar
 backoffice boleh disiapkan lebih dulu.
@@ -0,0 +1,664 @@
 # Integrasi EnakGame: Game Client (Phaser)
 **Untuk:** tim game EnakGame (client Phaser) · **Base URL:** `/api/v1` · **Per:** 12 Okt 2026
 Kamu mengerjakan **game EnakGame**: game web (Phaser) yang dibuka aplikasi customer di
 dalam webview dari `game_url` sebuah game. Game inilah yang menjalankan satu kali main
 dari awal sampai akhir: memulai session (EnakCoin dipotong), menjalankan permainan,
 mengirim hasil, dan menampilkan hadiah. Jangan mengarang endpoint, field, atau aturan
 yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan ke tim backend.
 Pembagian tugas dengan aplikasi customer:
 | Aplikasi customer ([`integration-mobile-customer.md`](./integration-mobile-customer.md)) | Game EnakGame (dokumen ini) |
 |---|---|
 | Login customer, menyimpan token | Menerima token dari aplikasi lewat bridge (§4); bila tidak ada, meminta customer login (§5) |
 | Daftar game, membuka `game_url` di webview | Start session, main, complete, tampilkan hadiah, leaderboard mingguan (§10) |
 | Saldo, riwayat, voucher, PIN | Memberi tahu aplikasi saat saldo berubah atau game ditutup |
 Alasan di balik aturannya ada di [`rfc-enakgame.md`](./rfc-enakgame.md) dan
 [`enakgame-prd.md`](./enakgame-prd.md).
 ---
 ## 1. Aturan yang tidak boleh dilanggar
 1. **Server yang menentukan hadiah.** Game hanya mengirim **hasil main**: `score`,
   `outcome`, dan `data`. Jangan pernah mengirim jumlah hadiah. Kalaupun terkirim,
   backend mengabaikannya. Untuk spin, server yang mengundi segmennya.
 2. **Tampilkan hadiah dari response, bukan dari hitungan sendiri.** Angka di layar akhir
   selalu `reward_total` dari backend.
 3. **Satu tap "Main" = satu `Idempotency-Key`.** Retry memakai key yang sama.
 4. **Token customer adalah rahasia.** Hanya didapat dari bridge atau dari login di
   game, disimpan di memori, tidak pernah ditaruh di URL, `localStorage`,
   `sessionStorage`, cookie, log, atau analytics. Begitu juga password customer.
   (`session_id` boleh disimpan di `sessionStorage`, §6.4.)
 5. **Tanpa token, jangan panggil API customer.** Tampilkan layar login akun customer
   (§5.2).
 6. **Semua jumlah bilangan bulat.** Tidak ada pecahan EnakCoin.
 7. **Main game tidak butuh PIN.**
 ---
 ## 2. Daftar game
 Game bukan daftar tetap di kode. Setiap game adalah data yang dibuat admin di
 backoffice per organisasi (nama, `slug`, `game_url`, biaya main, aturan hadiah) dan
 dibaca game lewat `GET /customer/enakgame/games` (§6.1). Satu `game_url` = satu game.
 ### 2.1 Game yang ada sekarang
 | Game | `slug` | Jenis hadiah (`reward_type`) | Body complete | Status |
 |---|---|---|---|---|
 | Spin Harian | `spin` | `PROBABILITY`: server mengundi segmen roda | `{}` | Backend siap. Panduan: §9 |
 Runner, Memory, dan Puzzle hanya disebut sebagai contoh di PRD; belum ada spesifikasi,
 `slug`, atau aturan hadiahnya. Game baru harus didaftarkan dulu (§2.3) sebelum bisa
 dimainkan.
 ### 2.2 Jenis hadiah menentukan apa yang dikirim game
 API customer tidak memberi tahu `reward_type`. Jenisnya disepakati saat game
 didaftarkan (§2.3), dan game dibangun untuk jenis itu.
 | `reward_type` | Hadiah dihitung dari | Body complete | Bila field-nya tidak dikirim |
 |---|---|---|---|
 | `FIXED` | Jumlah tetap per main | `{}` | – |
 | `SCORE_BASED` | Rentang skor yang diatur admin | `{ "score": 800 }` | Hadiah 0 |
 | `OUTCOME_BASED` | Hasil main, mis. `PERFECT`, `GOOD`, `FAIL` | `{ "outcome": "PERFECT" }` | Hadiah 0. `outcome` yang tidak terdaftar juga 0 |
 | `PROBABILITY` | Undian server; peluang tidak pernah dikirim ke game | `{}` | – |
 Admin bisa mengubah besar hadiah kapan saja tanpa build game baru. Supaya game tetap
 benar bila admin juga mengganti jenisnya, **kirim semua hasil yang dimiliki game**:
 game berbasis skor selalu mengirim `score`, game berbasis hasil selalu mengirim
 `outcome`. Field yang tidak dipakai jenis hadiah aktif diabaikan.
 ### 2.3 Mendaftarkan game baru
 Sepakati dengan tim backoffice, lalu admin membuatnya
 ([`integration-backoffice.md`](./integration-backoffice.md) §8):
 | Yang disepakati | Contoh | Catatan |
 |---|---|---|
 | `slug` | `runner` | Huruf kecil, angka, `-`; unik per organisasi. Game memakainya untuk memeriksa dirinya (§6.1) |
 | `game_url` | `https://…/runner/index.html` | URL build game; dibuka aplikasi di webview |
 | `version` | `1.0.0` | Versi build |
 | `reward_type` | `SCORE_BASED` | §2.2 |
 | Daftar `outcome` | `WIN`, `LOSE` | Hanya game `OUTCOME_BASED`; harus sama persis (huruf besar/kecil) |
 | `result_rules` | `max_score`, `min_duration_seconds`, `max_score_per_second` | Hasil di luar batas ini mendapat hadiah 0 tanpa pemberitahuan (§6.3). Isi dengan skor dan durasi wajar game-mu |
 | `session_ttl_seconds` | `600` | Batas waktu satu main. Harus lebih lama dari durasi main terpanjang, ditambah jeda jaringan |
 | `entry_cost` | `5` | Ditentukan bisnis, minimal 1 |
 ---
 ## 3. Daftar API
 Semua endpoint diawali `api_base_url` (dari `init`, §4, atau dari config build pada
 mode mandiri, §5.4), mis. `https://api.example.com/api/v1`. Selain login, semua wajib
 memakai header `Authorization: Bearer <token>`. Request ber-body memakai
 `Content-Type: application/json`.
 | # | Endpoint | Header tambahan | Body | Dipakai saat | Detail |
 |---|---|---|---|---|---|
 | 0 | `POST /customer-auth/login` | Tanpa `Authorization` | `{ "phone_number", "password" }` | Tidak ada token, atau token ditolak | §5.3 |
 | 1 | `GET /customer/enakgame/games` | – | – | Setelah ada token: biaya main, event, segmen roda | §6.1 |
 | 2 | `POST /customer/enakgame/sessions` | `Idempotency-Key` (wajib) | `{ "game_id" }` | Customer menekan Main; EnakCoin dipotong | §6.2 |
 | 3 | `POST /customer/enakgame/sessions/:id/complete` | – | `{ "score"?, "outcome"?, "data"? }` | Permainan selesai | §6.3 |
 | 4 | `GET /customer/enakgame/sessions/:id` | – | – | Pemulihan setelah reload, bila `session_id` tersimpan | §6.4 |
 | 5 | `GET /customer/enakgame/sessions?game_id=&status=&page=&limit=` | – | – | Pemulihan setelah reload, bila `session_id` tidak tersimpan | §6.4 |
 | 6 | `GET /customer/enakgame/leaderboard?date=&game_id=&limit=` | – | – | Layar leaderboard; muat ulang setelah complete | §10 |
 Game tidak memanggil endpoint lain. Registrasi, saldo, riwayat, voucher, dan PIN
 adalah tugas aplikasi customer.
 ---
 ## 4. Bridge dengan aplikasi customer
 > **Usulan.** Bentuk bridge di bawah belum diimplementasikan di sisi mana pun. Sepakati
 > dengan tim aplikasi customer sebelum mulai; aplikasi memakai kontrak yang sama
 > ([`integration-mobile-customer.md`](./integration-mobile-customer.md) §8.3).
 Semua pesan berupa JSON string dengan field `type`.
 - **Game → aplikasi:** `window.EnakGameHost.postMessage(JSON.stringify(pesan))`
  (JavaScript channel webview bernama `EnakGameHost`).
 - **Aplikasi → game:** aplikasi memanggil `window.enakGame.receive(jsonString)`. Game
  wajib mendefinisikan fungsi ini sebelum mengirim `ready`.
 | Arah | `type` | Isi | Kapan |
 |---|---|---|---|
 | game → app | `ready` | – | Halaman game selesai dimuat |
 | app → game | `init` | `api_base_url`, `token`, `game_id` | Jawaban atas `ready`. `token` boleh kosong bila customer belum login |
 | game → app | `balance_changed` | `coin_balance` | Setelah start dan complete berhasil |
 | game → app | `close` | – | Customer keluar dari game |
 Contoh `init`:
 ```json
 { "type": "init", "api_base_url": "https://api.example.com/api/v1", "token": "eyJ…", "game_id": "8a1f…" }
 ```
 Di dalam aplikasi, jangan memanggil API apa pun sebelum `init` diterima. Token yang
 kosong atau ditolak tidak dikembalikan ke aplikasi: game sendiri yang meminta customer
 login (§5.2). Tanpa aplikasi (browser biasa), game berjalan dalam mode mandiri (§5.4).
 ---
 ## 5. Koneksi ke API dan token
 ### 5.1 Bentuk response dan error
 - Sukses: `{ "success": true, "data": { … }, "errors": null }`.
 - Gagal: `{ "success": false, "data": null, "errors": [{ "code", "entity", "cause" }] }`.
  `cause` berbahasa Inggris; jangan tampilkan mentah ke customer.
 - Contoh response di dokumen ini adalah isi `data`, kecuali yang menampilkan amplop
  lengkap (§6.4).
 | `errors[0].code` | HTTP | Arti | Yang dilakukan game |
 |---|---|---|---|
 | `304` dengan `entity` `auth_handler` | 400 | **Token tidak ada atau tidak berlaku** | Layar login (§5.2) |
 | `304` | 400 | Ditolak aturan bisnis | Lihat tabel per endpoint |
 | `303`, `310` | 400 | Request salah format | Bug di game; pesan umum |
 | `404` | 404 | Game/session tidak ada atau bukan milik customer | Pesan "tidak ditemukan", kembali ke aplikasi |
 | `900` | 500 | Error server | Retry (§8) |
 Backend **tidak** memakai HTTP 401. Token yang ditolak dijawab HTTP 400 dengan code
 `304`, sama seperti penolakan bisnis; bedakan lewat `entity`: `auth_handler` untuk token,
 `enakgame_service` untuk aturan EnakGame.
 ### 5.2 Token tidak ada atau ditolak: customer login di game
 Token didapat dari `init` (game dibuka dari aplikasi) atau dari login di game. Setiap
 kali tidak ada token yang berlaku, game menampilkan **layar login akun customer**
 (§5.3).
 | Keadaan | Cara mengenali | Yang dilakukan game |
 |---|---|---|
 | `init` datang dengan token | `token` terisi | Pakai token itu, tanpa layar login |
 | `init` datang tanpa token | `token` kosong, `null`, atau tidak ada | Layar login |
 | Dibuka tanpa aplikasi (browser biasa) | `window.EnakGameHost` tidak ada | Mode mandiri (§5.4), dimulai dari layar login |
 | `init` tidak datang | Tidak ada `init` 5 detik setelah `ready` | Kirim `ready` sekali lagi. Masih tidak datang dalam 5 detik: mode mandiri (§5.4) |
 | Token ditolak backend | HTTP 400, `code` `304`, `entity` `auth_handler` | Layar login dengan pesan "Sesi kamu berakhir, silakan login lagi". Setelah login berhasil, ulangi request yang sama **satu kali** (body dan `Idempotency-Key` sama) |
 | Token hasil login langsung ditolak lagi | Penolakan `auth_handler` kedua untuk request yang sama | Berhenti: "Login bermasalah, coba buka ulang game" dengan tombol Keluar. Jangan menampilkan login berulang-ulang |
 | Customer login dengan akun lain | `GET /sessions/:id` untuk session tersimpan menjawab `404` | Hapus `session_id` dari `sessionStorage`, tampilkan layar awal (§6.4) |
 Token ditolak sebelum apa pun diproses: start yang ditolak tidak memotong EnakCoin, dan
 complete yang ditolak tidak menyelesaikan session. Jadi aman mengulang request yang
 sama setelah login. Timer `expires_at` tetap berjalan selama customer login; complete
 setelah `expires_at` ditolak dan entry cost **tidak** dikembalikan (§7).
 Token hasil login di game tidak dikirim ke aplikasi; aplikasi mengurus tokennya
 sendiri.
 `cause` dari `auth_handler` hanya untuk debugging, jangan dicocokkan di kode:
 | `cause` | Penyebab |
 |---|---|
 | `Authorization header is required` | Header tidak dikirim. Bug di game: memanggil API sebelum ada token |
 | `Invalid authorization header format` | Header bukan `Bearer <token>` |
 | `Invalid token: …` | Token kedaluwarsa, rusak, atau dari environment lain (staging vs. produksi) |
 | `Invalid token type` | Yang dipakai refresh token, bukan access token |
 | `Token is not valid`, `Customer ID not found in token`, `Phone number not found in token` | Token bukan token customer yang sah |
 ### 5.3 Layar login — `POST /customer-auth/login`
 Form berisi nomor HP dan password akun customer, sama dengan akun di aplikasi. Endpoint
 ini tidak memakai header `Authorization`.
 ```json
 { "phone_number": "6281234561234", "password": "rahasia123" }
 ```
 Response lengkap, termasuk amplopnya. Token ada di **`data.data.access_token`**:
 ```json
 {
  "success": true,
  "data": {
    "status": "SUCCESS",
    "message": "Login successful.",
    "data": {
      "access_token": "eyJ…",
      "refresh_token": "eyJ…",
      "user": { "id": "…", "name": "Budi", "phone_number": "6281234561234", "birth_date": "2000-01-31" }
    }
  },
  "errors": null
 }
 ```
 - Pakai `access_token` saja. `refresh_token` ditolak endpoint customer dan belum ada
  endpoint refresh; abaikan dan jangan disimpan.
 - Token hanya di memori (§1). Halaman dimuat ulang berarti login lagi, kecuali di dalam
  aplikasi yang mengirim token lewat `init`.
 - Password hanya dipegang selama request login: jangan disimpan, di-log, atau dikirim
  ke analytics.
 - `user.name` boleh ditampilkan, mis. "Main sebagai Budi", dengan tombol "Ganti akun"
  yang menghapus token dari memori lalu menampilkan login lagi.
 - Nomor HP boleh ditulis `0812…`, `+62 812…`, `62812…`, atau `812…` (spasi dan `-`
  boleh). Backend mengubahnya menjadi format baku **`62812…`**, dan format itu juga yang
  dikembalikan di `user.phone_number`. Hanya nomor HP Indonesia (`628…`) yang diterima;
  selain itu ditolak `invalid phone number format`.
 - Registrasi tidak ada di game. Tampilkan "Belum punya akun atau pendaftaran belum
  selesai? Lanjutkan di aplikasi."
 | `code` | `entity` | HTTP | Arti (`cause`) | Tampilan |
 |---|---|---|---|---|
 | `304` | `customer_auth_service` | 400 | Nomor HP tidak terdaftar atau password salah (`invalid phone number or password`), atau pendaftaran belum selesai (`customer not properly registered`) | **"Nomor HP atau password salah."** |
 | `304` | `request` | 400 | Format salah: `invalid phone number format`, `phone number is required`, `password is required` | "Periksa nomor HP dan password." Cek juga di game sebelum mengirim |
 | `303` | `request` | 400 | Body tidak lengkap | Bug di game |
 | `429` | `customer_auth_service` | 429 | Terlalu banyak percobaan login untuk nomor ini; `data.locked_until` (RFC3339 UTC) | "Terlalu banyak percobaan. Coba lagi pukul {jam}." Nonaktifkan tombol Masuk sampai `locked_until` |
 | `900` | – | 500 | Error server | "Gagal login, coba lagi." |
 Login yang gagal jangan diulang otomatis. Setiap nomor HP hanya boleh mencoba login
 5 kali dalam 15 menit, berhasil maupun gagal; login yang berhasil memulai hitungan
 dari nol. Percobaan ke-6 ditolak `429` sampai 15 menit itu habis, juga bila
 password-nya benar. Batas ini berlaku untuk nomor HP, bukan perangkat, dan sama untuk
 aplikasi customer.
 ### 5.4 Mode mandiri (tanpa aplikasi)
 Dipakai saat game dibuka di browser biasa, atau saat aplikasi tidak mengirim `init`
 (§5.2). Juga dipakai untuk development dengan config staging.
 1. `api_base_url` diambil dari config build per environment (staging, produksi), bukan
   dari URL atau input customer.
 2. Tampilkan layar login (§5.3).
 3. Panggil `GET /customer/enakgame/games` dan ambil game dengan `slug` milik build ini;
   `id`-nya menjadi `game_id`. Tidak ada → "Game tidak tersedia untuk akun ini."
 4. Lanjutkan seperti biasa: pemulihan session (§6.4), lalu layar awal.
 Tanpa aplikasi tidak ada bridge: `balance_changed` dan `close` tidak dikirim, dan tombol
 Keluar kembali ke layar awal game.
 ### 5.5 Contoh helper API
 Helper ini menangani token dari `init`, layar login, dan token yang ditolak:
 ```js
 let apiBaseUrl = CONFIG.apiBaseUrl; // config build per environment; init menimpanya
 let gameId = null;                  // dari init; mode mandiri: dicari lewat slug (§5.4)
 let token = null;                   // hanya di memori
 let loginWaiters = [];              // request yang menunggu customer login
 const hasHost = () => typeof window.EnakGameHost !== 'undefined';
 const toHost = (msg) => hasHost() && window.EnakGameHost.postMessage(JSON.stringify(msg));
 window.enakGame = {
  receive(raw) {
    const msg = JSON.parse(raw);
    if (msg.type !== 'init') return;
    apiBaseUrl = msg.api_base_url;
    gameId = msg.game_id;
    token = msg.token || null;      // kosong → layar login saat request pertama
    onInit();                       // pemulihan session (§6.4), lalu layar awal
  },
 };
 // Menampilkan layar login; selesai setelah customer berhasil login.
 function waitForLogin(message) {
  return new Promise((resolve) => {
    if (loginWaiters.length === 0) showLoginScreen(message);
    loginWaiters.push(resolve);
  });
 }
 // Dipanggil tombol Masuk. Error dilempar ke layar login dan ditampilkan sesuai §5.3.
 async function login(phoneNumber, password) {
  const res = await fetch(apiBaseUrl + '/customer-auth/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ phone_number: phoneNumber, password }),
  });
  const json = await res.json().catch(() => null);
  if (!json?.success) throw json?.errors?.[0] ?? { code: String(res.status) };
  token = json.data.data.access_token;
  hideLoginScreen();
  loginWaiters.splice(0).forEach((resolve) => resolve());
 }
 // Mengembalikan isi `data`, atau melempar errors[0]. Error jaringan ikut dilempar,
 // lalu ditangani pemanggil sesuai §8.
 async function api(method, path, { body, idempotencyKey } = {}) {
  for (let attempt = 0; ; attempt++) {
    if (!token) await waitForLogin(attempt === 0 ? null : 'Sesi kamu berakhir, silakan login lagi.');
    const headers = { Authorization: `Bearer ${token}` };
    if (body !== undefined) headers['Content-Type'] = 'application/json';
    if (idempotencyKey) headers['Idempotency-Key'] = idempotencyKey;
    const res = await fetch(apiBaseUrl + path, {
      method,
      headers,
      body: body === undefined ? undefined : JSON.stringify(body),
    });
    const json = await res.json().catch(() => null);
    if (json?.success) return json.data;
    const err = json?.errors?.[0] ?? { code: String(res.status) };
    if (err.entity === 'auth_handler' && attempt === 0) {
      token = null;                 // login lagi, lalu ulangi request yang sama sekali
      continue;
    }
    throw err;
  }
 }
 ```
 ---
 ## 6. Alur satu kali main
 ```
 init ─► token ada? tidak: login (§5.2) ─► cek session yang masih berjalan (§6.4)
     ─► GET /customer/enakgame/games ─► tampilkan biaya (dan roda, untuk spin)
     ─► tap Main ─► POST /customer/enakgame/sessions      (EnakCoin dipotong)
     ─► permainan berjalan (batas waktu: expires_at)
     ─► POST /customer/enakgame/sessions/:id/complete     (server menghitung hadiah)
     ─► tampilkan hadiah ─► main lagi atau close
 ```
 ### 6.1 Data game — `GET /customer/enakgame/games`
 Mengembalikan semua game aktif organisasi customer. Ambil yang `id`-nya sama dengan
 `game_id` dari `init`; pada mode mandiri, yang `slug`-nya milik build ini (§5.4).
 ```json
 [
  {
    "id": "8a1f…",
    "slug": "spin",
    "name": "Spin Harian",
    "description": null,
    "thumbnail_url": "https://…/spin.png",
    "game_url": "https://…/spin/index.html",
    "version": "1.2.0",
    "entry_cost": 5,
    "session_ttl_seconds": 600,
    "events": [
      { "id": "…", "name": "Ramadan 2x", "banner_url": "https://…", "multiplier": 2, "bonus": null, "end_at": "2026-10-31T16:59:59Z" }
    ],
    "prizes": [
      { "entry": 1, "label": "Zonk", "amount": 0 },
      { "entry": 2, "label": "3 Coin", "amount": 3 },
      { "entry": 3, "label": "10 Coin", "amount": 10 },
      { "entry": 4, "label": "Jackpot", "amount": 50 }
    ]
  }
 ]
 ```
 - `entry_cost`: EnakCoin per main. Tampilkan di tombol Main ("Main · 5 EnakCoin").
 - `events`: event yang sedang berlaku, prioritas tertinggi dulu. Tampilkan sebagai
  label, mis. "2x hadiah sampai 31 Okt". `multiplier` 2 berarti hadiah dasar ditambah
  sekali lagi; `bonus` menambah sejumlah EnakCoin.
 - `prizes`: hanya ada untuk game ber-reward `PROBABILITY` (spin). Urutan = urutan segmen
  roda. `label` bisa `null`. Bobot peluang tidak pernah dikirim.
 - Game tidak ada di daftar → game sudah dinonaktifkan; tampilkan pesan dan `close`.
 - `slug` bukan yang dibangun untuk build ini (mis. build spin menerima game `runner`)
  → `game_url` salah dipasang admin. Tampilkan "Game sedang tidak tersedia", `close`,
  dan laporkan ke tim backoffice.
 ### 6.2 Mulai — `POST /customer/enakgame/sessions`
 Header `Idempotency-Key` wajib (maks. 50 karakter, mis. UUID v4). Buat key baru saat
 customer menekan Main; pakai key yang sama bila request diulang karena jaringan atau
 karena customer login ulang (§5.2).
 ```json
 { "game_id": "8a1f…" }
 ```
 ```json
 {
  "session_id": "c0d3…",
  "game_id": "8a1f…",
  "entry_cost": 5,
  "expires_at": "2026-10-08T05:10:00Z",
  "coin_balance": 15,
  "replayed": false
 }
 ```
 - EnakCoin sudah terpotong. Kirim `balance_changed` dengan `coin_balance`.
 - `replayed: true`: request ini mengulang start yang sudah berhasil; pakai session yang
  sama, EnakCoin tidak terpotong dua kali.
 - `expires_at`: batas waktu mengirim hasil (default 10 menit sejak start, diatur per
  game). Tampilkan timer bila permainan bisa lama.
 | Penolakan `304` (`cause`) | Tampilan |
 |---|---|
 | `not enough EnakCoin` | "EnakCoin kamu kurang." Tombol kembali ke aplikasi |
 | `the game is not available` | "Game sedang tidak tersedia." |
 | `the game has no active reward configuration` | "Game sedang tidak tersedia." |
 | `no EnakGame budget is set for this period` | "Game sedang tidak tersedia." |
 | `the customer is not active` | "Akun tidak aktif." |
 | `this Idempotency-Key was already used to start another game` | Bug di game: key dipakai ulang untuk game lain |
 | `the Idempotency-Key header is required` / `… at most 50 characters` | Bug di game |
 ### 6.3 Kirim hasil — `POST /customer/enakgame/sessions/:id/complete`
 Kirim sekali saat permainan selesai, sebelum `expires_at`. Body berisi hasil saja,
 sesuai jenis hadiah game (§2.2):
 | Field | Tipe | Untuk |
 |---|---|---|
 | `score` | integer ≥ 0, opsional | Game berbasis skor |
 | `outcome` | string, opsional | Game berbasis hasil, mis. `"WIN"`, `"PERFECT"` |
 | `data` | objek JSON, opsional, maks. 16 KB | Data tambahan untuk audit (durasi per level, dsb.) |
 Spin cukup mengirim `{}`. Game skor: `{ "score": 800 }`. Game hasil:
 `{ "outcome": "WIN" }`. Nilai `outcome` yang diterima ditentukan admin per game
 (§2.3).
 ```json
 {
  "session_id": "c0d3…",
  "status": "COMPLETED",
  "reward_total": 10,
  "reward": { "base": 5, "event": 5 },
  "coin_balance": 25,
  "limited_by": ["USER_DAILY"],
  "prize": { "entry": 2, "label": "3 Coin", "amount": 3 }
 }
 ```
 | Field | Arti | Tampilan |
 |---|---|---|
 | `reward_total` | EnakCoin yang **benar-benar masuk** | Angka utama di layar hadiah |
 | `reward.base` / `reward.event` | Hadiah dasar dan tambahan event | "5 + 5 bonus event" |
 | `coin_balance` | Saldo EnakCoin setelah hadiah | Kirim `balance_changed` |
 | `limited_by` | Batas harian yang memotong hadiah: `USER_DAILY`, `GAME_DAILY`, `GLOBAL_DAILY` | "Hadiah hari ini sudah mencapai batas" |
 | `prize` | Untuk spin: segmen hasil undian. `amount` = hadiah dasar segmen, sebelum event dan batas | Hentikan roda di `prize.entry` |
 | `status` | `COMPLETED`, atau `REFUNDED` bila game dinonaktifkan selama dimainkan | Lihat di bawah |
 - **`status: "REFUNDED"`** (`refund_reason: "GAME_DEACTIVATED"`): entry cost
  dikembalikan dan tidak ada hadiah. Tampilkan "Game sedang dihentikan, EnakCoin kamu
  dikembalikan."
 - **`reward_total` 0** bisa terjadi: hadiahnya memang 0 (mis. segmen Zonk), batas harian
  sudah habis, field yang dibutuhkan jenis hadiahnya tidak dikirim (§2.2), atau hasilnya
  tidak lolos validasi server (skor di atas batas, terlalu cepat selesai, `outcome`
  tidak dikenal). Server tidak memberi tahu alasan validasi; tampilkan hasil apa adanya.
 - **Mengirim ulang aman.** Complete untuk session yang sudah selesai mengembalikan
  jawaban yang sama, tanpa hadiah dua kali. Tidak perlu `Idempotency-Key`.
 | Penolakan | Arti | Tampilan |
 |---|---|---|
 | `304` `the session has expired` | Lewat `expires_at` | "Waktu bermain habis." (lihat §7) |
 | `304` `data must be …` | `data` bukan JSON atau lebih dari 16 KB | Bug di game |
 | `310` | `score` bukan bilangan bulat atau `outcome` bukan string | Bug di game |
 | `404` | Session tidak ada / milik customer lain | Pesan umum |
 ### 6.4 Pemulihan setelah reload
 Webview bisa memuat ulang halaman game (aplikasi ke background, memori habis, crash)
 saat customer sedang main. EnakCoin sudah terpotong, jadi game wajib menemukan lagi
 session-nya. Dua endpoint dipakai:
 **Satu session** — `GET /customer/enakgame/sessions/:id`
 ```json
 {
  "id": "c0d3…", "game_id": "8a1f…", "status": "STARTED", "entry_cost": 5, "reward_total": 0,
  "started_at": "…", "expires_at": "…", "ended_at": null, "refund_reason": null
 }
 ```
 `status`: `STARTED`, `COMPLETED`, `REFUNDED`, atau `EXPIRED`. Response ini tidak memuat
 `prize` atau rincian hadiah; untuk itu kirim ulang complete (lihat di bawah).
 **Mencari session** — `GET /customer/enakgame/sessions?game_id=8a1f…&status=STARTED&limit=1`
 Response lengkap, termasuk amplopnya. Daftar session ada di **`data.data`**, terbaru di
 atas:
 ```json
 {
  "success": true,
  "data": {
    "data": [
      {
        "id": "c0d3…", "game_id": "8a1f…", "status": "STARTED", "entry_cost": 5, "reward_total": 0,
        "started_at": "…", "expires_at": "…", "ended_at": null, "refund_reason": null
      }
    ],
    "pagination": { "page": 1, "limit": 1, "total_count": 1, "total_pages": 1 }
  },
  "errors": null
 }
 ```
 Tidak ada session yang cocok: `data.data` berupa array kosong `[]` (tidak pernah
 `null`). Bentuk lain berarti error, bukan "tidak ada session". Semua query opsional:
 `game_id`, `status` (`STARTED`, `COMPLETED`, `REFUNDED`, `EXPIRED`), `page`, `limit`.
 `status` atau `game_id` yang tidak valid ditolak `304`.
 Bila pengecekan ini gagal (jaringan, `5xx`), **jangan** menganggap tidak ada session:
 customer bisa terpotong EnakCoin dua kali. Tampilkan "Coba lagi" sampai berhasil.
 **Alurnya, setiap kali menerima `init`:**
 1. Simpan `session_id` di **`sessionStorage`** setiap kali start berhasil, dan hapus
   setelah hasilnya ditampilkan. `session_id` bukan rahasia; token tetap hanya di
   memori (§1).
 2. Bila ada `session_id` tersimpan, panggil `GET /sessions/:id`. Bila tidak ada (mis.
   webview dibuka ulang dari awal), panggil
   `GET /sessions?game_id=<game_id>&status=STARTED&limit=1`.
 3. Tindak lanjuti sesuai status:
 | Keadaan | Yang dilakukan game |
 |---|---|
 | `STARTED`, sekarang sebelum `expires_at` | **Lanjutkan** session itu: jangan start baru (EnakCoin akan terpotong lagi). Spin: langsung kirim complete `{}` dan tampilkan hasilnya. Game lain: progres main hilang, jadi mulai ulang permainan di session yang sama dengan timer sampai `expires_at`, lalu kirim complete. Complete setelah `expires_at` ditolak, jadi **akhiri ronde otomatis dan kirim skor saat itu** beberapa detik sebelum `expires_at` (mis. 5 detik, untuk jeda jaringan dan selisih jam perangkat) |
 | `STARTED`, `expires_at` sudah lewat | Anggap selesai. Server mengubahnya menjadi `EXPIRED` (atau merefund bila complete sebelumnya gagal karena error server) dalam ±1 menit. Tampilkan "Waktu bermain habis", lalu customer boleh start baru |
 | `COMPLETED` | Hasil sudah dihitung tapi mungkin belum ditampilkan. Kirim ulang `POST /sessions/:id/complete` dengan body apa saja (`{}`): server mengembalikan jawaban yang sama persis, termasuk `prize`, tanpa hadiah dobel. Tampilkan hasilnya |
 | `REFUNDED` | "EnakCoin kamu dikembalikan." |
 | `EXPIRED` | "Waktu bermain habis." |
 | `404` untuk `session_id` tersimpan | Session milik akun lain (customer berganti akun). Hapus `session_id`, lanjut seperti tidak ada session |
 | Tidak ada session | Tampilkan layar awal seperti biasa |
 Riwayat main lengkap (tanpa filter) dipakai aplikasi customer, bukan game.
 ---
 ## 7. Batas waktu dan refund
 | Keadaan | Yang terjadi pada EnakCoin |
 |---|---|
 | Hasil dikirim sebelum `expires_at` | Entry cost terpakai, hadiah masuk |
 | Customer menutup game / game crash, hasil tidak pernah dikirim | Session menjadi `EXPIRED` setelah `expires_at`. **Entry cost tidak dikembalikan** |
 | Complete tertahan karena customer harus login ulang sampai `expires_at` lewat | Sama dengan di atas: `EXPIRED`, **entry cost tidak dikembalikan** |
 | Complete gagal karena error server (`5xx`) dan tidak berhasil sampai `expires_at` | Session direfund otomatis (`refund_reason: "SYSTEM_ERROR"`) dalam ±1 menit setelah `expires_at` |
 | Game dinonaktifkan admin saat dimainkan | Session direfund (`GAME_DEACTIVATED`) |
 Karena itu kirim hasil **segera** setelah permainan selesai, sebelum animasi panjang.
 Saat customer menekan keluar di tengah permainan, tampilkan konfirmasi "EnakCoin yang
 sudah dipakai tidak kembali".
 ---
 ## 8. Retry dan jaringan
 | Request | Gagal karena jaringan / `5xx` | Aturan |
 |---|---|---|
 | Start | Ulangi dengan **`Idempotency-Key` yang sama** | Key baru = potong EnakCoin lagi |
 | Complete | Ulangi dengan body yang sama sampai berhasil atau `expires_at` lewat | Aman diulang |
 | Token ditolak (`entity` `auth_handler`) | Bukan error jaringan; layar login (§5.2) | Setelah login, ulangi sekali |
 | Login gagal | Tampilkan pesan (§5.3) | Jangan diulang otomatis |
 Gunakan backoff (mis. 1 s, 2 s, 4 s) dan tampilkan indikator "Menyimpan hasil…" selama
 complete diulang.
 ---
 ## 9. Spin
 1. Gambar roda dari `prizes` (§6.1): satu segmen per entri, urut, dengan `label`
   (atau `amount` bila `label` `null`).
 2. Tap Putar → start session (§6.2).
 3. Mulai animasi berputar, lalu langsung kirim complete dengan `{}`.
 4. Dari response, hentikan roda di segmen `prize.entry`, lalu tampilkan `reward_total`.
 Jangan menentukan segmen sendiri lalu "mencocokkan" dengan server. Bila `prize` tidak
 ada di response, hasil tidak bisa ditampilkan sebagai roda; tampilkan `reward_total`
 saja.
 ---
 ## 10. Leaderboard mingguan — `GET /customer/enakgame/leaderboard`
 Peringkat customer satu organisasi menurut EnakCoin yang dimenangkan dari game dalam
 satu minggu, Senin 00:00 sampai Minggu 23:59 WIB. Yang dihitung hanya session
 `COMPLETED`, menurut minggu saat session dimulai; entry cost tidak mengurangi. Total
 yang sama diurutkan menurut siapa yang mencapainya lebih dulu, jadi tidak ada peringkat
 kembar.
 | Query | Default | Keterangan |
 |---|---|---|
 | `date` | Minggu ini | Hari mana pun dalam minggu yang diminta, `YYYY-MM-DD`. Untuk minggu lalu, kirim tanggal 7 hari sebelum `week_start` minggu ini |
 | `game_id` | Semua game | Leaderboard satu game, mis. `game_id` dari `init` untuk "peringkat game ini" |
 | `limit` | 10 | Jumlah peringkat teratas, maks 100 |
 ```json
 {
  "week_start": "2026-10-12",
  "week_end": "2026-10-18",
  "game_id": null,
  "entries": [
    { "rank": 1, "name": "Budi S******", "coins": 120, "is_me": false },
    { "rank": 2, "name": "Siti N** A*****", "coins": 90, "is_me": true }
  ],
  "me": { "rank": 2, "name": "Siti N** A*****", "coins": 90, "is_me": true }
 }
 ```
 - Nama customer lain sudah disamarkan server: kata pertama utuh, kata berikutnya hanya
  huruf pertama. Tampilkan apa adanya; untuk baris `is_me: true` tampilkan "Kamu".
 - `me` adalah posisi customer yang login, juga bila di luar `limit`: tampilkan sebagai
  baris tersendiri di bawah daftar. `null` bila belum menang EnakCoin minggu itu
  ("Main untuk masuk leaderboard").
 - `entries` kosong (`[]`, tidak pernah `null`) bila belum ada yang menang minggu itu.
 - Tampilkan rentang minggu dari `week_start`–`week_end`; jangan menghitung minggu
  sendiri dari jam perangkat.
 - Leaderboard tidak berubah sendiri. Muat ulang setelah complete berhasil, atau saat
  layar leaderboard dibuka.
 - `date` yang bukan `YYYY-MM-DD` atau `game_id` yang bukan UUID ditolak `304` (bug di
  game; pesan umum).
 ---
 ## 11. Checklist
 - [ ] Game baru sudah didaftarkan bersama tim backoffice (§2.3); `slug` diperiksa saat `init` (§6.1).
 - [ ] Body complete sesuai jenis hadiah game (§2.2).
 - [ ] Bridge sesuai kontrak §4 yang sudah disepakati dengan tim aplikasi.
 - [ ] Token hanya di memori; tidak ada di URL, storage, log, atau analytics.
 - [ ] Tanpa token tidak ada request; token kosong atau ditolak → layar login → ulangi request sekali (§5.2).
 - [ ] Login memakai `access_token`; password tidak disimpan; nomor HP/password salah tampil sebagai pesan yang jelas (§5.3).
 - [ ] Mode mandiri (§5.4): dibuka di browser atau `init` tidak datang → login, `game_id` dicari lewat `slug`.
 - [ ] Pemulihan setelah reload (§6.4): session `STARTED` dilanjutkan, bukan start baru; `COMPLETED` ditampilkan lewat complete ulang.
 - [ ] Biaya main dan label event tampil sebelum main.
 - [ ] Satu `Idempotency-Key` per tap Main, dipakai ulang saat retry.
 - [ ] Complete hanya mengirim `score` / `outcome` / `data`, tidak pernah hadiah.
 - [ ] Hadiah di layar dari `reward_total`; `limited_by` dan `REFUNDED` ditangani.
 - [ ] Spin berhenti di `prize.entry`.
 - [ ] Leaderboard (§10): rentang minggu dari `week_start`/`week_end`, baris `is_me` sebagai "Kamu", `me` di luar `limit` tampil di bawah daftar, dimuat ulang setelah complete.
 - [ ] Complete diulang dengan aman saat gagal; timeout `expires_at` ditangani.
 - [ ] `balance_changed` dikirim setelah start dan complete; `close` saat keluar.
@@ -1,548 +0,0 @@
 # Integrasi EnakPoint & EnakCoin — Customer App, POS & Dashboard
 **Migrasi:** `000090`–`000097` · **Base URL:** `/api/v1` · **Kompatibilitas:** endpoint
 lama tetap jalan sebagai alias (lihat §8)
 Panduan untuk memakai saldo loyalitas dari sisi klien. Alasan di balik setiap aturan
 ada di [`prd-point-coin.md`](./prd-point-coin.md).
 > **Perubahan 7 Okt 2026:** bayar order dengan EnakPoint sudah dihapus (migrasi
 > `000102`). EnakPoint sekarang hanya bisa ditukar ke voucher, tidak bisa dipakai
 > sebagai alat bayar dan tidak bisa dicairkan
 > ([`enakgame-prd.md`](./enakgame-prd.md) §3.2). Endpoint dan field yang ikut dihapus
 > ada di §8.
 ---
 ## 1. Konsep inti
 | | EnakPoint (`POINT`) | EnakCoin (`COIN`) |
 |---|---|---|
 | Didapat dari | Order lunas (per outlet), adjustment admin, exchange | Order lunas (per outlet), adjustment admin |
 | Dipakai untuk | **Ditukar ke voucher** (tidak bisa membayar order) | **Main game**, ditukar ke EnakPoint |
 | Bisa ditransfer | Ya | Ya |
 | Bisa kedaluwarsa | Ya, bila diaktifkan owner | Ya, bila diaktifkan owner |
 Aturan yang berlaku di seluruh dokumen ini:
 1. **Semua jumlah bilangan bulat.** Tidak ada "setengah EnakPoint".
 2. **Saldo tidak pernah jadi uang.** Tidak ada pencairan, dan EnakPoint tidak bisa
   dipakai membayar order. Tampilkan nilai rupiahnya sebagai **"setara potongan
   Rp …"**, bukan "saldo Rp …".
 3. **Semua aksi customer yang memindahkan saldo butuh PIN 6 digit** (§3): exchange
   dan transfer. Main game tidak butuh PIN.
 4. **Wallet milik customer di satu organisasi.** Saldo berlaku di semua outlet
   organisasi itu. Nilai rupiah EnakPoint, kurs exchange, batas transfer, dan
   kedaluwarsa diatur per organisasi; earning per outlet.
 5. **Setiap mutasi tercatat** di riwayat beserta asal atau tujuannya, dan tidak pernah
   dihapus. Koreksi muncul sebagai baris baru.
 ### Format response
 Semua endpoint memakai amplop yang sama:
 ```json
 { "success": true, "data": { … }, "errors": null }
 ```
 ```json
 {
  "success": false,
  "data": null,
  "errors": [{ "code": "304", "entity": "wallet_service", "cause": "wallet move refused: not enough EnakCoin" }]
 }
 ```
 | `code` | HTTP | Arti |
 |---|---|---|
 | `303`, `310` | 400 | Body atau parameter tidak lengkap / salah format |
 | `304` | 400 | Permintaan ditolak aturan bisnis; `cause` menjelaskan alasannya |
 | `404` | 404 | Tidak ditemukan (juga dipakai untuk data milik customer/organisasi lain) |
 | `429` | 429 | Terlalu cepat meminta ulang (OTP) |
 | `PIN_NOT_SET` | 403 | Customer belum membuat PIN |
 | `PIN_INVALID` | 400 | PIN salah |
 | `PIN_LOCKED` | 423 | PIN terkunci |
 | `TRANSFER_BLOCKED` | 403 | Transfer ditahan setelah reset PIN |
 | `900` | 500 | Kesalahan server |
 ---
 ## 2. Customer app — saldo & riwayat
 Semua endpoint customer memakai header `Authorization: Bearer <token customer>`.
 ### 2.1 Saldo
 `GET /api/v1/customer/wallet`
 ```json
 {
  "point_balance": 12500,
  "coin_balance": 8,
  "point_value": 1,
  "point_discount_value": 12500,
  "nearest_expiring": {
    "point": { "amount": 150, "date": "2026-12-31" },
    "coin": null
  },
  "recent_transactions": [ … ]
 }
 ```
 - `point_balance` dan `coin_balance` adalah saldo yang **bisa dipakai sekarang**.
 - `point_discount_value` = `point_balance × point_value`. Tampilkan sebagai
  "setara potongan Rp 12.500".
 - `nearest_expiring` bernilai `null` per currency bila tidak ada yang akan kedaluwarsa.
 - `recent_transactions` berisi 5 mutasi terakhir dengan bentuk yang sama seperti §2.2.
 ### 2.2 Riwayat
 `GET /api/v1/customer/wallet/transactions?page=1&limit=20&currency=POINT&type=EARN,TRANSFER_IN&from=2026-09-01&to=2026-09-30`
 Semua query opsional. `limit` 1–100 (default 20). `type` boleh beberapa, dipisah koma.
 `from` / `to` tanggal WIB, inklusif.
 ```json
 {
  "data": [
    {
      "id": "…",
      "currency": "POINT",
      "type": "EARN",
      "amount": 875,
      "balance_after": 12500,
      "description": "Belanja #ORD-0123 di Outlet Kemang",
      "source": { "type": "ORDER", "id": "…" },
      "outlet_id": "…",
      "expires_at": "2026-12-31T23:59:59+07:00",
      "lots": [{ "amount": 875, "remaining": 875, "expires_at": "2026-12-31T23:59:59+07:00" }],
      "created_at": "2026-09-30T12:01:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total_count": 42, "total_pages": 3 }
 }
 ```
 - `amount` bertanda: positif menambah saldo, negatif mengurangi.
 - Penambahan punya `source`, pengurangan punya `destination`. Keduanya berbentuk
  `{ type, id }` dan menunjuk hal yang bisa dibuka di detail (order, game play,
  dst.).
 - `description` sudah siap tampil dan tidak berubah walau nama outlet atau customer
  berubah belakangan. Nama lawan transfer sudah disamarkan.
 - Dua baris exchange atau transfer berbagi `group_id` yang sama.
 | `type` | Arah | Arti | `source` / `destination` |
 |---|---|---|---|
 | `EARN` | + | Didapat dari order lunas | `ORDER` |
 | `EARN_REVERSAL` | − | Ditarik karena order di-void/refund | `ORDER` |
 | `EXCHANGE_OUT` / `EXCHANGE_IN` | − / + | Tukar EnakCoin ke EnakPoint | `WALLET_TX` (baris pasangannya) |
 | `TRANSFER_OUT` / `TRANSFER_IN` | − / + | Transfer antar customer | `WALLET_TX` (baris pasangannya) |
 | `GAME_SPEND` | − | Main game | `GAME_PLAY` |
 | `EXPIRE` | − | Hangus karena kedaluwarsa | `LOT` |
 | `ADJUSTMENT` | + / − | Koreksi oleh admin | `USER` |
 | `MIGRATION` | + | Saldo dari sistem lama | `LEGACY_POINTS` / `LEGACY_TOKENS` |
 ### 2.3 Yang akan kedaluwarsa
 `GET /api/v1/customer/wallet/expiring`
 ```json
 {
  "point": [
    { "amount": 150, "date": "2026-10-31" },
    { "amount": 200, "date": "2026-12-31" }
  ],
  "coin": []
 }
 ```
 Dikelompokkan per tanggal (WIB), paling dekat lebih dulu. Saldo bisa dipakai sampai
 akhir hari tanggal itu. Daftar kosong berarti tidak ada yang akan kedaluwarsa.
 ### 2.4 Notifikasi push (FCM)
 Aplikasi mendaftarkan token FCM-nya **setelah login dan setiap kali FCM memberi token
 baru**:
 `PUT /api/v1/customer/devices`
 ```json
 { "device_id": "a1b2c3", "fcm_token": "…", "platform": "android", "app_version": "2.4.0" }
 ```
 `platform`: `android`, `ios`, atau `web` (opsional). Saat logout, panggil
 `DELETE /api/v1/customer/devices/:device_id` supaya HP itu tidak lagi menerima
 notifikasi customer tersebut. Satu token hanya milik satu customer: bila customer lain
 login di HP yang sama dan mendaftarkan token yang sama, customer sebelumnya otomatis
 tidak menerima notifikasi di HP itu lagi.
 Push yang dikirim, dibedakan lewat `data.type`:
 | `data.type` | Kapan | Isi `data` lainnya |
 |---|---|---|
 | `WALLET_TRANSFER_IN` | Menerima transfer | `transaction_id`, `group_id`, `currency`, `amount` |
 | `WALLET_EXPIRING` | `reminder_days` hari sebelum saldo kedaluwarsa, sekali per tanggal | `currency`, `amount`, `expiry_date` |
 | `WALLET_EXPIRED` | Saldo baru saja hangus | `currency`, `amount` |
 | `PIN_LOCKED` | PIN terkunci setelah 5 kali salah | `locked_until` (RFC3339, UTC) |
 Semua nilai di `data` berupa string, sesuai aturan FCM.
 ---
 ## 3. Customer app — PIN
 PIN 6 digit, terpisah dari password login, dikirim sebagai **string** supaya angka nol
 di depan tidak hilang. PIN tidak pernah dikembalikan di response.
 ### 3.1 Cek status
 `GET /api/v1/customer/pin/status`
 ```json
 { "has_pin": true, "locked_until": null, "transfer_blocked_until": null }
 ```
 Minta customer membuat PIN saat pertama kali ia melakukan aksi yang butuh PIN
 (`has_pin: false`), bukan saat registrasi.
 ### 3.2 Membuat PIN pertama kali
 1. `POST /api/v1/customer/pin/otp` dengan `{ "purpose": "pin_setup" }`. OTP dikirim ke
   nomor customer lewat WhatsApp. Response: `{ "purpose", "otp_token", "expires_at" }`.
 2. `POST /api/v1/customer/pin` dengan
   `{ "otp_token": "…", "otp_code": "123456", "pin": "482913", "confirm_pin": "482913" }`.
 PIN ditolak (`304`) bila bukan 6 digit, konfirmasinya beda, semua digit sama
 (`111111`), berurutan (`123456`, `654321`), atau sama dengan tanggal lahir
 (`DDMMYY` / `YYMMDD`). Tampilkan `cause` apa adanya. Meminta OTP terlalu cepat
 menghasilkan `429`.
 ### 3.3 Mengganti dan mereset PIN
 - **Ganti:** `PUT /api/v1/customer/pin` dengan `{ "old_pin", "pin", "confirm_pin" }`.
 - **Lupa PIN:** minta OTP dengan `purpose: "pin_reset"`, lalu
  `POST /api/v1/customer/pin/reset` dengan body yang sama seperti §3.2. Reset juga
  membuka PIN yang terkunci. Setelah reset, **transfer keluar ditahan 24 jam**;
  exchange tetap bisa.
 ### 3.4 Menangani error PIN
 Setiap endpoint yang menerima `pin` bisa mengembalikan error PIN. Pada error ini `data`
 **tidak** `null`:
 ```json
 {
  "success": false,
  "data": { "code": "PIN_INVALID", "remaining_attempts": 3 },
  "errors": [{ "code": "PIN_INVALID", "entity": "customer_pin_service", "cause": "wrong PIN, 3 attempts left" }]
 }
 ```
 | `data.code` | Field tambahan | Yang ditampilkan aplikasi |
 |---|---|---|
 | `PIN_NOT_SET` | – | Arahkan ke pembuatan PIN (§3.2) |
 | `PIN_INVALID` | `remaining_attempts` | "PIN salah, sisa 3 percobaan" |
 | `PIN_LOCKED` | `locked_until` | "PIN terkunci sampai 14:30", tawarkan reset PIN |
 | `TRANSFER_BLOCKED` | `transfer_blocked_until` | "Transfer bisa dilakukan lagi pada …" |
 Lima kali salah berturut-turut mengunci PIN selama 30 menit. Selama terkunci, PIN yang
 benar pun ditolak. Penghitung disimpan di server, jadi tidak bisa diakali dengan
 reinstall atau ganti HP.
 ---
 ## 4. Earning, void, dan refund
 EnakPoint bukan payment method: tidak ada payment method bertipe `point`, dan
 `POST /api/v1/payments` memakai `amount` seperti pembayaran lain. Kode bayar,
 bayar dari aplikasi, dan preview pembayaran EnakPoint sudah dihapus (§8).
 Response order membawa `points_earned` dan `coins_earned` (0 bila order tidak
 menghasilkan apa-apa). Earning dihitung dari `subtotal − discount`, sebelum pajak, dan
 diberikan saat order lunas.
 EnakPoint dan EnakCoin yang didapat dari order ikut ditarik saat void/refund. Bila
 saldo customer sudah terpakai, yang ditarik sebanyak yang ada; refund tidak pernah
 diblokir karena ini.
 ---
 ## 5. Exchange EnakCoin → EnakPoint
 Kurs per organisasi: `coin_amount` EnakCoin = `point_amount` EnakPoint (default 1 : 1).
 1. **Preview** sebelum minta PIN:
   `GET /api/v1/customer/wallet/exchange/preview?coins=30`
   ```json
   { "coin_amount": 10, "point_amount": 3, "coin_balance": 35, "coins": 30, "points": 9, "valid": true }
   ```
   Bila `valid: false`, tampilkan `reason` (misalnya harus kelipatan `coin_amount`,
   atau EnakCoin tidak cukup).
 2. **Tukar:**
   `POST /api/v1/customer/wallet/exchange` dengan header **`Idempotency-Key`** (wajib,
   maks. 50 karakter, satu key per percobaan tukar)
   ```json
   { "coins": 30, "pin": "482913" }
   ```
   ```json
   {
     "group_id": "…",
     "coins": 30,
     "points": 9,
     "coin_amount": 10,
     "point_amount": 3,
     "lots": [{ "amount": 9, "expires_at": "2026-12-31T23:59:59+07:00" }],
     "coin_balance": 5,
     "point_balance": 9,
     "replayed": false
   }
   ```
 - Jumlah EnakCoin harus kelipatan `coin_amount`. Kesalahan jumlah ditolak **sebelum**
  PIN dicek, jadi tidak memakan jatah percobaan PIN.
 - Exchange tidak bisa dibatalkan; tampilkan konfirmasi.
 - Kirim ulang dengan `Idempotency-Key` yang sama bila koneksi putus: hasil pertama
  dikembalikan dengan `replayed: true` tanpa menukar lagi, dengan kurs saat itu.
  `Idempotency-Key` yang sama untuk jumlah berbeda ditolak.
 - EnakPoint hasil tukar tidak bisa hidup lebih lama dari EnakCoin asalnya (`lots`
  menunjukkan tanggalnya).
 ---
 ## 6. Transfer ke customer lain
 1. **Cek penerima** sebelum konfirmasi:
   `GET /api/v1/customer/wallet/transfer/recipient?phone=081234561234`
   ```json
   { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" }
   ```
   Nomor yang tidak terdaftar di organisasi yang sama dijawab `404`. Diri sendiri,
   customer walk-in, atau customer nonaktif dijawab `304`.
 2. **Kirim:**
   `POST /api/v1/customer/wallet/transfer` dengan header **`Idempotency-Key`** (wajib)
   ```json
   { "currency": "POINT", "amount": 120, "recipient_phone": "081234561234", "pin": "482913" }
   ```
   ```json
   {
     "group_id": "…",
     "currency": "POINT",
     "amount": 120,
     "recipient": { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" },
     "lots": [
       { "amount": 100, "expires_at": "2026-12-31T23:59:59+07:00" },
       { "amount": 20, "expires_at": null }
     ],
     "balance": 30,
     "replayed": false
   }
   ```
 - `currency`: `POINT` atau `COIN`, satu jenis per transfer.
 - Batas dari organisasi: transfer bisa dimatikan, ada minimal, maksimal per
  transaksi, dan batas harian per currency (reset tengah malam WIB). Pelanggaran batas
  ditolak `304` sebelum PIN dicek.
 - Transfer final dan tidak bisa dibatalkan customer.
 - Saldo yang dikirim membawa tanggal kedaluwarsa aslinya ke penerima (`lots`).
  Tampilkan ini ke pengirim.
 - Penerima mendapat push `WALLET_TRANSFER_IN` (§2.4).
 - Retry dengan `Idempotency-Key` yang sama mengembalikan hasil pertama
  (`replayed: true`) dan tidak dihitung dua kali terhadap batas harian.
 ---
 ## 7. Game
 Game lama (`POST /api/v1/customer/spin`, `GET /customer/games`,
 `GET /customer/ferris-wheel`, dan admin `/marketing/games`, `/marketing/game-prizes`,
 `/marketing/rewards`) sudah dihapus. Semua game, termasuk spin, sekarang game EnakGame:
 - Customer: `GET /api/v1/customer/enakgame/games`, lalu
  `POST /api/v1/customer/enakgame/sessions` (wajib `Idempotency-Key`, memotong
  `entry_cost` EnakCoin), lalu `POST /api/v1/customer/enakgame/sessions/:id/complete`
  (server menghitung hadiah EnakCoin). Tanpa PIN.
 - Dashboard: game dan biaya per main (`entry_cost`, bilangan bulat ≥ 1) diatur di
  `/marketing/enakgame/games`, hadiahnya di reward config.
 Langkah admin dan alur aplikasi untuk spin ada di [`enakgame-spin.md`](enakgame-spin.md).
 ---
 ## 8. Endpoint lama (deprecated)
 Masih jalan dan membaca saldo wallet, tapi akan dihapus setelah semua versi aplikasi
 pindah. Aplikasi baru jangan memakainya.
 | Lama | Ganti dengan |
 |---|---|
 | `GET /customer/points` | `GET /customer/wallet` (`point_balance`) |
 | `total_points`, `points_history`, `last_updated` di `/customer/wallet` | `point_balance`, `recent_transactions` |
 Beri tahu tim backend setelah aplikasi yang beredar tidak lagi memakai kolom kiri,
 supaya alias ini bisa dihapus.
 Semua yang bernama token sudah dihapus: `GET /customer/tokens`, `total_tokens`,
 `tokens_history`, `token_used`, `tokens_remaining`, dan nilai `TOKENS` di campaign. Pakai
 `coin_balance`, `coins_used`, `coins_remaining`, dan `COINS`.
 Bayar dengan EnakPoint juga sudah dihapus (7 Okt 2026, migrasi `000102`) karena
 EnakPoint sekarang hanya untuk voucher ([`enakgame-prd.md`](./enakgame-prd.md) §3.2).
 Tidak ada penggantinya:
 - Endpoint `POST /customer/wallet/payment-code`, `POST /customer/orders/:id/pay-with-points`,
  dan `GET /orders/:id/point-payment/preview`.
 - Payment method tipe `point`, serta field `points` dan `payment_code` di
  `POST /payments`; `amount` kembali wajib seperti pembayaran lain.
 - `points_used` dan `point_value` di response pembayaran dan di `payments` pada
  `GET /customer/orders/:id`; `accepts_point_payment` di `GET /customer/outlets`.
 - Objek `point_payment` (`accept_payment`, `min_payment_points`,
  `max_payment_percent`) di setting outlet (§9.1).
 - Di analytics payment method: `point_amount`, `points_used`, `total_with_points` di
  `summary`, serta `points_used` dan `counts_as_cash_in` per baris.
  `summary.total_amount` kembali total semua method, dan persentase dihitung dari total
  itu.
 - Tipe mutasi `PAYMENT` dan `PAYMENT_REFUND` tidak ditulis lagi.
 ---
 ## 9. Dashboard
 Semua endpoint di bagian ini butuh login user dengan role Admin atau Manager.
 ### 9.1 Pengaturan per outlet
 `GET` / `PUT /api/v1/outlets/:outlet_id/loyalty-settings`
 ```json
 {
  "point": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 100, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null },
  "coin": { "enabled": true, "earn_mode": "PER_AMOUNT", "earn_per_amount": 25000, "earn_value": 1, "earn_percent": 1, "min_order_amount": 0, "max_per_order": null }
 }
 ```
 Field yang tidak dikirim di `PUT` tetap memakai nilai sekarang. `PUT` yang masih
 mengirim `point_payment` ditolak `310` (field tidak dikenal). Response menambahkan
 `point_value` organisasi dan `point_cashback_percent`
 (`earn_value × point_value / earn_per_amount × 100`, atau `earn_percent × point_value`
 pada `earn_mode` `PERCENTAGE`). **Tampilkan persentase ini di
 samping setting** supaya owner tidak salah membaca skala: default di atas setara
 cashback 1%.
 ### 9.2 Pengaturan organisasi
 `GET` / `PUT /api/v1/marketing/loyalty-settings` (tambah `?dry_run=true` untuk preview
 tanpa menyimpan)
 ```json
 {
  "point_value": 1,
  "exchange": { "coin_amount": 1, "point_amount": 1 },
  "transfer": { "enabled": true, "min_amount": 1, "max_per_transaction": null, "daily_limit": null },
  "point_expiry": {
    "enabled": false,
    "mode": "FIXED_DATE",
    "fixed_dates": ["12-31"],
    "grace_months": 3,
    "period": 12,
    "unit": "MONTH",
    "end_of_month": false,
    "reminder_days": 7
  },
  "coin_expiry": { … sama … },
  "enakgame": { "user_daily_limit": 0, "global_daily_limit": 0 }
 }
 ```
 Field yang tidak dikirim di `PUT` tetap memakai nilai sekarang. Response menambahkan:
 - `impact`: total saldo beredar dan nilai rupiahnya **sebelum dan sesudah** perubahan
  `point_value` atau kurs. Tampilkan sebagai peringatan sebelum owner menyimpan.
 - `expiry_preview`: `{ "point": …, "coin": … }`, kapan saldo yang didapat hari ini
  akan kedaluwarsa (`null` bila tidak kedaluwarsa). Tampilkan sebagai "EnakPoint yang
  didapat hari ini kedaluwarsa pada 31 Des 2026".
 - `expiry_activations`: bila perubahan ini **menyalakan** kedaluwarsa untuk pertama
  kali, berapa saldo lama yang ikut diberi tanggal (`lots`, `amount`) dan tanggalnya
  (`expires_at`). Selalu minta konfirmasi dengan `dry_run=true` dulu.
 - `changes`: key yang berubah.
 **Kedaluwarsa** diatur per currency dengan salah satu model:
 | `mode` | Cara kerja | Field yang dipakai |
 |---|---|---|
 | `FIXED_DATE` (default) | Semua saldo hangus di tanggal tetap setiap tahun. Saldo yang didapat kurang dari `grace_months` sebelum tanggal itu ikut ke tanggal berikutnya | `fixed_dates` (format `MM-DD`, boleh lebih dari satu, `02-29` ditolak), `grace_months` (0–24) |
 | `ROLLING` | Tiap saldo berlaku sekian lama sejak didapat | `period`, `unit` (`DAY` / `MONTH`), `end_of_month` |
 - `reminder_days` berlaku untuk keduanya: customer diingatkan sekian hari sebelum
  hangus (0 = tanpa pengingat).
 - Mengubah pengaturan hanya berlaku untuk saldo yang masuk setelahnya.
 - Menyalakan kedaluwarsa pertama kali memberi saldo lama masa berlaku penuh: tanggal
  hangus kedua berikutnya (`FIXED_DATE`) atau satu periode penuh (`ROLLING`).
 - Mematikan kedaluwarsa tidak membatalkan tanggal yang sudah terjadwal.
 Riwayat perubahan: `GET /api/v1/marketing/loyalty-settings/history?page=1&limit=20`
 (tambah `outlet_id=` untuk setting outlet).
 ### 9.3 Wallet customer
 - `GET /api/v1/marketing/customers/:id/wallet` — saldo buku dan saldo yang bisa
  dipakai, semua lot yang masih berisi, dan riwayat dengan nama asli (lawan transfer,
  admin, kasir, outlet). Query riwayat sama seperti §2.2.
 - `POST /api/v1/marketing/customers/:id/wallet/adjust`
  ```json
  { "currency": "POINT", "amount": -500, "reason": "Komplain #45", "idempotency_key": "adj-45" }
  ```
  `amount` bertanda. `reason` wajib. Pengurangan yang melebihi saldo ditolak.
  Adjustment tidak disertai pembayaran uang, jadi jangan pakai alasan "pencairan".
 - `GET /api/v1/marketing/wallet-transactions/:id/trace` — telusuri satu mutasi per
  butir: lot mana yang dipakai atau dibuat, lalu rantai asalnya lewat transfer atau
  exchange sampai ke earning/adjustment/migrasi pertama. Contoh: dari transfer keluar
  B bisa terlihat bahwa EnakPoint-nya berasal dari order #ORD-1 milik A yang
  mentransfer ke B.
 ### 9.4 PIN customer
 - `DELETE /api/v1/marketing/customers/:id/pin` dengan `{ "reason": "…" }` — hapus PIN
  bila customer kehilangan akses. Customer lalu membuat PIN baru lewat OTP. Admin
  **tidak bisa** membuat, mengganti, atau melihat PIN.
 - `GET /api/v1/marketing/customers/:id/security-events?page=1&limit=20` — log keamanan:
  `PIN_SET`, `PIN_CHANGED`, `PIN_RESET`, `PIN_FAILED`, `PIN_LOCKED`,
  `PIN_REMOVED_BY_ADMIN`, beserta waktu, IP, dan perangkat.
 ---
 ## 10. Checklist integrasi
 **Customer app**
 - [ ] Daftarkan token FCM setelah login dan saat token berganti; hapus saat logout.
 - [ ] Tangani empat kode error PIN (§3.4) di semua layar yang meminta PIN.
 - [ ] Kirim `Idempotency-Key` baru untuk setiap exchange dan transfer, dan pakai ulang
      key yang sama saat retry.
 - [ ] Tampilkan nilai rupiah sebagai "setara potongan", bukan saldo uang.
 - [ ] Baca `coins_used` / `coins_remaining` dan `/customer/wallet`, bukan field lama.
 **POS**
 - [ ] Cetak `points_earned` dan `coins_earned` di struk.
 - [ ] Jangan menampilkan EnakPoint sebagai payment method (§4).
 **Dashboard**
 - [ ] Tampilkan `point_cashback_percent`, `impact`, `expiry_preview`, dan
      `expiry_activations` sebelum owner menyimpan setting.
 - [ ] Buat ulang game (termasuk spin) di `/marketing/enakgame/games` dengan `entry_cost`
      dan reward config ([`enakgame-spin.md`](enakgame-spin.md)).
@@ -1,9 +1,18 @@
-# Prompt: fitur EnakPoint & EnakCoin di Mobile App Customer
+# Integrasi Mobile App Customer: EnakPoint, EnakCoin, EnakGame & Voucher
 **Untuk:** tim aplikasi mobile customer · **Base URL:** `/api/v1` · **Per:** 8 Okt 2026
 Kamu mengerjakan aplikasi mobile untuk **customer** (bukan kasir, bukan backoffice).
-Tugasmu: membangun fitur loyalitas EnakPoint & EnakCoin di aplikasi, memakai API backend
+Tugasmu: membangun fitur loyalitas di aplikasi, yaitu saldo EnakPoint & EnakCoin,
-yang sudah jadi dan dijelaskan di dokumen ini. Jangan mengarang endpoint, field, atau
+PIN, tukar, transfer, voucher, dan pintu masuk ke game EnakGame. Semuanya memakai API
-aturan yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan dulu.
+backend yang sudah jadi dan dijelaskan di dokumen ini. Jangan mengarang endpoint,
 field, atau aturan yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan
 dulu.
 Dokumen ini menggantikan `mobile-customer-enakpoint.md`, `integration-enakpoint.md`,
 `api-enakpoint.md`, dan `enakgame-spin.md` untuk sisi aplikasi customer. Game-nya
 sendiri (Phaser) dikerjakan tim EnakGame dengan
 [`integration-enakgame.md`](./integration-enakgame.md).
 ---
@@ -11,34 +20,28 @@ aturan yang tidak tertulis di sini; kalau ada yang kurang jelas, tanyakan dulu.
 | | EnakPoint (`POINT`) | EnakCoin (`COIN`) |
 |---|---|---|
-| Didapat dari | Belanja (order lunas), koreksi admin, tukar EnakCoin | Belanja, koreksi admin |
+| Didapat dari | Belanja (order lunas), tukar EnakCoin, koreksi admin | Belanja, **hadiah game**, koreksi admin |
 | Dipakai untuk | **Ditukar ke voucher** (tidak bisa membayar order) | **Main game**, ditukar ke EnakPoint |
 | Bisa dikirim ke customer lain | Ya | Ya |
 | Bisa kedaluwarsa | Ya, bila owner mengaktifkan | Ya, bila owner mengaktifkan |
-Tidak ada lagi "token". Semua yang dulu token sekarang EnakCoin, dan endpoint serta
+Tidak ada lagi "token". Semua yang dulu token sekarang EnakCoin.
 field bernama token sudah dihapus dari API.
 > **Perubahan 7 Okt 2026:** bayar dengan EnakPoint (kode bayar di kasir, bayar order
 > dari app) sudah dihapus dari backend. EnakPoint sekarang hanya bisa ditukar ke
 > voucher, tidak bisa dipakai sebagai alat bayar dan tidak bisa dicairkan
 > ([`enakgame-prd.md`](./enakgame-prd.md) §3.2). Jangan membangun layar bayar atau kode
 > bayar; endpoint dan field yang dihapus ada di §9.
 ### Aturan yang wajib dipatuhi di UI
 1. **Semua jumlah bilangan bulat.** Tidak ada desimal pada EnakPoint atau EnakCoin.
 2. **Saldo bukan uang.** Nilai rupiah EnakPoint selalu ditulis **"setara potongan
-   Rp …"**, tidak pernah "saldo Rp …" atau "uang". Tidak ada fitur tarik tunai, dan
+   Rp …"**, tidak pernah "saldo Rp …" atau "uang". Tidak ada tarik tunai, dan EnakPoint
-   EnakPoint tidak bisa dipakai membayar.
+   tidak bisa dipakai membayar. Jangan membangun layar bayar atau kode bayar.
-3. **PIN 6 digit wajib** untuk: tukar EnakCoin dan transfer. **Main game tidak butuh PIN.** Melihat saldo dan riwayat
+3. **PIN 6 digit wajib** untuk: tukar EnakCoin, transfer, dan **tukar EnakPoint ke
-   tidak butuh PIN.
+   voucher**. Main game, melihat saldo, dan riwayat tidak butuh PIN.
 4. **PIN terpisah dari password login** dan selalu dikirim sebagai **string** (supaya
   nol di depan tidak hilang). Jangan pernah menyimpan PIN di perangkat, log, atau
   analytics.
 5. **Satu akun customer = satu organisasi.** Saldo berlaku di semua outlet organisasi itu.
 6. **Waktu memakai WIB.** Tanggal kedaluwarsa berarti saldo masih bisa dipakai sampai
   23:59:59 WIB di tanggal itu.
 7. **Hadiah game ditentukan server.** Aplikasi tidak menghitung atau mengirim hadiah.
 ---
@@ -47,13 +50,21 @@ field bernama token sudah dihapus dari API.
 - Base URL: `/api/v1`
 - Semua endpoint customer: header `Authorization: Bearer <token login customer>`
 - Semua jumlah di request dan response berupa integer.
 - Belum ada endpoint refresh token: bila token ditolak (§2.2, `entity` `auth_handler`),
  customer login ulang.
 - **Nomor HP customer selalu disimpan dan dikembalikan dalam format `62…`** (mis.
  `6281234561234`). Di request (registrasi, login, kirim ulang OTP, cek nomor, penerima
  transfer) nomor boleh ditulis `0812…`, `+62 812…`, `62812…`, atau `812…`; backend
  mengubahnya ke `62…`. Hanya nomor HP Indonesia (`628…`) yang diterima; selain itu
  ditolak `304` `invalid phone number format`. Pengecualian: nomor penerima transfer
  yang disamarkan tetap ditampilkan dalam format lokal, `08**-****-1234` (§7.2).
-### Registrasi customer
+### 2.1 Registrasi customer
 `POST /api/v1/customer-auth/register/start` menerima `organization_id` (opsional):
 ```json
-{ "phone_number": "0812…", "name": "Budi", "birth_date": "2000-01-31", "organization_id": "648b96a0-1d1d-414e-baee-37e9d6317b4e" }
+{ "phone_number": "6281234561234", "name": "Budi", "birth_date": "2000-01-31", "organization_id": "648b96a0-1d1d-414e-baee-37e9d6317b4e" }
 ```
 - Customer terdaftar di satu organisasi, dan saldonya berlaku di semua outlet organisasi itu.
@@ -65,7 +76,7 @@ field bernama token sudah dihapus dari API.
 - Wallet customer baru belum punya baris sampai saldo pertama kali bergerak;
  `GET /customer/wallet` tetap menjawab saldo 0.
-### Format response
+### 2.2 Format response
 Sukses:
@@ -73,6 +84,10 @@ Sukses:
 { "success": true, "data": { … }, "errors": null }
 ```
 Semua contoh response di dokumen ini adalah isi `data`. Untuk daftar berhalaman, isi
 itu sendiri berbentuk `{ "data": [ … ], "pagination": { … } }`, jadi array-nya ada di
 `data.data` pada response mentah.
 Gagal:
 ```json
@@ -82,19 +97,19 @@ Gagal:
 | `errors[0].code` | HTTP | Arti | Yang dilakukan app |
 |---|---|---|---|
 | `303`, `310` | 400 | Request tidak lengkap / salah format | Bug di app; tampilkan pesan umum |
-| `304` | 400 | Ditolak aturan bisnis | Tampilkan pesan yang ramah (lihat tiap fitur); `cause` berbahasa Inggris, jangan tampilkan mentah |
+| `304` | 400 | Ditolak aturan bisnis, **atau token tidak berlaku** bila `entity` = `auth_handler` | Pesan yang ramah per fitur; `cause` berbahasa Inggris, jangan tampilkan mentah. Token: login ulang |
-| `404` | 404 | Tidak ditemukan | Tampilkan "tidak ditemukan" |
+| `404` | 404 | Tidak ditemukan, juga untuk data milik customer lain | Tampilkan "tidak ditemukan" |
-| `429` | 429 | Minta OTP terlalu cepat | Tampilkan hitung mundur sebelum boleh minta lagi |
+| `429` | 429 | Minta OTP terlalu cepat, atau terlalu banyak percobaan login (§2.4) | Hitung mundur sebelum boleh minta lagi |
 | `PIN_NOT_SET` | 403 | Belum punya PIN | Buka alur buat PIN (§6.2) |
 | `PIN_INVALID` | 400 | PIN salah | §6.5 |
 | `PIN_LOCKED` | 423 | PIN terkunci | §6.5 |
 | `TRANSFER_BLOCKED` | 403 | Transfer ditahan setelah reset PIN | §6.5 |
 | `900` | 500 | Error server | "Terjadi kesalahan, coba lagi" |
-### Idempotency-Key
+### 2.3 Idempotency-Key
-Endpoint **tukar** dan **transfer** wajib header `Idempotency-Key` (string unik, maks.
+Endpoint **tukar**, **transfer**, dan **tukar voucher** wajib header `Idempotency-Key`
-50 karakter, mis. UUID v4).
+(string unik, maks. 50 karakter, mis. UUID v4; `X-Idempotency-Key` juga diterima).
 - Buat **satu key baru saat customer menekan tombol konfirmasi**.
 - Bila request gagal karena jaringan/timeout, **kirim ulang dengan key yang sama**.
@@ -102,6 +117,25 @@ Endpoint **tukar** dan **transfer** wajib header `Idempotency-Key` (string unik,
  dua kali.
 - Jangan pakai ulang key untuk transaksi yang berbeda; server menolaknya (`304`).
 ### 2.4 Login — `POST /api/v1/customer-auth/login`
 `{ "phone_number": "…", "password": "…" }` → token di `data.data.access_token`.
 | `errors[0].code` | HTTP | Arti | Tampilan |
 |---|---|---|---|
 | `304`, `entity` `customer_auth_service` | 400 | Nomor HP tidak terdaftar, password salah, atau pendaftaran belum selesai | "Nomor HP atau password salah." |
 | `304`, `entity` `request` | 400 | Format nomor HP salah, field kosong | "Periksa nomor HP dan password." |
 | `429` | 429 | Terlalu banyak percobaan; `data.locked_until` (RFC3339 UTC) | "Terlalu banyak percobaan. Coba lagi pukul {jam}." |
 | `900` | 500 | Error server | "Terjadi kesalahan, coba lagi" |
 > **Berubah per 9 Okt 2026.** Sebelumnya nomor HP atau password salah dijawab `900`
 > (HTTP 500) dengan `cause` `invalid password` / `customer not found`. Bila app
 > menangani login gagal dari HTTP 500 atau teks `cause` itu, ganti ke tabel di atas.
 Setiap nomor HP hanya boleh mencoba login 5 kali dalam 15 menit; login yang berhasil
 memulai hitungan dari nol. Percobaan ke-6 ditolak `429` sampai 15 menit itu habis, juga
 bila password-nya benar.
 ---
 ## 3. Layar yang perlu dibuat
@@ -116,7 +150,11 @@ Endpoint **tukar** dan **transfer** wajib header `Idempotency-Key` (string unik,
 | Tukar EnakCoin | `GET …/exchange/preview`, `POST /customer/wallet/exchange` | Ya |
 | Transfer | `GET …/transfer/recipient`, `POST /customer/wallet/transfer` | Ya |
 | PIN (buat, ganti, lupa) | `/customer/pin/*` | – |
-| Game | `GET /customer/enakgame/games`, `POST /customer/enakgame/sessions`, `POST …/sessions/:id/complete` | – |
+| Daftar game + webview game | `GET /customer/enakgame/games` | – |
 | Riwayat main | `GET /customer/enakgame/sessions` | – |
 | Katalog voucher | `GET /customer/vouchers` | – |
 | Tukar voucher | `POST /customer/vouchers/:id/redeem` | Ya |
 | Voucher saya | `GET /customer/vouchers/redemptions` | – |
 | (latar belakang) registrasi push | `PUT` / `DELETE /customer/devices` | – |
 ---
@@ -146,9 +184,10 @@ Tampilkan:
 - Bila `nearest_expiring.point` / `.coin` tidak `null`: banner "{amount} EnakPoint akan
  kedaluwarsa pada {date}" yang membuka layar §4.3.
 - 5 mutasi terakhir dari `recent_transactions`, dengan tautan "Lihat semua" ke §4.2.
- Tombol aksi: Tukar EnakCoin (§7.1), Transfer (§7.2), Main game (§8).
+- Tombol aksi: Tukar EnakCoin (§7.1), Transfer (§7.2), Main game (§8), Voucher (§9).
-Muat ulang beranda setelah setiap transaksi dan saat menerima push (§5).
+Muat ulang beranda setelah setiap transaksi, saat webview game ditutup, dan saat
 menerima push (§5).
 Field `total_points`, `points_history`, `last_updated` di response ini **deprecated**;
 jangan dipakai.
@@ -189,26 +228,34 @@ Query (semua opsional):
 Aturan tampilan:
 - `amount` bertanda: positif tampil hijau dengan `+`, negatif merah dengan `−`.
- `description` sudah siap tampil (nama lawan transfer sudah disamarkan). Tampilkan apa
+- Penambahan membawa `source`, pengurangan membawa `destination`, keduanya `{ type, id }`.
-  adanya.
+- `description` sudah siap tampil (nama lawan transfer sudah disamarkan, nama game dan
  voucher sudah tertulis). Tampilkan apa adanya.
 - Mutasi masuk yang punya `expires_at` menampilkan "Berlaku sampai {tanggal}".
 - Infinite scroll memakai `pagination.total_pages`.
 - Riwayat tidak pernah berubah atau hilang; koreksi muncul sebagai baris baru.
 Label tipe:
-| `type` | Label | Arah |
+| `type` | Mata uang | Label | Arah |
-|---|---|---|
+|---|---|---|---|
-| `EARN` | Dari belanja | + |
+| `EARN` | keduanya | Dari belanja | + |
-| `EARN_REVERSAL` | Dibatalkan (order di-void/refund) | − |
+| `EARN_REVERSAL` | keduanya | Dibatalkan (order di-void/refund) | − |
-| `EXCHANGE_OUT` | Ditukar ke EnakPoint | − |
+| `EXCHANGE_OUT` | EnakCoin | Ditukar ke EnakPoint | − |
-| `EXCHANGE_IN` | Hasil tukar EnakCoin | + |
+| `EXCHANGE_IN` | EnakPoint | Hasil tukar EnakCoin | + |
-| `TRANSFER_OUT` | Transfer keluar | − |
+| `TRANSFER_OUT` | keduanya | Transfer keluar | − |
-| `TRANSFER_IN` | Transfer masuk | + |
+| `TRANSFER_IN` | keduanya | Transfer masuk | + |
-| `GAME_SPEND` | Main game | − |
+| `GAME_SPEND` | EnakCoin | Main game | − |
-| `EXPIRE` | Kedaluwarsa | − |
+| `GAME_SPEND_REFUND` | EnakCoin | Biaya main dikembalikan | + |
-| `ADJUSTMENT` | Koreksi | + / − |
+| `GAME_REWARD` | EnakCoin | Hadiah game | + |
-| `MIGRATION` | Saldo awal | + |
+| `REWARD_REDEEM` | EnakPoint | Ditukar ke voucher | − |
 | `REWARD_REDEEM_REFUND` | EnakPoint | Penukaran voucher dibatalkan | + |
 | `EXPIRE` | keduanya | Kedaluwarsa | − |
 | `ADJUSTMENT` | keduanya | Koreksi | + / − |
 | `MIGRATION` | keduanya | Saldo awal | + |
 Tipe yang tidak dikenal (bila backend menambah tipe baru): tampilkan `description` dan
 arah dari tanda `amount`, tanpa label.
 ### 4.3 Akan kedaluwarsa — `GET /customer/wallet/expiring`
@@ -225,8 +272,6 @@ Label tipe:
 Daftar per tanggal, paling dekat di atas. Daftar kosong: tampilkan "Tidak ada saldo
 yang akan kedaluwarsa". Saldo yang kedaluwarsa hangus tanpa kompensasi.
 ---
 ### 4.4 Daftar outlet — `GET /customer/outlets`
 Outlet aktif di organisasi customer, tempat saldo EnakPoint & EnakCoin berlaku. Urut
@@ -248,7 +293,6 @@ berdasarkan nama.
 - `earns_points` / `earns_coins`: belanja di outlet ini memberi EnakPoint / EnakCoin.
 - Belum ada telepon, koordinat, atau jam buka; data itu belum disimpan di backend.
 ### 4.5 Riwayat order — `GET /customer/orders` dan `GET /customer/orders/:id`
 Order milik customer yang login di semua outlet organisasinya, terbaru di atas. Order
@@ -329,6 +373,7 @@ hanya masuk ke sini bila kasir mengaitkannya ke customer.
 - Order yang `is_void` atau `is_refund` tetap tampil, beri label "Dibatalkan" /
  "Direfund".
 ---
 ## 5. Notifikasi push (FCM)
@@ -344,8 +389,10 @@ Setelah login berhasil **dan** setiap kali FCM memberi token baru (`onTokenRefre
 - `device_id` wajib, stabil untuk satu instalasi (simpan di secure storage).
 - `platform`: `android`, `ios`, atau `web`.
 - Satu token FCM hanya milik satu customer: bila customer lain login di HP yang sama,
  customer sebelumnya tidak lagi menerima notifikasi di HP itu.
 - Saat **logout**, panggil `DELETE /api/v1/customer/devices/{device_id}` sebelum
-  menghapus token login, supaya HP itu tidak lagi menerima notifikasi akun ini.
+  menghapus token login.
 Tanpa registrasi ini, customer tidak menerima push apa pun.
@@ -356,7 +403,7 @@ Semua nilai di `data` berupa string.
 | `data.type` | Kapan | Isi `data` lain | Aksi saat di-tap |
 |---|---|---|---|
 | `WALLET_TRANSFER_IN` | Menerima transfer | `transaction_id`, `group_id`, `currency`, `amount` | Buka riwayat, sorot transaksi itu |
-| `WALLET_EXPIRING` | Beberapa hari sebelum saldo hangus | `currency`, `amount`, `expiry_date` | Buka layar kedaluwarsa (§4.3) |
+| `WALLET_EXPIRING` | `reminder_days` hari sebelum saldo hangus | `currency`, `amount`, `expiry_date` | Buka layar kedaluwarsa (§4.3) |
 | `WALLET_EXPIRED` | Saldo baru saja hangus | `currency`, `amount` | Buka riwayat |
 | `PIN_LOCKED` | PIN terkunci setelah 5 kali salah | `locked_until` (RFC3339 UTC) | Buka layar lupa PIN (§6.4) |
@@ -369,7 +416,7 @@ Saat app terbuka dan menerima push wallet, muat ulang beranda.
 ### 6.1 Kapan diminta
 Jangan minta PIN saat registrasi. Minta saat customer **pertama kali** melakukan aksi
-yang butuh PIN. Cek dengan:
+yang butuh PIN (tukar, transfer, tukar voucher). Cek dengan:
 `GET /api/v1/customer/pin/status` → `{ "has_pin": false, "locked_until": null, "transfer_blocked_until": null }`
@@ -403,7 +450,7 @@ Minta OTP lagi terlalu cepat → `429`: tampilkan hitung mundur.
 2. `POST /customer/pin/reset` dengan `{ "otp_token", "otp_code", "pin", "confirm_pin" }`.
 Reset juga membuka PIN yang terkunci. Setelah reset, **transfer keluar ditahan 24 jam**;
-tukar tetap bisa. Beri tahu customer hal ini di layar sukses.
+tukar EnakCoin dan tukar voucher tetap bisa. Beri tahu customer hal ini di layar sukses.
 ### 6.5 Menangani error PIN
@@ -467,14 +514,17 @@ ditolak. Penghitung ada di server, jadi jangan membuat penghitung sendiri di app
   ```
 3. Layar sukses: saldo baru, dan bila `lots[].expires_at` ada, "EnakPoint ini berlaku
-   sampai {tanggal}".
+   sampai {tanggal}". EnakPoint hasil tukar tidak bisa hidup lebih lama dari EnakCoin
   asalnya.
 Jumlah yang salah ditolak sebelum PIN dicek, jadi tidak memakan jatah percobaan PIN.
 ### 7.2 Transfer
 1. Pilih mata uang (EnakPoint / EnakCoin), isi nomor HP penerima dan jumlah.
 2. Cek penerima:
-   `GET /api/v1/customer/wallet/transfer/recipient?phone=081234561234`
+   `GET /api/v1/customer/wallet/transfer/recipient?phone=6281234561234`
   ```json
   { "name": "Bu*** Sa***", "phone_number": "08**-****-1234" }
@@ -491,7 +541,7 @@ ditolak. Penghitung ada di server, jadi jangan membuat penghitung sendiri di app
   `POST /api/v1/customer/wallet/transfer` + header `Idempotency-Key`
   ```json
-   { "currency": "POINT", "amount": 120, "recipient_phone": "081234561234", "pin": "482913" }
+   { "currency": "POINT", "amount": 120, "recipient_phone": "6281234561234", "pin": "482913" }
   ```
   ```json
@@ -522,37 +572,227 @@ Penerima mendapat push `WALLET_TRANSFER_IN`.
 ---
-## 8. Game (memakai EnakCoin)
+## 8. Game (EnakGame)
-`POST /api/v1/customer/spin`, `GET /customer/games`, dan `GET /customer/ferris-wheel`
+Game dimainkan di **webview** yang memuat `game_url` tiap game. Pembagian tugasnya:
-sudah dihapus. Semua game, termasuk spin, dimainkan lewat EnakGame. Tanpa PIN.
+aplikasi menampilkan daftar game, membuka webview, dan memberi token lewat bridge; game
 EnakGame sendiri yang memulai session, memotong EnakCoin, mengirim hasil, dan
 menampilkan hadiah ([`integration-enakgame.md`](./integration-enakgame.md)). Aplikasi
 **tidak** memanggil `POST /customer/enakgame/sessions` atau `…/complete`.
-1. `GET /api/v1/customer/enakgame/games`: daftar game dengan `entry_cost` (EnakCoin per
+### 8.1 Daftar game — `GET /customer/enakgame/games`
   main). Tampilkan biaya sebelum main, dan nonaktifkan tombol bila `coin_balance`
   kurang. Spin punya `prizes` untuk menggambar roda.
 2. `POST /api/v1/customer/enakgame/sessions` dengan `{ "game_id": "…" }` dan header
   `Idempotency-Key` (satu key per tap; retry memakai key yang sama). Response berisi
   `session_id` dan `coin_balance` setelah dipotong.
 3. `POST /api/v1/customer/enakgame/sessions/:id/complete` dengan hasil main (`score`
   atau `outcome`; spin cukup `{}`). Server yang menentukan hadiah: perbarui saldo dari
   `coin_balance`, tampilkan `reward_total`, dan untuk spin hentikan roda di `prize.entry`.
-Rincian spin ada di [`enakgame-spin.md`](./enakgame-spin.md).
+```json
 [
  {
    "id": "8a1f…",
    "slug": "spin",
    "name": "Spin Harian",
    "description": null,
    "thumbnail_url": "https://…/spin.png",
    "game_url": "https://…/spin/index.html",
    "version": "1.2.0",
    "entry_cost": 5,
    "session_ttl_seconds": 600,
    "events": [
      { "id": "…", "name": "Ramadan 2x", "banner_url": "https://…", "multiplier": 2, "bonus": null, "end_at": "2026-10-31T16:59:59Z" }
    ],
    "prizes": [ { "entry": 1, "label": "Zonk", "amount": 0 } ]
  }
 ]
 ```
 Tampilkan:
 - Kartu per game: `thumbnail_url`, `name`, biaya "{entry_cost} EnakCoin".
 - Badge event bila `events` tidak kosong: `name` atau `banner_url`, dan "berakhir
  {end_at}" (tampilkan dalam WIB).
 - Tombol Main nonaktif dengan teks "EnakCoin kurang" bila `coin_balance` (§4.1) lebih
  kecil dari `entry_cost`.
 - `prizes` hanya dipakai game spin di dalam webview; aplikasi boleh mengabaikannya.
 Game yang dinonaktifkan admin hilang dari daftar ini. Muat ulang daftar setiap kali
 layar dibuka.
 ### 8.2 Membuka game
 1. Customer menekan Main → buka webview layar penuh dengan `game_url`.
 2. Pasang bridge (§8.3) **sebelum** halaman dimuat.
 3. Saat game mengirim `ready`, jawab dengan `init`.
 4. Saat game mengirim `close`, tutup webview, lalu muat ulang beranda wallet (§4.1).
 Jangan menaruh token di URL `game_url` (query string atau fragment): URL bisa tercatat di
 log server game dan riwayat webview.
 ### 8.3 Bridge (sisi aplikasi)
 > **Usulan.** Kontrak ini sama dengan [`integration-enakgame.md`](./integration-enakgame.md)
 > §4 dan belum diimplementasikan. Sepakati dengan tim EnakGame sebelum mulai.
 - Game → aplikasi: JavaScript channel webview bernama **`EnakGameHost`**; setiap pesan
  berupa JSON string.
 - Aplikasi → game: jalankan `window.enakGame.receive('<json>')` di webview.
 | Pesan masuk dari game | Yang dilakukan aplikasi |
 |---|---|
 | `{ "type": "ready" }` | Kirim `{ "type": "init", "api_base_url": "<base URL>/api/v1", "token": "<access token customer>", "game_id": "<id game yang dibuka>" }`. Jawab setiap `ready`, termasuk setelah halaman game dimuat ulang. Access token, bukan refresh token (ditolak backend) |
 | `{ "type": "balance_changed", "coin_balance": 15 }` | Perbarui saldo EnakCoin yang ditampilkan aplikasi |
 | `{ "type": "close" }` | Tutup webview, muat ulang beranda |
 Bila token kosong atau ditolak backend, game menampilkan layar login akun customer
 sendiri; aplikasi tidak perlu menangani apa pun, dan token hasil login di game tidak
 dikirim balik ke aplikasi.
 Abaikan pesan dengan `type` lain. Tombol back Android jangan langsung menutup webview:
 tampilkan konfirmasi "Keluar dari game? EnakCoin yang sudah dipakai untuk main tidak
 kembali", lalu tutup. Tidak perlu mengirim pesan ke game.
 ### 8.4 Riwayat main — `GET /customer/enakgame/sessions?page=1&limit=20`
 Query opsional `game_id` (riwayat satu game) dan `status` (`STARTED`, `COMPLETED`,
 `REFUNDED`, `EXPIRED`) untuk filter atau tab.
 ```json
 {
  "data": [
    {
      "id": "…", "game_id": "8a1f…", "status": "COMPLETED", "entry_cost": 5, "reward_total": 10,
      "started_at": "…", "expires_at": "…", "ended_at": "…", "refund_reason": null
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total_count": 3, "total_pages": 1 }
 }
 ```
 | `status` | Label | Keterangan |
 |---|---|---|
 | `STARTED` | Sedang dimainkan | |
 | `COMPLETED` | Selesai | "Dapat {reward_total} EnakCoin" |
 | `REFUNDED` | Dikembalikan | Entry cost kembali; `refund_reason` `SYSTEM_ERROR` atau `GAME_DEACTIVATED` |
 | `EXPIRED` | Tidak selesai | Hasil tidak dikirim sebelum batas waktu; entry cost tidak kembali |
 Nama game diambil dari daftar game (§8.1) lewat `game_id`. Detail satu session:
 `GET /customer/enakgame/sessions/:id`.
 ---
-## 9. Yang sudah dihapus / deprecated
+## 9. Voucher (tukar EnakPoint)
 ### 9.1 Katalog — `GET /customer/vouchers`
 Voucher yang bisa ditukar sekarang: aktif, dalam masa berlaku, dan masih ada stoknya.
 ```json
 [
  {
    "id": "…",
    "name": "Kopi Susu Gratis",
    "description": "Berlaku untuk ukuran regular",
    "image_url": "https://…/kopi.png",
    "voucher_type": "FREE_ITEM",
    "face_value": 20000,
    "point_cost": 15000,
    "max_per_customer": 2,
    "valid_until": "2026-12-31T16:59:59Z",
    "terms": { "…": "syarat & ketentuan, objek JSON bebas" },
    "available": 120
  }
 ]
 ```
 - `point_cost`: EnakPoint yang dipotong. Tombol Tukar nonaktif bila `point_balance`
  kurang.
 - `face_value`: nilai voucher dalam rupiah, tampilkan sebagai "senilai Rp 20.000".
 - `available`: sisa stok; `null` berarti stok tidak dihitung. Bila 0, tampilkan "Habis".
 - `max_per_customer`: batas tukar per customer; `null` = tanpa batas.
 - `terms`: objek JSON yang isinya diatur admin. Sepakati bentuknya dengan tim
  backoffice; sebelum itu tampilkan `description` saja.
 | `voucher_type` | Label usulan |
 |---|---|
 | `FIXED_VALUE` | Potongan Rp {face_value} |
 | `PERCENTAGE` | Potongan persen |
 | `FREE_ITEM` | Gratis item |
 | `MERCHANT_BENEFIT` | Benefit merchant |
 ### 9.2 Tukar — `POST /customer/vouchers/:id/redeem`
 Konfirmasi ("Tukar {point_cost} EnakPoint dengan {name}? Tidak bisa dibatalkan.") →
 minta PIN → kirim dengan header `Idempotency-Key`:
 ```json
 { "pin": "482913" }
 ```
 ```json
 {
  "id": "…",
  "voucher_id": "…",
  "voucher_name": "Kopi Susu Gratis",
  "voucher_image_url": "https://…/kopi.png",
  "voucher_type": "FREE_ITEM",
  "status": "COMPLETED",
  "face_value": 20000,
  "point_cost": 15000,
  "code": "KOPI-7F3C-2291",
  "code_expires_at": "2026-12-31T16:59:59Z",
  "completed_at": "…",
  "created_at": "…",
  "point_balance": 2500,
  "replayed": false
 }
 ```
 - Layar sukses: voucher, `code` bila ada (bisa disalin), masa berlaku, dan saldo
  EnakPoint baru (`point_balance`).
 - `code` bisa `null`: voucher ini tidak memakai kode; tunjukkan layar voucher ke kasir.
 - `status: "PENDING"`: voucher sedang diproses penyedia luar (belum ada voucher seperti
  ini di katalog, tapi tangani dari sekarang). EnakPoint sudah terpotong;
  tampilkan "Voucher sedang diproses" dan cek lagi di Voucher saya (§9.3). Bila akhirnya
  `FAILED`, EnakPoint dikembalikan otomatis (mutasi `REWARD_REDEEM_REFUND`).
 - Error PIN ditangani sesuai §6.5.
 | Penolakan `304` (`cause`) | Tampilan |
 |---|---|
 | `not enough EnakPoint` | "EnakPoint kamu kurang." |
 | `the voucher is out of stock` | "Voucher sudah habis." Muat ulang katalog |
 | `this voucher can be redeemed at most … times per customer` | "Kamu sudah mencapai batas penukaran voucher ini." |
 | `the voucher is not available`, `… cannot be redeemed yet`, `… has ended`, `… not available yet` | "Voucher tidak tersedia." Muat ulang katalog |
 | `the customer is not active` | "Akun tidak aktif." |
 | `this Idempotency-Key was already used to redeem another voucher` | Bug di app: key dipakai ulang |
 ### 9.3 Voucher saya — `GET /customer/vouchers/redemptions?page=1&limit=20`
 Daftar penukaran customer, terbaru di atas, dengan bentuk item sama seperti response
 §9.2 (tanpa `point_balance` dan `replayed`). Seperti semua daftar berhalaman di dokumen
 ini, array-nya ada di `data.data` dan pagination di `data.pagination` di dalam amplop
 response (§2.2); daftar kosong berupa `[]`.
 | `status` | Tampilan |
 |---|---|
 | `COMPLETED` | Voucher siap dipakai: nama, `code` (bila ada), berlaku sampai `code_expires_at` |
 | `PENDING` | "Sedang diproses" |
 | `FAILED` | "Gagal, EnakPoint sudah dikembalikan" |
 **Memakai voucher di outlet:** customer menunjukkan layar voucher ke kasir. POS belum
 bisa menandai voucher terpakai, jadi aplikasi belum bisa menampilkan status "sudah
 dipakai" ([`integration-pos.md`](./integration-pos.md) §5).
 ---
 ## 10. Yang sudah dihapus / deprecated
 Sudah **dihapus** dari API (jangan dipanggil, akan error / tidak ada):
 | Lama | Pengganti |
 |---|---|
 | `POST /customer/spin` | Game EnakGame di webview (§8) |
 | `GET /customer/games`, `GET /customer/ferris-wheel` | `GET /customer/enakgame/games` |
 | `coins_used`, `coins_remaining`, `prize_won`, `game_play` di response spin | Tidak ada; hasil game ditampilkan di dalam game |
 | `metadata.coin_cost` pada data game | `entry_cost` |
 | `GET /customer/tokens` | `GET /customer/wallet` → `coin_balance` |
-| `total_tokens`, `tokens_history` | `coin_balance`, `GET /customer/wallet/transactions?currency=COIN` |
+| `total_tokens`, `tokens_history`, `token_used`, `tokens_remaining` | `coin_balance`, `GET /customer/wallet/transactions?currency=COIN` |
 | `token_used`, `tokens_remaining` di response game | `coins_used`, `coins_remaining` |
 | `POST /customer/wallet/payment-code` | Tidak ada; EnakPoint tidak bisa untuk bayar |
 | `POST /customer/orders/:id/pay-with-points` | Tidak ada; EnakPoint tidak bisa untuk bayar |
 | `GET /orders/:id/point-payment/preview` (POS) | Tidak ada; EnakPoint tidak bisa untuk bayar |
 | `accepts_point_payment` di `GET /customer/outlets` | – |
 | `points_used`, `point_value` di `payments` pada `GET /customer/orders/:id` | – |
 | Tipe mutasi `PAYMENT`, `PAYMENT_REFUND` di riwayat | Tidak ditulis lagi |
@@ -566,18 +806,22 @@ Masih ada tapi **deprecated** (akan dihapus, jangan dipakai di kode baru):
 ---
-## 10. Checklist selesai
+## 11. Checklist selesai
 - [ ] Beranda menampilkan saldo EnakPoint ("setara potongan Rp …"), EnakCoin, dan banner kedaluwarsa terdekat.
- [ ] Riwayat dengan tab per mata uang, filter tipe/tanggal, infinite scroll, label tipe sesuai §4.2.
+- [ ] Riwayat dengan tab per mata uang, filter tipe/tanggal, infinite scroll, dan label semua tipe di §4.2, termasuk tipe game dan voucher.
 - [ ] Layar saldo akan kedaluwarsa.
 - [ ] Registrasi device FCM setelah login dan saat token berganti; unregister saat logout.
 - [ ] Penanganan tap untuk keempat tipe push.
 - [ ] PIN diminta hanya saat aksi yang membutuhkan; alur buat, ganti, dan lupa PIN lewat OTP.
- [ ] Keempat error PIN ditangani di semua layar yang meminta PIN.
+- [ ] Keempat error PIN ditangani di semua layar yang meminta PIN (tukar, transfer, voucher).
 - [ ] Tukar dengan preview, kelipatan kurs, konfirmasi, `Idempotency-Key`, retry dengan key sama.
 - [ ] Transfer dengan cek penerima tersamar, konfirmasi, `Idempotency-Key`, retry dengan key sama.
- [ ] Game memakai `coins_used` / `coins_remaining` dan menampilkan biaya per game.
+- [ ] Daftar game dengan biaya, badge event, dan tombol nonaktif bila EnakCoin kurang.
 - [ ] Webview game dengan bridge §8.3; token tidak pernah di URL; beranda dimuat ulang saat game ditutup.
 - [ ] Riwayat main dengan label status.
 - [ ] Katalog voucher, tukar dengan PIN dan `Idempotency-Key`, status `PENDING` ditangani.
 - [ ] Voucher saya dengan kode yang bisa disalin.
 - [ ] Riwayat order dengan pagination dan layar detail (item, pembayaran, EnakPoint/EnakCoin yang didapat).
- [ ] Tidak ada pemakaian endpoint atau field di §9.
+- [ ] Tidak ada pemakaian endpoint atau field di §10.
- [ ] PIN tidak pernah disimpan, di-log, atau dikirim ke analytics.
+- [ ] PIN dan token tidak pernah disimpan sembarangan, di-log, atau dikirim ke analytics.
@@ -0,0 +1,142 @@
 # Integrasi POS: EnakPoint, EnakCoin & Voucher
 **Untuk:** tim aplikasi POS (kasir) · **Base URL:** `/api/v1` · **Per:** 8 Okt 2026
 Kamu mengerjakan aplikasi **POS** yang dipakai kasir di outlet. Dokumen ini menjelaskan
 bagian program loyalitas yang menyentuh POS: mengaitkan customer ke order, menampilkan
 EnakPoint dan EnakCoin yang didapat, void/refund, dan voucher. Jangan mengarang
 endpoint, field, atau aturan yang tidak tertulis di sini; kalau ada yang kurang jelas,
 tanyakan ke tim backend.
 Dokumen ini menggantikan bagian POS di `integration-enakpoint.md` dan `api-enakpoint.md`.
 ---
 ## 1. Yang perlu diketahui kasir
 | | EnakPoint (`POINT`) | EnakCoin (`COIN`) |
 |---|---|---|
 | Didapat dari | Belanja (order lunas), hasil tukar EnakCoin, koreksi admin | Belanja, hadiah game, koreksi admin |
 | Dipakai untuk | **Ditukar ke voucher** di aplikasi customer | Main game, ditukar ke EnakPoint |
 | Bisa membayar order | **Tidak** | **Tidak** |
 - **EnakPoint bukan alat bayar.** Tidak ada payment method EnakPoint di POS, dan saldo
  tidak bisa dicairkan. Customer menukar EnakPoint ke voucher di aplikasinya sendiri.
 - Saldo berlaku di **semua outlet** organisasi. Berapa yang didapat per order diatur
  **per outlet** oleh owner di backoffice.
 - Semua jumlah bilangan bulat.
 ---
 ## 2. Mengaitkan customer ke order
 Earning hanya terjadi bila order dikaitkan ke customer terdaftar. Order tanpa customer,
 dengan **customer default (walk-in)**, atau dengan customer nonaktif tidak mendapat
 apa-apa.
 1. **Cari customer:** `GET /api/v1/customers?search=0812…&page=1&limit=20`
   (cocok dengan nama, email, atau nomor HP). Abaikan customer dengan `is_default: true`.
 2. **Kaitkan** dengan salah satu cara:
   - saat membuat order: `POST /api/v1/orders` dengan `"customer_id": "…"`, atau
   - setelah order dibuat: `PUT /api/v1/orders/:id/customer` dengan
     `{ "customer_id": "…" }`.
 **Kaitkan sebelum order lunas.** Earning dihitung saat order menjadi lunas penuh.
 Customer yang dikaitkan setelah lunas tetap mendapat earning lewat job susulan yang
 berjalan tiap 30 menit untuk order lunas 72 jam terakhir, tapi tidak langsung, sehingga
 struk akan menulis 0.
 ---
 ## 3. Earning: yang didapat dari order
 Earning berjalan otomatis di backend saat order lunas lewat jalur pembayaran mana pun
 (`POST /payments`, update order, split bill). POS tidak memanggil apa-apa.
 - **Basis** = `subtotal − discount_amount`, **sebelum pajak** dan biaya lain.
 - Rumus per outlet (diatur owner): mode `PER_AMOUNT`
  `floor(basis ÷ earn_per_amount) × earn_value`, atau mode `PERCENTAGE`
  `floor(basis × earn_percent ÷ 100)`, dengan minimal belanja dan batas per order.
 - Contoh: basis Rp 87.500, outlet memberi 1 EnakPoint per Rp 100 dan 1 EnakCoin per
  Rp 25.000 → **875 EnakPoint** dan **3 EnakCoin**.
 Response order (`GET /api/v1/orders/:id` dan response order lainnya) membawa:
 ```json
 { "points_earned": 875, "coins_earned": 3 }
 ```
 Keduanya 0 bila order tidak mendapat apa-apa. **Cetak di struk**, mis. "Kamu mendapat
 875 EnakPoint & 3 EnakCoin". Ambil nilainya setelah pembayaran terakhir berhasil; bila
 masih 0 padahal customer sudah dikaitkan, earning akan menyusul (§2).
 ---
 ## 4. Void dan refund
 Tidak ada langkah tambahan di POS. Saat order di-void atau direfund, backend menarik
 kembali yang didapat dari order itu (mutasi `EARN_REVERSAL` di riwayat customer):
 | Kejadian | Yang ditarik |
 |---|---|
 | Void | Semua EnakPoint dan EnakCoin dari order itu |
 | Refund (sebagian atau penuh) | `floor(earned × total_refund ÷ basis)`, tidak pernah lebih dari yang didapat; refund berikutnya hanya menarik sisanya |
 Bila saldo customer sudah terpakai, yang ditarik sebanyak yang ada. **Refund tidak
 pernah diblokir** karena ini.
 ---
 ## 5. Voucher dari EnakPoint
 Customer menukar EnakPoint ke voucher di aplikasi customer. Voucher yang didapat tampil
 di menu "Voucher saya" di aplikasi itu, dengan nama, nilai (`face_value`), jenis, dan
 bila ada, **kode** serta tanggal berlakunya.
 > **Belum tersedia:** POS belum punya endpoint untuk **mengecek** atau **menandai
 > voucher sudah dipakai**. Ini pekerjaan lanjutan di backend.
 Sampai endpoint itu ada:
 1. Kasir melihat voucher di layar aplikasi customer (nama, nilai, kode, masa berlaku).
 2. Kasir memasukkan potongannya sebagai **diskon biasa** di order, sesuai jenisnya:
   | `voucher_type` | Cara memasukkan |
   |---|---|
   | `FIXED_VALUE` | Diskon nominal sebesar `face_value` |
   | `PERCENTAGE` | Diskon persen sesuai syarat voucher |
   | `FREE_ITEM` | Item gratis sesuai syarat voucher |
   | `MERCHANT_BENEFIT` | Sesuai syarat voucher |
 3. Karena backend belum mencatat voucher terpakai, outlet perlu mencatat kode yang
   sudah dipakai secara manual supaya voucher yang sama tidak dipakai dua kali.
 Diskon dari voucher mengurangi basis earning seperti diskon lain (§3).
 ---
 ## 6. Yang sudah dihapus
 Bayar dengan EnakPoint dihapus pada 7 Okt 2026. Jangan dipanggil atau ditampilkan lagi;
 tidak ada penggantinya.
 | Dihapus | Catatan |
 |---|---|
 | Payment method tipe `point` ("EnakPoint") | Tidak ada di daftar payment method |
 | Field `points` dan `payment_code` di `POST /payments` | `amount` wajib seperti pembayaran lain |
 | `GET /orders/:id/point-payment/preview` | – |
 | Kode bayar dari aplikasi customer | – |
 | `points_used`, `point_value` di response pembayaran | – |
 | `point_amount`, `points_used`, `total_with_points`, `counts_as_cash_in` di laporan payment method | `summary.total_amount` adalah total semua method |
 ---
 ## 7. Checklist
 - [ ] Kasir bisa mencari dan mengaitkan customer ke order sebelum pembayaran.
 - [ ] Customer default (walk-in) tidak ditawarkan sebagai pemilik earning.
 - [ ] Struk mencetak `points_earned` dan `coins_earned`.
 - [ ] Tidak ada payment method EnakPoint dan tidak ada field pembayaran EnakPoint di
      request.
 - [ ] Void/refund tidak menampilkan langkah tambahan untuk EnakPoint/EnakCoin.
 - [ ] SOP outlet untuk voucher manual (§5) sudah disepakati sampai endpoint POS tersedia.
@@ -388,7 +388,8 @@ beredar. Karena itu:
 > **Diganti EnakGame (2026-10-07).** Alur game di bawah (`POST /customer/spin`,
 > `metadata.coin_cost`, `game_plays`) sudah dihapus. Game sekarang dimainkan lewat
 > `/customer/enakgame/sessions` dengan `games.entry_cost`; lihat
-> [RFC EnakGame](rfc-enakgame.md) §14 dan [enakgame-spin.md](enakgame-spin.md).
+> [RFC EnakGame](rfc-enakgame.md) §14, [integration-backoffice.md](integration-backoffice.md) §8.4,
 > dan [integration-enakgame.md](integration-enakgame.md).
 > EnakCoin tetap mata uang untuk bermain game.
 - **Semua jenis game** (`SPIN`, ferris wheel, `RAFFLE`, `MINIGAME`) memotong EnakCoin
@@ -636,7 +636,7 @@ menanganinya, dan complete di §7.2 langkah 4 menangani yang lebih cepat.
 ### 7.4 Redemption voucher internal (`STATIC`, `CODE_POOL`)
 ```
-POST /customer/enakgame/vouchers/:id/redeem   { pin }   Idempotency-Key: <≤50 char>
+POST /customer/vouchers/:id/redeem   { pin }   Idempotency-Key: <≤50 char>
 ```
 Satu transaksi, sehingga state `RESERVED` tidak diperlukan:
@@ -842,13 +842,22 @@ tambahkan snapshot harian, bukan cache yang di-invalidate.
 | `POST` | `/sessions` | §7.1. Wajib `Idempotency-Key` |
 | `POST` | `/sessions/:id/complete` | §7.2. Idempotent tanpa header |
 | `GET` | `/sessions/:id` | Status dan hasil |
-| `GET` | `/sessions` | Riwayat main |
+| `GET` | `/sessions` | Riwayat main; filter opsional `game_id`, `status` (dipakai game untuk menemukan session `STARTED` setelah reload) |
-| `GET` | `/vouchers` | Katalog `ACTIVE` + stok tersedia |
+| `GET` | `/leaderboard` | Peringkat mingguan (Senin–Minggu, Asia/Jakarta) org customer menurut EnakCoin yang dimenangkan dari game. Query opsional `date` (hari mana pun dalam minggu itu), `game_id`, `limit` (default 10, maks 100) |
 | `POST` | `/vouchers/:id/redeem` | §7.4 / §7.5. Wajib `Idempotency-Key` + PIN |
 | `GET` | `/redemptions` | Voucher milik customer, termasuk kode |
 Prefix `/enakgame` dipakai karena `/customer/games` sudah dipakai alur spin lama.
 ### Voucher customer (`/api/v1/customer/vouchers`, `ValidateCustomerToken`)
 Voucher adalah tempat memakai EnakPoint dari mana pun asalnya, bukan bagian dari game,
 jadi tidak di bawah `/enakgame` (diubah 2026-10-08).
 | Method | Path | Catatan |
 |---|---|---|
 | `GET` | `/vouchers` | Katalog `ACTIVE` + stok tersedia |
 | `POST` | `/vouchers/:id/redeem` | §7.4 / §7.5. Wajib `Idempotency-Key` + PIN |
 | `GET` | `/vouchers/redemptions` | Voucher milik customer, termasuk kode |
 ### Admin (`/api/v1/marketing/enakgame`, `RequireAdminOrManager`)
 | Resource | Endpoint |
@@ -858,7 +867,7 @@ Prefix `/enakgame` dipakai karena `/customer/games` sudah dipakai alur spin lama
 | Events | CRUD, `PUT /:id/status` |
 | Budgets | CRUD, `GET /:id/metrics`, `GET /:id/recommendation`, `POST /:id/recommendation/accept` |
 | Analytics | `GET /analytics/games?from=&to=&game_id=`, `GET /analytics/economy?from=&to=` (tanggal Asia/Jakarta, maks 366 hari) |
-| Vouchers | CRUD, `POST /:id/codes` (impor CSV), `GET /:id/codes` |
+| Vouchers | Di `/api/v1/marketing/vouchers`, bukan di bawah `/enakgame`: CRUD, `PUT /:id/status`, `POST /:id/codes` (impor CSV), `GET /:id/codes` |
 | Redemptions | `GET` list, `GET /:id` dengan atribusi cost |
 | Sessions | `GET` list + filter `flagged` |
 | Settings | Lewat endpoint loyalty settings yang ada, dengan key baru (§5.10) |
@@ -932,7 +941,8 @@ Ditemukan saat memetakan code. Tidak memblokir RFC ini, tapi sebagian berdampak
 ## 16. Di Luar Scope
 - **Mission** (PRD §3.1, §19). PRD belum mendefinisikan aturannya.
- **Leaderboard** (PRD §15).
+- **Leaderboard event** (PRD §15). Leaderboard mingguan umum sudah ada (§11, ditambahkan
  2026-10-12); leaderboard per event dengan aturannya sendiri belum.
 - **Reward `TIERED`** (§8).
 - **Budget Controller automatic mode** (D9).
 - **Hosting dan build Phaser.** RFC ini hanya mendefinisikan API yang dipanggil game.
@@ -307,6 +307,7 @@ type repositories struct {
 	campaignRepo                   repository.CampaignRepository
 	campaignRuleRepo               repository.CampaignRuleRepository
 	customerAuthRepo               repository.CustomerAuthRepository
 	customerLoginAttemptRepo       repository.CustomerLoginAttemptRepository
 	otpRepo                        repository.OtpRepository
 	sessionRepo                    repository.SessionRepository
 	txManager                      *repository.TxManager
@@ -359,6 +360,7 @@ func (a *App) initRepositories() *repositories {
 		campaignRepo:                   repository.NewCampaignRepository(a.db),
 		campaignRuleRepo:               repository.NewCampaignRuleRepository(a.db),
 		customerAuthRepo:               repository.NewCustomerAuthRepository(a.db),
 		customerLoginAttemptRepo:       repository.NewCustomerLoginAttemptRepository(a.redisClient),
 		otpRepo:                        repository.NewOtpRepository(a.db),
 		sessionRepo:                    repository.NewSessionRepository(a.redisClient),
 		txManager:                      repository.NewTxManager(a.db),
@@ -488,7 +490,7 @@ func (a *App) initProcessors(cfg *config.Config, repos *repositories) *processor
 		omsetTrackerProcessor:               processor.NewOmsetTrackerProcessor(repos.omsetTrackerRepo),
 		campaignProcessor:                   processor.NewCampaignProcessor(repos.campaignRepo),
 		campaignRuleProcessor:               processor.NewCampaignRuleProcessor(repos.campaignRuleRepo),
-		customerAuthProcessor:               processor.NewCustomerAuthProcessor(repos.customerAuthRepo, otpProcessor, repos.otpRepo, cfg.GetCustomerJWTSecret(), cfg.GetCustomerJWTExpiresTTL()),
+		customerAuthProcessor:               processor.NewCustomerAuthProcessor(repos.customerAuthRepo, repos.customerLoginAttemptRepo, otpProcessor, repos.otpRepo, cfg.GetCustomerJWTSecret(), cfg.GetCustomerJWTExpiresTTL()),
 		customerPointsProcessor:             processor.NewCustomerPointsProcessor(processor.NewWalletQueryProcessor(repos.walletQueryRepo, processor.NewLoyaltySettingsProcessor(repos.loyaltySettingsRepo, repos.txManager))),
 		otpProcessor:                        otpProcessor,
 		fileClient:                          fileClient,
@@ -67,6 +67,7 @@ const (
 	EnakGameServiceEntity           = "enakgame_service"
 	LoyaltySettingsServiceEntity    = "loyalty_settings_service"
 	CustomerPinServiceEntity        = "customer_pin_service"
 	CustomerAuthServiceEntity       = "customer_auth_service"
 )
 var HttpErrorMap = map[string]int{
@@ -8,7 +8,7 @@ type StartGameSessionRequest struct {
 	GameID uuid.UUID `json:"game_id" binding:"required"`
 }
-// RedeemVoucherRequest is POST /customer/enakgame/vouchers/:id/redeem (§7.4). The
+// RedeemVoucherRequest is POST /customer/vouchers/:id/redeem (§7.4). The
 // Idempotency-Key header is required.
 type RedeemVoucherRequest struct {
 	Pin string `json:"pin" binding:"required"`
@@ -1,9 +1,12 @@
 package handler
 import (
 	"errors"
 	"apskel-pos-be/internal/constants"
 	"apskel-pos-be/internal/contract"
 	"apskel-pos-be/internal/logger"
 	"apskel-pos-be/internal/processor"
 	"apskel-pos-be/internal/service"
 	"apskel-pos-be/internal/util"
 	"apskel-pos-be/internal/validator"
@@ -161,13 +164,36 @@ func (h *CustomerAuthHandler) Login(c *gin.Context) {
 	response, err := h.customerAuthService.Login(ctx, &req)
 	if err != nil {
 		logger.FromContext(c.Request.Context()).WithError(err).Error("CustomerAuthHandler::Login -> service call failed")
-		util.HandleResponse(c.Writer, c.Request, contract.BuildErrorResponse([]*contract.ResponseError{contract.NewResponseError(constants.InternalServerErrorCode, constants.RequestEntity, err.Error())}), "CustomerAuthHandler::Login")
+		util.HandleResponse(c.Writer, c.Request, loginErrorResponse(err), "CustomerAuthHandler::Login")
 		return
 	}
 	util.HandleResponse(c.Writer, c.Request, contract.BuildSuccessResponse(response), "CustomerAuthHandler::Login")
 }
 // loginErrorResponse answers a phone number with too many attempts with 429 and when it
 // may try again, a refused login with 304 and its reason, and anything else with 900.
 func loginErrorResponse(err error) *contract.Response {
 	var locked *processor.CustomerLoginLockedError
 	if errors.As(err, &locked) {
 		return &contract.Response{
 			Success: false,
 			Data:    map[string]interface{}{"locked_until": locked.Until},
 			Errors:  []*contract.ResponseError{contract.NewResponseError(constants.TooManyRequestsErrorCode, constants.CustomerAuthServiceEntity, locked.Error())},
 		}
 	}
 	for _, refused := range []error{processor.ErrCustomerLoginInvalid, processor.ErrCustomerNotRegistered} {
 		if errors.Is(err, refused) {
 			return contract.BuildErrorResponse([]*contract.ResponseError{
 				contract.NewResponseError(constants.ValidationErrorCode, constants.CustomerAuthServiceEntity, refused.Error()),
 			})
 		}
 	}
 	return contract.BuildErrorResponse([]*contract.ResponseError{
 		contract.NewResponseError(constants.InternalServerErrorCode, constants.RequestEntity, err.Error()),
 	})
 }
 func (h *CustomerAuthHandler) ResendOtp(c *gin.Context) {
 	ctx := c.Request.Context()
@@ -0,0 +1,245 @@
 package handler
 import (
 	"bytes"
 	"context"
 	"encoding/json"
 	"errors"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 	"time"
 	"github.com/gin-gonic/gin"
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"golang.org/x/crypto/bcrypt"
 	"apskel-pos-be/internal/entities"
 	applogger "apskel-pos-be/internal/logger"
 	"apskel-pos-be/internal/processor"
 	"apskel-pos-be/internal/service"
 	"apskel-pos-be/internal/validator"
 )
 // customerAuthRepoFake holds customers by phone number. Only the login lookup is used.
 type customerAuthRepoFake struct {
 	customers map[string]*entities.Customer
 	err       error
 }
 func (f *customerAuthRepoFake) GetCustomerByPhoneNumber(_ context.Context, phone string) (*entities.Customer, error) {
 	if f.err != nil {
 		return nil, f.err
 	}
 	return f.customers[phone], nil
 }
 func (f *customerAuthRepoFake) GetCustomerByID(context.Context, string) (*entities.Customer, error) {
 	return nil, nil
 }
 func (f *customerAuthRepoFake) CreateCustomer(context.Context, *entities.Customer) error { return nil }
 func (f *customerAuthRepoFake) UpdateCustomer(context.Context, *entities.Customer) error { return nil }
 func (f *customerAuthRepoFake) CheckPhoneNumberExists(context.Context, string) (bool, error) {
 	return false, nil
 }
 func (f *customerAuthRepoFake) SetCustomerPassword(context.Context, string, string) error {
 	return nil
 }
 func (f *customerAuthRepoFake) OrganizationExists(context.Context, uuid.UUID) (bool, error) {
 	return false, nil
 }
 func (f *customerAuthRepoFake) OrganizationIDs(context.Context, int) ([]uuid.UUID, error) {
 	return nil, nil
 }
 // loginAttemptsFake counts attempts per phone number in one window that never ends.
 type loginAttemptsFake struct {
 	counts map[string]int64
 	err    error
 }
 func (f *loginAttemptsFake) Hit(_ context.Context, phone string, window time.Duration) (int64, time.Duration, error) {
 	if f.err != nil {
 		return 0, 0, f.err
 	}
 	f.counts[phone]++
 	return f.counts[phone], window, nil
 }
 func (f *loginAttemptsFake) Reset(_ context.Context, phone string) error {
 	delete(f.counts, phone)
 	return nil
 }
 const (
 	loginTestPassword   = "rahasia123"
 	loginTestRegistered = "6281234561234"
 	loginTestUnfinished = "6281234569999"
 )
 type loginTest struct {
 	repo     *customerAuthRepoFake
 	attempts *loginAttemptsFake
 	router   *gin.Engine
 }
 func newLoginTest(t *testing.T) *loginTest {
 	t.Helper()
 	applogger.Setup("fatal", "json")
 	hash, err := bcrypt.GenerateFromPassword([]byte(loginTestPassword), bcrypt.MinCost)
 	require.NoError(t, err)
 	hashStr := string(hash)
 	registered, unfinished := loginTestRegistered, loginTestUnfinished
 	birth := time.Date(2000, 1, 31, 0, 0, 0, 0, time.UTC)
 	lt := &loginTest{
 		repo: &customerAuthRepoFake{customers: map[string]*entities.Customer{
 			registered: {ID: uuid.New(), Name: "Budi", PhoneNumber: &registered, BirthDate: &birth, PasswordHash: &hashStr},
 			unfinished: {ID: uuid.New(), Name: "Sari", PhoneNumber: &unfinished},
 		}},
 		attempts: &loginAttemptsFake{counts: map[string]int64{}},
 	}
 	h := NewCustomerAuthHandler(
 		service.NewCustomerAuthService(processor.NewCustomerAuthProcessor(lt.repo, lt.attempts, nil, nil, "test", 60)),
 		validator.NewCustomerAuthValidator(),
 	)
 	gin.SetMode(gin.TestMode)
 	lt.router = gin.New()
 	lt.router.POST("/customer-auth/login", h.Login)
 	return lt
 }
 func (lt *loginTest) login(t *testing.T, phone, password string) (int, map[string]any) {
 	t.Helper()
 	body, _ := json.Marshal(map[string]string{"phone_number": phone, "password": password})
 	rec := httptest.NewRecorder()
 	lt.router.ServeHTTP(rec, httptest.NewRequest(http.MethodPost, "/customer-auth/login", bytes.NewReader(body)))
 	var out map[string]any
 	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &out))
 	return rec.Code, out
 }
 func firstLoginError(t *testing.T, out map[string]any) map[string]any {
 	t.Helper()
 	errs, ok := out["errors"].([]any)
 	require.True(t, ok, "errors: %v", out)
 	require.NotEmpty(t, errs)
 	return errs[0].(map[string]any)
 }
 func TestCustomerLoginRefusalsAreValidationErrors(t *testing.T) {
 	lt := newLoginTest(t)
 	for name, tc := range map[string]struct{ phone, password, cause string }{
 		"wrong password":          {loginTestRegistered, "salah", "invalid phone number or password"},
 		"unknown phone":           {"6280000000000", loginTestPassword, "invalid phone number or password"},
 		"registration unfinished": {loginTestUnfinished, loginTestPassword, "customer not properly registered"},
 	} {
 		t.Run(name, func(t *testing.T) {
 			status, out := lt.login(t, tc.phone, tc.password)
 			assert.Equal(t, http.StatusBadRequest, status)
 			e := firstLoginError(t, out)
 			assert.Equal(t, "304", e["code"])
 			assert.Equal(t, "customer_auth_service", e["entity"])
 			assert.Equal(t, tc.cause, e["cause"])
 		})
 	}
 	t.Run("right password", func(t *testing.T) {
 		status, out := lt.login(t, loginTestRegistered, loginTestPassword)
 		require.Equal(t, http.StatusOK, status, "%v", out)
 		inner := out["data"].(map[string]any)["data"].(map[string]any)
 		assert.NotEmpty(t, inner["access_token"])
 	})
 	t.Run("the number written another way finds the same customer", func(t *testing.T) {
 		for _, phone := range []string{"081234561234", "+62 812-3456-1234", "81234561234"} {
 			status, out := lt.login(t, phone, loginTestPassword)
 			require.Equal(t, http.StatusOK, status, "%s: %v", phone, out)
 			user := out["data"].(map[string]any)["data"].(map[string]any)["user"].(map[string]any)
 			assert.Equal(t, loginTestRegistered, user["phone_number"], phone)
 		}
 	})
 	t.Run("a number that is not an Indonesian mobile number", func(t *testing.T) {
 		status, out := lt.login(t, "021-1234567", loginTestPassword)
 		assert.Equal(t, http.StatusBadRequest, status)
 		e := firstLoginError(t, out)
 		assert.Equal(t, "304", e["code"])
 		assert.Equal(t, "invalid phone number format", e["cause"])
 	})
 	t.Run("a failing lookup is still a server error", func(t *testing.T) {
 		lt.repo.err = errors.New("connection refused")
 		defer func() { lt.repo.err = nil }()
 		status, out := lt.login(t, loginTestRegistered, loginTestPassword)
 		assert.Equal(t, http.StatusInternalServerError, status)
 		assert.Equal(t, "900", firstLoginError(t, out)["code"])
 	})
 }
 func TestCustomerLoginLocksAfterTooManyAttempts(t *testing.T) {
 	t.Run("the sixth attempt is refused, even with the right password", func(t *testing.T) {
 		lt := newLoginTest(t)
 		for i := 0; i < 5; i++ {
 			status, _ := lt.login(t, loginTestRegistered, "salah")
 			require.Equal(t, http.StatusBadRequest, status, "attempt %d", i+1)
 		}
 		status, out := lt.login(t, loginTestRegistered, loginTestPassword)
 		assert.Equal(t, http.StatusTooManyRequests, status)
 		e := firstLoginError(t, out)
 		assert.Equal(t, "429", e["code"])
 		assert.Equal(t, "customer_auth_service", e["entity"])
 		data, ok := out["data"].(map[string]any)
 		require.True(t, ok, "data: %v", out)
 		until, err := time.Parse(time.RFC3339, data["locked_until"].(string))
 		require.NoError(t, err)
 		assert.WithinDuration(t, time.Now().Add(15*time.Minute), until, time.Minute)
 		// Another number is not affected.
 		status, _ = lt.login(t, loginTestUnfinished, loginTestPassword)
 		assert.Equal(t, http.StatusBadRequest, status)
 	})
 	t.Run("writing the number another way counts toward the same limit", func(t *testing.T) {
 		lt := newLoginTest(t)
 		for _, phone := range []string{"081234561234", "+6281234561234", "81234561234", "0812-3456-1234", loginTestRegistered} {
 			lt.login(t, phone, "salah")
 		}
 		status, _ := lt.login(t, "081234561234", loginTestPassword)
 		assert.Equal(t, http.StatusTooManyRequests, status)
 	})
 	t.Run("unknown numbers lock the same way", func(t *testing.T) {
 		lt := newLoginTest(t)
 		for i := 0; i < 5; i++ {
 			lt.login(t, "6280000000000", "salah")
 		}
 		status, _ := lt.login(t, "6280000000000", "salah")
 		assert.Equal(t, http.StatusTooManyRequests, status)
 	})
 	t.Run("a successful login starts the count again", func(t *testing.T) {
 		lt := newLoginTest(t)
 		for i := 0; i < 4; i++ {
 			lt.login(t, loginTestRegistered, "salah")
 		}
 		status, _ := lt.login(t, loginTestRegistered, loginTestPassword)
 		require.Equal(t, http.StatusOK, status)
 		for i := 0; i < 5; i++ {
 			status, _ := lt.login(t, loginTestRegistered, "salah")
 			require.Equal(t, http.StatusBadRequest, status, "attempt %d after the login", i+1)
 		}
 	})
 	t.Run("logins go on when the counter is down", func(t *testing.T) {
 		lt := newLoginTest(t)
 		lt.attempts.err = errors.New("redis: connection refused")
 		for i := 0; i < 6; i++ {
 			lt.login(t, loginTestRegistered, "salah")
 		}
 		status, _ := lt.login(t, loginTestRegistered, loginTestPassword)
 		assert.Equal(t, http.StatusOK, status)
 	})
 }
@@ -285,7 +285,7 @@ func (h *EnakGameAdminHandler) EconomyAnalytics(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.EconomyAnalytics(ctx, appcontext.FromGinContext(ctx), q), method)
 }
-// CreateVoucher is POST /marketing/enakgame/vouchers.
+// CreateVoucher is POST /marketing/vouchers.
 func (h *EnakGameAdminHandler) CreateVoucher(c *gin.Context) {
 	const method = "EnakGameAdminHandler::CreateVoucher"
 	body, ok := rawBody(c, method)
@@ -296,7 +296,7 @@ func (h *EnakGameAdminHandler) CreateVoucher(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.CreateVoucher(ctx, appcontext.FromGinContext(ctx), body), method)
 }
-// ListVouchers is GET /marketing/enakgame/vouchers?status=&search=&page=&limit=.
+// ListVouchers is GET /marketing/vouchers?status=&search=&page=&limit=.
 func (h *EnakGameAdminHandler) ListVouchers(c *gin.Context) {
 	const method = "EnakGameAdminHandler::ListVouchers"
 	var q models.VoucherListQuery
@@ -307,7 +307,7 @@ func (h *EnakGameAdminHandler) ListVouchers(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.ListVouchers(ctx, appcontext.FromGinContext(ctx), q), method)
 }
-// GetVoucher is GET /marketing/enakgame/vouchers/:id.
+// GetVoucher is GET /marketing/vouchers/:id.
 func (h *EnakGameAdminHandler) GetVoucher(c *gin.Context) {
 	const method = "EnakGameAdminHandler::GetVoucher"
 	id, ok := pathID(c, "id", method)
@@ -318,7 +318,7 @@ func (h *EnakGameAdminHandler) GetVoucher(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.GetVoucher(ctx, appcontext.FromGinContext(ctx), id), method)
 }
-// UpdateVoucher is PUT /marketing/enakgame/vouchers/:id.
+// UpdateVoucher is PUT /marketing/vouchers/:id.
 func (h *EnakGameAdminHandler) UpdateVoucher(c *gin.Context) {
 	const method = "EnakGameAdminHandler::UpdateVoucher"
 	id, ok := pathID(c, "id", method)
@@ -333,7 +333,7 @@ func (h *EnakGameAdminHandler) UpdateVoucher(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.UpdateVoucher(ctx, appcontext.FromGinContext(ctx), id, body), method)
 }
-// SetVoucherStatus is PUT /marketing/enakgame/vouchers/:id/status.
+// SetVoucherStatus is PUT /marketing/vouchers/:id/status.
 func (h *EnakGameAdminHandler) SetVoucherStatus(c *gin.Context) {
 	const method = "EnakGameAdminHandler::SetVoucherStatus"
 	id, ok := pathID(c, "id", method)
@@ -348,7 +348,7 @@ func (h *EnakGameAdminHandler) SetVoucherStatus(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.SetVoucherStatus(ctx, appcontext.FromGinContext(ctx), id, body), method)
 }
-// ImportVoucherCodes is POST /marketing/enakgame/vouchers/:id/codes, with the CSV as
+// ImportVoucherCodes is POST /marketing/vouchers/:id/codes, with the CSV as
 // a multipart file named "file" or as the request body.
 func (h *EnakGameAdminHandler) ImportVoucherCodes(c *gin.Context) {
 	const method = "EnakGameAdminHandler::ImportVoucherCodes"
@@ -379,7 +379,7 @@ func (h *EnakGameAdminHandler) ImportVoucherCodes(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.ImportVoucherCodes(ctx, appcontext.FromGinContext(ctx), id, data), method)
 }
-// ListVoucherCodes is GET /marketing/enakgame/vouchers/:id/codes?status=&page=&limit=.
+// ListVoucherCodes is GET /marketing/vouchers/:id/codes?status=&page=&limit=.
 func (h *EnakGameAdminHandler) ListVoucherCodes(c *gin.Context) {
 	const method = "EnakGameAdminHandler::ListVoucherCodes"
 	id, ok := pathID(c, "id", method)
@@ -50,16 +50,18 @@ func (h *EnakGameCustomerHandler) StartSession(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.StartSession(c.Request.Context(), customerID, &req, idempotencyKey(c)), method)
 }
-// ListSessions is GET /customer/enakgame/sessions?page=&limit=.
+// ListSessions is GET /customer/enakgame/sessions?game_id=&status=&page=&limit=.
 func (h *EnakGameCustomerHandler) ListSessions(c *gin.Context) {
 	const method = "EnakGameCustomerHandler::ListSessions"
 	customerID, ok := customerIDFromGin(c, method)
 	if !ok {
 		return
 	}
-	page, _ := strconv.Atoi(c.Query("page"))
+	var q models.GameSessionListQuery
-	limit, _ := strconv.Atoi(c.Query("limit"))
+	if !bindQuery(c, &q, method) {
-	util.HandleResponse(c.Writer, c.Request, h.service.ListSessions(c.Request.Context(), customerID, page, limit), method)
+		return
 	}
 	util.HandleResponse(c.Writer, c.Request, h.service.ListSessions(c.Request.Context(), customerID, q), method)
 }
 // GetSession is GET /customer/enakgame/sessions/:id.
@@ -76,6 +78,20 @@ func (h *EnakGameCustomerHandler) GetSession(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.GetSession(c.Request.Context(), customerID, id), method)
 }
 // Leaderboard is GET /customer/enakgame/leaderboard?date=&game_id=&limit=.
 func (h *EnakGameCustomerHandler) Leaderboard(c *gin.Context) {
 	const method = "EnakGameCustomerHandler::Leaderboard"
 	customerID, ok := customerIDFromGin(c, method)
 	if !ok {
 		return
 	}
 	var q models.EnakGameLeaderboardQuery
 	if !bindQuery(c, &q, method) {
 		return
 	}
 	util.HandleResponse(c.Writer, c.Request, h.service.Leaderboard(c.Request.Context(), customerID, q), method)
 }
 // CompleteSession is POST /customer/enakgame/sessions/:id/complete. The body is read
 // leniently on purpose: a reward amount, or anything else the backend does not take
 // from the client, is ignored rather than refused (P1). An empty body is a result
@@ -106,7 +122,7 @@ func (h *EnakGameCustomerHandler) CompleteSession(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.CompleteSession(c.Request.Context(), customerID, id, in), method)
 }
-// ListVouchers is GET /customer/enakgame/vouchers.
+// ListVouchers is GET /customer/vouchers.
 func (h *EnakGameCustomerHandler) ListVouchers(c *gin.Context) {
 	const method = "EnakGameCustomerHandler::ListVouchers"
 	customerID, ok := customerIDFromGin(c, method)
@@ -116,7 +132,7 @@ func (h *EnakGameCustomerHandler) ListVouchers(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.ListVouchers(c.Request.Context(), customerID), method)
 }
-// RedeemVoucher is POST /customer/enakgame/vouchers/:id/redeem. It requires the PIN
+// RedeemVoucher is POST /customer/vouchers/:id/redeem. It requires the PIN
 // and Idempotency-Key; the body holds the PIN, so it is never logged.
 func (h *EnakGameCustomerHandler) RedeemVoucher(c *gin.Context) {
 	const method = "EnakGameCustomerHandler::RedeemVoucher"
@@ -135,7 +151,7 @@ func (h *EnakGameCustomerHandler) RedeemVoucher(c *gin.Context) {
 	util.HandleResponse(c.Writer, c.Request, h.service.RedeemVoucher(c.Request.Context(), customerID, id, &req, idempotencyKey(c), pinRequestInfo(c)), method)
 }
-// ListRedemptions is GET /customer/enakgame/redemptions?page=&limit=.
+// ListRedemptions is GET /customer/vouchers/redemptions?page=&limit=.
 func (h *EnakGameCustomerHandler) ListRedemptions(c *gin.Context) {
 	const method = "EnakGameCustomerHandler::ListRedemptions"
 	customerID, ok := customerIDFromGin(c, method)
@@ -285,7 +285,7 @@ func TestEnakGameVoucherEndpoints_AgainstPostgres(t *testing.T) {
 	router := gin.New()
 	for prefix, role := range map[string]string{"/manager": "manager", "/purchasing": "purchasing"} {
 		role := role
-		g := router.Group(prefix+"/enakgame", func(c *gin.Context) {
+		g := router.Group(prefix, func(c *gin.Context) {
 			ctx := context.WithValue(c.Request.Context(), appcontext.OrganizationIDKey, org.String())
 			ctx = context.WithValue(ctx, appcontext.UserIDKey, admin.String())
 			ctx = context.WithValue(ctx, appcontext.UserRoleKey, role)
@@ -296,10 +296,10 @@ func TestEnakGameVoucherEndpoints_AgainstPostgres(t *testing.T) {
 		g.POST("/vouchers/:id/codes", auth.RequireLoyaltyManager(), adminHandler.ImportVoucherCodes)
 		g.GET("/vouchers/:id/codes", adminHandler.ListVoucherCodes)
 	}
-	c := router.Group("/customer/enakgame", func(c *gin.Context) { c.Set("customer_id", customer.String()) })
+	c := router.Group("/customer", func(c *gin.Context) { c.Set("customer_id", customer.String()) })
 	c.GET("/vouchers", customerHandler.ListVouchers)
 	c.POST("/vouchers/:id/redeem", customerHandler.RedeemVoucher)
-	c.GET("/redemptions", customerHandler.ListRedemptions)
+	c.GET("/vouchers/redemptions", customerHandler.ListRedemptions)
 	send := func(req *http.Request) (int, map[string]any) {
 		t.Helper()
@@ -320,12 +320,12 @@ func TestEnakGameVoucherEndpoints_AgainstPostgres(t *testing.T) {
 	data := func(body map[string]any) map[string]any { return body["data"].(map[string]any) }
 	voucher := `{"name": "Kopi", "voucher_type": "FREE_ITEM", "face_value": 20000, "point_cost": 15000, "stock_mode": "CODE_POOL", "status": "ACTIVE"}`
-	status, _ := call(http.MethodPost, "/purchasing/enakgame/vouchers", voucher)
+	status, _ := call(http.MethodPost, "/purchasing/vouchers", voucher)
 	assert.Equal(t, http.StatusForbidden, status)
-	status, body := call(http.MethodPost, "/manager/enakgame/vouchers", voucher)
+	status, body := call(http.MethodPost, "/manager/vouchers", voucher)
 	require.Equal(t, http.StatusOK, status, body)
 	id := data(body)["id"].(string)
-	status, _ = call(http.MethodPut, "/manager/enakgame/vouchers/"+id, `{"stock_mode": "STATIC", "stock": 5}`)
+	status, _ = call(http.MethodPut, "/manager/vouchers/"+id, `{"stock_mode": "STATIC", "stock": 5}`)
 	assert.Equal(t, http.StatusBadRequest, status, "the stock mode stays")
 	// Codes as a multipart file, then the same as a plain body.
@@ -335,25 +335,25 @@ func TestEnakGameVoucherEndpoints_AgainstPostgres(t *testing.T) {
 	require.NoError(t, err)
 	_, _ = part.Write([]byte("code\nKOPI-1\nKOPI-2\n"))
 	require.NoError(t, w.Close())
-	req := httptest.NewRequest(http.MethodPost, "/manager/enakgame/vouchers/"+id+"/codes", &form)
+	req := httptest.NewRequest(http.MethodPost, "/manager/vouchers/"+id+"/codes", &form)
 	req.Header.Set("Content-Type", w.FormDataContentType())
 	status, body = send(req)
 	require.Equal(t, http.StatusOK, status, body)
 	assert.EqualValues(t, 2, data(body)["imported"])
-	status, body = call(http.MethodPost, "/manager/enakgame/vouchers/"+id+"/codes", "KOPI-2\nKOPI-3\n", "Content-Type", "text/csv")
+	status, body = call(http.MethodPost, "/manager/vouchers/"+id+"/codes", "KOPI-2\nKOPI-3\n", "Content-Type", "text/csv")
 	require.Equal(t, http.StatusOK, status, body)
 	assert.EqualValues(t, 1, data(body)["imported"])
 	assert.Equal(t, []any{"KOPI-2"}, data(body)["duplicates"])
-	status, body = call(http.MethodGet, "/manager/enakgame/vouchers/"+id+"/codes", "")
+	status, body = call(http.MethodGet, "/manager/vouchers/"+id+"/codes", "")
 	require.Equal(t, http.StatusOK, status, body)
 	assert.Equal(t, map[string]any{"AVAILABLE": float64(3)}, data(body)["counts"])
-	status, body = call(http.MethodGet, "/customer/enakgame/vouchers", "")
+	status, body = call(http.MethodGet, "/customer/vouchers", "")
 	require.Equal(t, http.StatusOK, status, body)
 	require.Len(t, body["data"], 1)
 	assert.EqualValues(t, 3, body["data"].([]any)[0].(map[string]any)["available"])
-	redeem := "/customer/enakgame/vouchers/" + id + "/redeem"
+	redeem := "/customer/vouchers/" + id + "/redeem"
 	status, body = call(http.MethodPost, redeem, `{"pin": "482913"}`)
 	assert.Equal(t, http.StatusBadRequest, status, "Idempotency-Key is required")
 	status, body = call(http.MethodPost, redeem, `{}`, "Idempotency-Key", "r1")
@@ -377,10 +377,10 @@ func TestEnakGameVoucherEndpoints_AgainstPostgres(t *testing.T) {
 	assert.EqualValues(t, 5_000, data(body)["point_balance"])
 	status, _ = call(http.MethodPost, redeem, `{"pin": "482913"}`, "Idempotency-Key", "r5")
 	assert.Equal(t, http.StatusBadRequest, status, "out of codes and of EnakPoint")
-	status, _ = call(http.MethodPost, "/customer/enakgame/vouchers/"+uuid.NewString()+"/redeem", `{"pin": "482913"}`, "Idempotency-Key", "r4")
+	status, _ = call(http.MethodPost, "/customer/vouchers/"+uuid.NewString()+"/redeem", `{"pin": "482913"}`, "Idempotency-Key", "r4")
 	assert.Equal(t, http.StatusNotFound, status)
-	status, body = call(http.MethodGet, "/customer/enakgame/redemptions", "")
+	status, body = call(http.MethodGet, "/customer/vouchers/redemptions", "")
 	require.Equal(t, http.StatusOK, status, body)
 	assert.EqualValues(t, 3, data(body)["pagination"].(map[string]any)["total_count"])
 }
@@ -477,7 +477,7 @@ func TestEnakGameEventEndpoints_AgainstPostgres(t *testing.T) {
 	assert.NotContains(t, events[0], "budget_id", "the budget stays internal")
 }
-// EG-1001: the admin steps of docs/enakgame-spin.md make a spin wheel, and a customer
+// EG-1001: the admin steps of docs/integration-backoffice.md §8.4 make a spin wheel, and a customer
 // plays it through /customer/enakgame/sessions, over HTTP down to Postgres.
 func TestEnakGameSpin_AgainstPostgres(t *testing.T) {
 	dsn := os.Getenv("TEST_DATABASE_URL")
@@ -12,7 +12,7 @@ func CORS() gin.HandlerFunc {
 		}
 		c.Header("Access-Control-Allow-Origin", origin)
 		c.Header("Access-Control-Allow-Credentials", "true")
-		c.Header("Access-Control-Allow-Headers", "Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With")
+		c.Header("Access-Control-Allow-Headers", "Content-Type, Content-Length, Accept-Encoding, X-CSRF-Token, Authorization, accept, origin, Cache-Control, X-Requested-With, Idempotency-Key, X-Idempotency-Key")
 		c.Header("Access-Control-Allow-Methods", "POST, OPTIONS, GET, PUT, DELETE")
 		if c.Request.Method == "OPTIONS" {
@@ -189,6 +189,44 @@ type CustomerGameSession struct {
 	RefundReason *string    `json:"refund_reason"`
 }
 // GameSessionListQuery filters a customer's play history. The game client uses
 // game_id with status=STARTED to find the play it was running before a reload.
 type GameSessionListQuery struct {
 	GameID string `form:"game_id"`
 	// STARTED, COMPLETED, REFUNDED or EXPIRED; empty for all.
 	Status string `form:"status"`
 	Page   int    `form:"page"`
 	Limit  int    `form:"limit"`
 }
 // EnakGameLeaderboardQuery picks a week of the leaderboard, and optionally one game.
 type EnakGameLeaderboardQuery struct {
 	// Any day of the week, YYYY-MM-DD in Asia/Jakarta; this week when empty.
 	Date   string `form:"date"`
 	GameID string `form:"game_id"`
 	Limit  int    `form:"limit"`
 }
 // EnakGameLeaderboard ranks the customers of an organization by the EnakCoin they won
 // from games in one week, Monday to Sunday in Asia/Jakarta.
 type EnakGameLeaderboard struct {
 	WeekStart string                     `json:"week_start"`
 	WeekEnd   string                     `json:"week_end"`
 	GameID    *uuid.UUID                 `json:"game_id"`
 	Entries   []EnakGameLeaderboardEntry `json:"entries"`
 	// The customer asking, wherever they rank; null when they won nothing that week.
 	Me *EnakGameLeaderboardEntry `json:"me"`
 }
 // EnakGameLeaderboardEntry is one customer on the leaderboard. Other customers are
 // shown by a masked name only.
 type EnakGameLeaderboardEntry struct {
 	Rank  int    `json:"rank"`
 	Name  string `json:"name"`
 	Coins int64  `json:"coins"`
 	IsMe  bool   `json:"is_me"`
 }
 // GameSessionCompleteInput is what the client reports at the end of a play (§7.2): data
 // only. Anything else it sends, a reward amount above all, is ignored (P1).
 type GameSessionCompleteInput struct {
@@ -2,12 +2,14 @@ package processor
 import (
 	"context"
 	"errors"
 	"fmt"
 	"strings"
 	"time"
 	"apskel-pos-be/internal/contract"
 	"apskel-pos-be/internal/entities"
 	"apskel-pos-be/internal/logger"
 	"apskel-pos-be/internal/models"
 	"apskel-pos-be/internal/repository"
 	"apskel-pos-be/internal/util"
@@ -16,6 +18,32 @@ import (
 	"golang.org/x/crypto/bcrypt"
 )
 var (
 	// ErrCustomerLoginInvalid means no customer has the phone number or the password is
 	// wrong. Which of the two is not told.
 	ErrCustomerLoginInvalid = errors.New("invalid phone number or password")
 	// ErrCustomerNotRegistered means the customer never set a password: registration
 	// stopped before its last step.
 	ErrCustomerNotRegistered = errors.New("customer not properly registered")
 )
 // Login attempts a phone number may make before it has to wait, and the window they
 // are counted in. A successful login starts the count again.
 const (
 	customerLoginMaxAttempts = 5
 	customerLoginWindow      = 15 * time.Minute
 )
 // CustomerLoginLockedError means the phone number made too many login attempts and may
 // try again at Until.
 type CustomerLoginLockedError struct {
 	Until time.Time
 }
 func (e *CustomerLoginLockedError) Error() string {
 	return fmt.Sprintf("too many login attempts, try again after %s", e.Until.Format(time.RFC3339))
 }
 type CustomerAuthProcessor interface {
 	CheckPhoneNumber(ctx context.Context, req *contract.CheckPhoneRequest) (*models.CheckPhoneResponse, error)
 	StartRegistration(ctx context.Context, req *contract.RegisterStartRequest) (*models.RegisterStartResponse, error)
@@ -26,20 +54,22 @@ type CustomerAuthProcessor interface {
 }
 type customerAuthProcessor struct {
-	customerAuthRepo repository.CustomerAuthRepository
+	customerAuthRepo  repository.CustomerAuthRepository
-	otpProcessor     OtpProcessor
+	loginAttemptsRepo repository.CustomerLoginAttemptRepository
-	otpRepo          repository.OtpRepository
+	otpProcessor      OtpProcessor
-	jwtSecret        string
+	otpRepo           repository.OtpRepository
-	tokenTTLMinutes  int
+	jwtSecret         string
 	tokenTTLMinutes   int
 }
-func NewCustomerAuthProcessor(customerAuthRepo repository.CustomerAuthRepository, otpProcessor OtpProcessor, otpRepo repository.OtpRepository, jwtSecret string, tokenTTLMinutes int) CustomerAuthProcessor {
+func NewCustomerAuthProcessor(customerAuthRepo repository.CustomerAuthRepository, loginAttemptsRepo repository.CustomerLoginAttemptRepository, otpProcessor OtpProcessor, otpRepo repository.OtpRepository, jwtSecret string, tokenTTLMinutes int) CustomerAuthProcessor {
 	return &customerAuthProcessor{
-		customerAuthRepo: customerAuthRepo,
+		customerAuthRepo:  customerAuthRepo,
-		otpProcessor:     otpProcessor,
+		loginAttemptsRepo: loginAttemptsRepo,
-		otpRepo:          otpRepo,
+		otpProcessor:      otpProcessor,
-		jwtSecret:        jwtSecret,
+		otpRepo:           otpRepo,
-		tokenTTLMinutes:  tokenTTLMinutes,
+		jwtSecret:         jwtSecret,
 		tokenTTLMinutes:   tokenTTLMinutes,
 	}
 }
@@ -344,6 +374,21 @@ func (p *customerAuthProcessor) SetPassword(ctx context.Context, req *contract.R
 }
 func (p *customerAuthProcessor) Login(ctx context.Context, req *contract.CustomerLoginRequest) (*models.CustomerLoginResponse, error) {
 	// Counted before the password is checked, so attempts sent at once all count, and
 	// for numbers without a customer too, so a refusal never tells which numbers have
 	// one.
 	attempts, left, err := p.loginAttemptsRepo.Hit(ctx, req.PhoneNumber, customerLoginWindow)
 	switch {
 	case err != nil:
 		// Without the counter, logins go on unlimited rather than stop for everyone.
 		logger.FromContext(ctx).WithError(err).Error("CustomerAuthProcessor::Login -> failed to count the attempt")
 	case attempts > customerLoginMaxAttempts:
 		if left <= 0 {
 			left = customerLoginWindow
 		}
 		return nil, &CustomerLoginLockedError{Until: time.Now().Add(left).UTC().Truncate(time.Second)}
 	}
 	// Get customer by phone number
 	customer, err := p.customerAuthRepo.GetCustomerByPhoneNumber(ctx, req.PhoneNumber)
 	if err != nil {
@@ -351,16 +396,19 @@ func (p *customerAuthProcessor) Login(ctx context.Context, req *contract.Custome
 	}
 	if customer == nil {
-		return nil, fmt.Errorf("customer not found")
+		return nil, ErrCustomerLoginInvalid
 	}
 	if customer.PasswordHash == nil {
-		return nil, fmt.Errorf("customer not properly registered")
+		return nil, ErrCustomerNotRegistered
 	}
 	// Verify password
 	if err := bcrypt.CompareHashAndPassword([]byte(*customer.PasswordHash), []byte(req.Password)); err != nil {
-		return nil, fmt.Errorf("invalid password")
+		return nil, ErrCustomerLoginInvalid
 	}
 	if err := p.loginAttemptsRepo.Reset(ctx, req.PhoneNumber); err != nil {
 		logger.FromContext(ctx).WithError(err).Error("CustomerAuthProcessor::Login -> failed to reset the attempts")
 	}
 	// Generate JWT tokens using customer JWT util
@@ -675,12 +675,34 @@ func TestGameSession_CustomerReads(t *testing.T) {
 	_, err = e.sessions.GetSession(ctx, e.bob, started.SessionID)
 	assert.ErrorIs(t, err, repository.ErrGameSessionNotFound, "another customer's session")
-	page, err := e.sessions.ListSessions(ctx, e.alice, 1, 10)
+	page, err := e.sessions.ListSessions(ctx, e.alice, models.GameSessionListQuery{Page: 1, Limit: 10})
 	require.NoError(t, err)
 	assert.EqualValues(t, 1, page.Pagination.Total)
-	page, err = e.sessions.ListSessions(ctx, e.bob, 1, 10)
+	page, err = e.sessions.ListSessions(ctx, e.bob, models.GameSessionListQuery{Page: 1, Limit: 10})
 	require.NoError(t, err)
 	assert.Empty(t, page.Data)
 	// After a reload, the game finds the play it was running by game and status.
 	other := e.playableGame(e.orgA, "other", 1)
 	otherStarted, err := e.sessions.Start(ctx, e.alice, other.ID, "k2")
 	require.NoError(t, err)
 	_, err = e.sessions.Complete(ctx, e.alice, otherStarted.SessionID, models.GameSessionCompleteInput{})
 	require.NoError(t, err)
 	running, err := e.sessions.ListSessions(ctx, e.alice, models.GameSessionListQuery{GameID: game.ID.String(), Status: "started"})
 	require.NoError(t, err)
 	require.Len(t, running.Data, 1)
 	assert.Equal(t, started.SessionID, running.Data[0].ID)
 	running, err = e.sessions.ListSessions(ctx, e.alice, models.GameSessionListQuery{GameID: other.ID.String(), Status: constants.GameSessionStatusStarted})
 	require.NoError(t, err)
 	assert.Empty(t, running.Data, "the other game's play is completed")
 	all, err := e.sessions.ListSessions(ctx, e.alice, models.GameSessionListQuery{})
 	require.NoError(t, err)
 	assert.EqualValues(t, 2, all.Pagination.Total)
 	_, err = e.sessions.ListSessions(ctx, e.alice, models.GameSessionListQuery{Status: "PLAYING"})
 	assert.ErrorIs(t, err, ErrGameSessionRejected)
 	_, err = e.sessions.ListSessions(ctx, e.alice, models.GameSessionListQuery{GameID: "runner"})
 	assert.ErrorIs(t, err, ErrGameSessionRejected)
 }
 // gameWith makes an ACTIVE game of org A with the given result rules and an active
@@ -0,0 +1,98 @@
 package processor
 import (
 	"context"
 	"strings"
 	"time"
 	"github.com/google/uuid"
 	"apskel-pos-be/internal/models"
 	"apskel-pos-be/internal/repository"
 )
 const (
 	// leaderboardLimit is how many ranks a leaderboard shows unless asked, and
 	// leaderboardMaxLimit the most it shows.
 	leaderboardLimit    = 10
 	leaderboardMaxLimit = 100
 )
 // Leaderboard ranks the customers of the customer's organization by the EnakCoin they
 // won from games in one week, Monday to Sunday in Asia/Jakarta: this week, or the one
 // holding q.Date. A session counts in the week it started. Refunded, expired and
 // flagged sessions count for nothing.
 func (p *GameSessionProcessor) Leaderboard(ctx context.Context, customerID uuid.UUID, q models.EnakGameLeaderboardQuery) (*models.EnakGameLeaderboard, error) {
 	day := walletDay(p.now())
 	if s := strings.TrimSpace(q.Date); s != "" {
 		d, err := time.ParseInLocation("2006-01-02", s, walletDisplayLocation)
 		if err != nil {
 			return nil, gameSessionRejected("date must be YYYY-MM-DD")
 		}
 		day = d
 	}
 	weekStart := leaderboardWeekStart(day)
 	filter := repository.LeaderboardFilter{
 		CustomerID: customerID, From: weekStart, To: weekStart.AddDate(0, 0, 7), Limit: q.Limit,
 	}
 	if filter.Limit < 1 || filter.Limit > leaderboardMaxLimit {
 		filter.Limit = leaderboardLimit
 	}
 	if s := strings.TrimSpace(q.GameID); s != "" {
 		id, err := uuid.Parse(s)
 		if err != nil {
 			return nil, gameSessionRejected("game_id must be a UUID")
 		}
 		filter.GameID = &id
 	}
 	customer, err := p.customers.GetCustomer(ctx, customerID)
 	if err != nil {
 		return nil, err
 	}
 	filter.OrganizationID = customer.OrganizationID
 	rows, err := p.sessions.Leaderboard(ctx, filter)
 	if err != nil {
 		return nil, err
 	}
 	board := &models.EnakGameLeaderboard{
 		WeekStart: weekStart.Format("2006-01-02"), WeekEnd: weekStart.AddDate(0, 0, 6).Format("2006-01-02"),
 		GameID: filter.GameID, Entries: []models.EnakGameLeaderboardEntry{},
 	}
 	for _, row := range rows {
 		entry := models.EnakGameLeaderboardEntry{
 			Rank: row.Rank, Name: maskCustomerName(row.Name), Coins: row.Coins, IsMe: row.CustomerID == customerID,
 		}
 		if row.Rank <= filter.Limit {
 			board.Entries = append(board.Entries, entry)
 		}
 		if entry.IsMe {
 			me := entry
 			board.Me = &me
 		}
 	}
 	return board, nil
 }
 // leaderboardWeekStart is the Monday, at midnight in Asia/Jakarta, of the week of day.
 func leaderboardWeekStart(day time.Time) time.Time {
 	day = walletDay(day)
 	return day.AddDate(0, 0, -((int(day.Weekday()) + 6) % 7))
 }
 // maskCustomerName keeps the first word of a name and the first letter of every other
 // word: "Budi Santoso" is shown as "Budi S******". A word with a digit, as when a phone
 // number was used for the name, keeps only its first character, the first word too.
 func maskCustomerName(name string) string {
 	words := strings.Fields(name)
 	if len(words) == 0 {
 		return "Pemain"
 	}
 	for i, w := range words {
 		if i == 0 && !strings.ContainsAny(w, "0123456789") {
 			continue
 		}
 		r := []rune(w)
 		words[i] = string(r[0]) + strings.Repeat("*", len(r)-1)
 	}
 	return strings.Join(words, " ")
 }
@@ -0,0 +1,95 @@
 package processor
 import (
 	"fmt"
 	"testing"
 	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"apskel-pos-be/internal/models"
 )
 // The weekly leaderboard against Postgres. Needs TEST_DATABASE_URL; see
 // internal/repository/wallet_repository_test.go.
 func TestGameSession_Leaderboard(t *testing.T) {
 	e := newEnakGameEnv(t)
 	ctx := e.ctx()
 	dave := uuid.New()
 	require.NoError(t, e.db.Exec(`INSERT INTO customers (id, organization_id, name) VALUES (?, ?, 'Dave Lee')`, dave, e.orgA).Error)
 	runner := e.playableGame(e.orgA, "runner", 1)
 	other := e.playableGame(e.orgA, "other", 1)
 	theirs := e.playableGame(e.orgB, "theirs", 1)
 	for _, c := range []uuid.UUID{e.alice, e.bob, e.carol, dave} {
 		e.coins(c, 100, nil)
 	}
 	n := 0
 	// play completes a session of game for customer and returns its id; every
 	// playableGame pays 10.
 	play := func(customer, game uuid.UUID) uuid.UUID {
 		t.Helper()
 		n++
 		s, err := e.sessions.Start(ctx, customer, game, fmt.Sprintf("k%d", n))
 		require.NoError(t, err)
 		_, err = e.sessions.Complete(ctx, customer, s.SessionID, models.GameSessionCompleteInput{})
 		require.NoError(t, err)
 		return s.SessionID
 	}
 	play(e.alice, runner.ID)
 	play(e.alice, other.ID)
 	bobs := play(e.bob, runner.ID)
 	play(dave, runner.ID)
 	play(e.carol, theirs.ID)
 	// Bob reached 10 before Dave did.
 	require.NoError(t, e.db.Exec(`UPDATE game_sessions SET ended_at = ended_at - INTERVAL '1 minute' WHERE id = ?`, bobs).Error)
 	flagged := play(e.bob, runner.ID)
 	require.NoError(t, e.db.Exec(`UPDATE game_sessions SET flagged = TRUE WHERE id = ?`, flagged).Error)
 	lastWeek := play(dave, runner.ID)
 	require.NoError(t, e.db.Exec(`UPDATE game_sessions SET started_at = started_at - INTERVAL '7 days' WHERE id = ?`, lastWeek).Error)
 	_, err := e.sessions.Start(ctx, e.alice, runner.ID, "open")
 	require.NoError(t, err, "a STARTED session counts for nothing")
 	board, err := e.sessions.Leaderboard(ctx, e.bob, models.EnakGameLeaderboardQuery{})
 	require.NoError(t, err)
 	week := leaderboardWeekStart(e.now)
 	assert.Equal(t, week.Format("2006-01-02"), board.WeekStart)
 	assert.Equal(t, week.AddDate(0, 0, 6).Format("2006-01-02"), board.WeekEnd)
 	assert.Equal(t, []models.EnakGameLeaderboardEntry{
 		{Rank: 1, Name: "Alice", Coins: 20},
 		{Rank: 2, Name: "Bob", Coins: 10, IsMe: true},
 		{Rank: 3, Name: "Dave L**", Coins: 10},
 	}, board.Entries, "the flagged play, last week's play and another organization's do not count")
 	require.NotNil(t, board.Me)
 	assert.Equal(t, 2, board.Me.Rank)
 	board, err = e.sessions.Leaderboard(ctx, dave, models.EnakGameLeaderboardQuery{Limit: 1})
 	require.NoError(t, err)
 	require.Len(t, board.Entries, 1)
 	assert.Equal(t, "Alice", board.Entries[0].Name)
 	require.NotNil(t, board.Me, "the customer asking is returned below the limit")
 	assert.Equal(t, models.EnakGameLeaderboardEntry{Rank: 3, Name: "Dave L**", Coins: 10, IsMe: true}, *board.Me)
 	board, err = e.sessions.Leaderboard(ctx, e.alice, models.EnakGameLeaderboardQuery{GameID: other.ID.String()})
 	require.NoError(t, err)
 	assert.Equal(t, []models.EnakGameLeaderboardEntry{{Rank: 1, Name: "Alice", Coins: 10, IsMe: true}}, board.Entries)
 	assert.Equal(t, &other.ID, board.GameID)
 	board, err = e.sessions.Leaderboard(ctx, dave, models.EnakGameLeaderboardQuery{Date: week.AddDate(0, 0, -3).Format("2006-01-02")})
 	require.NoError(t, err)
 	assert.Equal(t, []models.EnakGameLeaderboardEntry{{Rank: 1, Name: "Dave L**", Coins: 10, IsMe: true}}, board.Entries, "last week")
 	board, err = e.sessions.Leaderboard(ctx, e.carol, models.EnakGameLeaderboardQuery{})
 	require.NoError(t, err)
 	assert.Equal(t, []models.EnakGameLeaderboardEntry{{Rank: 1, Name: "Carol", Coins: 10, IsMe: true}}, board.Entries, "only the customer's organization")
 	board, err = e.sessions.Leaderboard(ctx, e.bob, models.EnakGameLeaderboardQuery{GameID: uuid.NewString(), Date: "2020-01-01"})
 	require.NoError(t, err)
 	assert.Empty(t, board.Entries)
 	assert.Nil(t, board.Me)
 	_, err = e.sessions.Leaderboard(ctx, e.bob, models.EnakGameLeaderboardQuery{Date: "12-10-2026"})
 	assert.ErrorIs(t, err, ErrGameSessionRejected)
 	_, err = e.sessions.Leaderboard(ctx, e.bob, models.EnakGameLeaderboardQuery{GameID: "runner"})
 	assert.ErrorIs(t, err, ErrGameSessionRejected)
 }
@@ -0,0 +1,38 @@
 package processor
 import (
 	"testing"
 	"time"
 	"github.com/stretchr/testify/assert"
 )
 func TestMaskCustomerName(t *testing.T) {
 	for name, want := range map[string]string{
 		"Budi Santoso":        "Budi S******",
 		"budi":                "budi",
 		"  Siti   Nur Aisyah": "Siti N** A*****",
 		"Ádám Ő":              "Ádám Ő",
 		"081234567890":        "0***********",
 		"Budi2 Santoso":       "B**** S******",
 		"":                    "Pemain",
 		"   ":                 "Pemain",
 	} {
 		assert.Equal(t, want, maskCustomerName(name), "%q", name)
 	}
 }
 func TestLeaderboardWeekStart(t *testing.T) {
 	monday := time.Date(2026, 10, 12, 0, 0, 0, 0, walletDisplayLocation)
 	for _, day := range []time.Time{
 		monday,
 		time.Date(2026, 10, 14, 12, 0, 0, 0, walletDisplayLocation),
 		time.Date(2026, 10, 18, 23, 59, 59, 0, walletDisplayLocation),
 		// Sunday 17:00 UTC is already Monday 00:00 in Jakarta.
 		time.Date(2026, 10, 11, 17, 0, 0, 0, time.UTC),
 	} {
 		assert.True(t, monday.Equal(leaderboardWeekStart(day)), "%s", day)
 	}
 	// Sunday 16:59 UTC is still Sunday in Jakarta, the week before.
 	assert.True(t, monday.AddDate(0, 0, -7).Equal(leaderboardWeekStart(time.Date(2026, 10, 11, 16, 59, 0, 0, time.UTC))))
 }
@@ -419,10 +419,26 @@ func (p *GameSessionProcessor) ListGames(ctx context.Context, customerID uuid.UU
 	return out, nil
 }
-// ListSessions returns a page of the customer's sessions, newest first.
+// ListSessions returns a page of the customer's sessions, newest first, of one game
-func (p *GameSessionProcessor) ListSessions(ctx context.Context, customerID uuid.UUID, page, limit int) (*models.PaginatedResponse[models.CustomerGameSession], error) {
+// or status when asked.
-	page, limit = enakGamePage(page, limit)
+func (p *GameSessionProcessor) ListSessions(ctx context.Context, customerID uuid.UUID, q models.GameSessionListQuery) (*models.PaginatedResponse[models.CustomerGameSession], error) {
-	sessions, total, err := p.sessions.ListCustomerSessions(ctx, customerID, (page-1)*limit, limit)
+	page, limit := enakGamePage(q.Page, q.Limit)
 	filter := repository.CustomerSessionFilter{CustomerID: customerID, Offset: (page - 1) * limit, Limit: limit}
 	if s := strings.TrimSpace(q.GameID); s != "" {
 		id, err := uuid.Parse(s)
 		if err != nil {
 			return nil, gameSessionRejected("game_id must be a UUID")
 		}
 		filter.GameID = &id
 	}
 	switch status := strings.ToUpper(strings.TrimSpace(q.Status)); status {
 	case "", constants.GameSessionStatusStarted, constants.GameSessionStatusCompleted,
 		constants.GameSessionStatusRefunded, constants.GameSessionStatusExpired:
 		filter.Status = status
 	default:
 		return nil, gameSessionRejected("status must be STARTED, COMPLETED, REFUNDED or EXPIRED")
 	}
 	sessions, total, err := p.sessions.ListCustomerSessions(ctx, filter)
 	if err != nil {
 		return nil, err
 	}
@@ -152,7 +152,7 @@ func (f *movePinFake) VerifyPin(_ context.Context, _ uuid.UUID, pin string, acti
 func TestWalletExchange_DefaultRateIsOneToOne(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	c := e.member("Budi Santoso", "081234561234")
+	c := e.member("Budi Santoso", "6281234561234")
 	e.earnCoins(t, c, 50, nil)
 	res, err := e.exchanges().Exchange(e.ctx, c, 50, "482913", "key-1", models.CustomerPinRequestInfo{})
@@ -187,7 +187,7 @@ func TestWalletExchange_DefaultRateIsOneToOne(t *testing.T) {
 func TestWalletExchange_TenCoinsForThreePoints(t *testing.T) {
 	e := newWalletMoveEnv(t)
 	e.settings.Exchange = models.LoyaltyExchangeSettings{CoinAmount: 10, PointAmount: 3}
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 35, nil)
 	preview, err := e.exchanges().Preview(e.ctx, c, 30)
@@ -206,7 +206,7 @@ func TestWalletExchange_TenCoinsForThreePoints(t *testing.T) {
 func TestWalletExchange_RefusesAmountsThatAreNotAMultiple(t *testing.T) {
 	e := newWalletMoveEnv(t)
 	e.settings.Exchange = models.LoyaltyExchangeSettings{CoinAmount: 10, PointAmount: 3}
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 50, nil)
 	preview, err := e.exchanges().Preview(e.ctx, c, 25)
@@ -227,7 +227,7 @@ func TestWalletExchange_RefusesAmountsThatAreNotAMultiple(t *testing.T) {
 func TestWalletExchange_NeverOutlivesTheCoinLot(t *testing.T) {
 	e := newWalletMoveEnv(t)
 	e.settings.Exchange = models.LoyaltyExchangeSettings{CoinAmount: 10, PointAmount: 3}
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	soon, later := e.at(24*time.Hour), e.at(48*time.Hour)
 	first := e.earnCoins(t, c, 15, soon)
 	second := e.earnCoins(t, c, 15, later)
@@ -268,7 +268,7 @@ func TestWalletExchange_NeverOutlivesTheCoinLot(t *testing.T) {
 func TestWalletExchange_LotTooSmallForAWholePointGivesNone(t *testing.T) {
 	e := newWalletMoveEnv(t)
 	e.settings.Exchange = models.LoyaltyExchangeSettings{CoinAmount: 10, PointAmount: 1}
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 5, e.at(time.Hour))
 	e.earnCoins(t, c, 5, nil)
@@ -281,7 +281,7 @@ func TestWalletExchange_LotTooSmallForAWholePointGivesNone(t *testing.T) {
 func TestWalletExchange_NotEnoughCoins(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 5, nil)
 	preview, err := e.exchanges().Preview(e.ctx, c, 6)
@@ -295,7 +295,7 @@ func TestWalletExchange_NotEnoughCoins(t *testing.T) {
 func TestWalletExchange_WrongPinMovesNothing(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 5, nil)
 	_, err := e.exchanges().Exchange(e.ctx, c, 5, "000000", "key-1", models.CustomerPinRequestInfo{})
@@ -307,7 +307,7 @@ func TestWalletExchange_WrongPinMovesNothing(t *testing.T) {
 func TestWalletExchange_RetryReturnsTheFirstExchangeAtItsRate(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 100, nil)
 	first, err := e.exchanges().Exchange(e.ctx, c, 40, "482913", "key-1", models.CustomerPinRequestInfo{})
@@ -330,7 +330,7 @@ func TestWalletExchange_RetryReturnsTheFirstExchangeAtItsRate(t *testing.T) {
 func TestWalletExchange_RequiresAnIdempotencyKey(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	e.earnCoins(t, c, 5, nil)
 	_, err := e.exchanges().Exchange(e.ctx, c, 5, "482913", " ", models.CustomerPinRequestInfo{})
@@ -344,7 +344,7 @@ func TestWalletExchange_CappedByThePointExpiry(t *testing.T) {
 	e := newWalletMoveEnv(t)
 	e.now = wib(2026, 6, 1, 10, 0)
 	e.settings.PointExpiry = rolling(30, "DAY", false)
-	c := e.member("Budi", "081234561234")
+	c := e.member("Budi", "6281234561234")
 	soon, later := e.at(24*time.Hour), e.at(90*24*time.Hour)
 	e.earnCoins(t, c, 10, soon)
 	e.earnCoins(t, c, 10, later)
@@ -54,7 +54,7 @@ func (e *walletMoveEnv) expiry(notifier customerNotifier) (*WalletExpiryProcesso
 func TestWalletExpiry_ExpiresWhatIsDueAndTellsTheCustomer(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	ord := earn(a, 150, e.at(-time.Hour))
 	ord.Description = "Belanja #ORD-0098"
 	due := e.credit(t, ord)
@@ -102,7 +102,7 @@ func TestWalletExpiry_ExpiresWhatIsDueAndTellsTheCustomer(t *testing.T) {
 func TestWalletExpiry_RunningAgainExpiresNothingMore(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	e.credit(t, earn(a, 150, e.at(-time.Hour)))
 	notifier := &notifierFake{}
@@ -128,7 +128,7 @@ func TestWalletExpiry_RunningAgainExpiresNothingMore(t *testing.T) {
 func TestWalletExpiry_OneFailingLotDoesNotStopTheOthers(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	e.credit(t, earn(a, 150, e.at(-time.Hour)))
 	p, repo := e.expiry(nil)
 	// A lot listed that ExpireLot cannot find.
@@ -142,7 +142,7 @@ func TestWalletExpiry_OneFailingLotDoesNotStopTheOthers(t *testing.T) {
 func TestWalletExpiry_NothingDue(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	e.credit(t, earn(a, 150, e.at(time.Hour)))
 	notifier := &notifierFake{}
 	p, _ := e.expiry(notifier)
@@ -206,7 +206,7 @@ func TestWalletExpiry_RemindsOncePerDayBeforeExpiry(t *testing.T) {
 	e.now = wib(2026, 10, 25, 9, 0)
 	e.settings.PointExpiry.ReminderDays = 7
 	e.settings.CoinExpiry.ReminderDays = 0 // no reminders for EnakCoin
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	oct31 := wib(2026, 10, 31, 23, 59)
 	nov30 := wib(2026, 11, 30, 23, 59)
 	e.credit(t, earn(a, 100, &oct31))
@@ -2,6 +2,7 @@ package processor
 import (
 	"context"
 	"encoding/binary"
 	"fmt"
 	"os"
 	"sync"
@@ -42,7 +43,7 @@ func walletMoveDB(t *testing.T) (db *gorm.DB, org, a, b uuid.UUID) {
 	require.NoError(t, err)
 	org, a, b = uuid.New(), uuid.New(), uuid.New()
-	phoneA, phoneB := "08"+a.String()[:10], "08"+b.String()[:10]
+	phoneA, phoneB := walletTestPhone(a), walletTestPhone(b)
 	require.NoError(t, db.Exec(`INSERT INTO organizations (id, name, plan_type) VALUES (?, 'wallet move test', 'basic')`, org).Error)
 	require.NoError(t, db.Exec(`INSERT INTO customers (id, organization_id, name, phone_number) VALUES (?, ?, 'Anita', ?), (?, ?, 'Budi Santoso', ?)`,
 		a, org, phoneA, b, org, phoneB).Error)
@@ -117,7 +118,7 @@ func TestWalletTransfer_BothWaysAtOnceAgainstPostgres(t *testing.T) {
 		_, err := wallet.Credit(ctx, earn(b, 100, nil))
 		return err
 	}))
-	phone := func(id uuid.UUID) string { return "08" + id.String()[:10] }
+	phone := walletTestPhone
 	const rounds = 10
 	errs := make(chan error, 2*rounds)
@@ -235,3 +236,8 @@ func TestWalletExpiry_TwoInstancesAgainstPostgres(t *testing.T) {
 	assert.Equal(t, int64(10), expires)
 	assert.Zero(t, left)
 }
 // walletTestPhone is a phone number in its stored form, 628…, unique to the customer.
 func walletTestPhone(id uuid.UUID) string {
 	return fmt.Sprintf("628%09d", binary.BigEndian.Uint64(id[:8])%1_000_000_000)
 }
@@ -85,8 +85,8 @@ func findRow(t *testing.T, e *walletMoveEnv, customerID uuid.UUID, txType string
 // redeems 30. Tracing B's redemption leads to A's order #ORD-1.
 func TestWalletTrace_RedemptionLeadsBackToTheSendersOrder(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	b := e.member("Budi Santoso", "081234561234")
+	b := e.member("Budi Santoso", "6281234561234")
 	ord1 := earn(a, 100, e.at(30*24*time.Hour))
 	ord1.Description = "Belanja #ORD-1"
 	ord2 := earn(a, 50, e.at(60*24*time.Hour))
@@ -121,8 +121,8 @@ func TestWalletTrace_RedemptionLeadsBackToTheSendersOrder(t *testing.T) {
 func TestWalletTrace_DebitAndCreditOfATransfer(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	b := e.member("Budi", "081234561234")
+	b := e.member("Budi", "6281234561234")
 	e.credit(t, earn(a, 100, e.at(time.Hour)))
 	e.credit(t, earn(a, 50, nil))
 	_, err := e.transfers(nil).Transfer(e.ctx, a, sendPoints(120, "081234561234"), "482913", "key-1", models.CustomerPinRequestInfo{})
@@ -153,7 +153,7 @@ func TestWalletTrace_DebitAndCreditOfATransfer(t *testing.T) {
 func TestWalletTrace_OtherOrganizationsRowsAreNotFound(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	res := e.credit(t, earn(a, 10, nil))
 	_, err := NewWalletTraceProcessor(walletTraceRepoFake{e}).Trace(e.ctx, uuid.New(), res.Transaction.ID)
@@ -15,6 +15,7 @@ import (
 	"apskel-pos-be/internal/logger"
 	"apskel-pos-be/internal/models"
 	"apskel-pos-be/internal/repository"
 	"apskel-pos-be/internal/util"
 )
 // ErrWalletRecipientNotFound means no customer of the sender's organization has the
@@ -213,10 +214,13 @@ func (p *WalletTransferProcessor) Transfer(ctx context.Context, senderID uuid.UU
 // them: an active customer of the same organization, not the walk-in customer, and
 // not the sender.
 func (p *WalletTransferProcessor) recipient(ctx context.Context, sender *repository.WalletMoveCustomer, phoneNumber string) (*repository.WalletMoveCustomer, error) {
-	phoneNumber = strings.TrimSpace(phoneNumber)
+	if strings.TrimSpace(phoneNumber) == "" {
 	if phoneNumber == "" {
 		return nil, fmt.Errorf("%w: the recipient's phone number is required", ErrWalletMoveRejected)
 	}
 	phoneNumber, err := util.NormalizePhoneNumber(phoneNumber)
 	if err != nil {
 		return nil, fmt.Errorf("%w: the recipient's phone number is not valid", ErrWalletMoveRejected)
 	}
 	recipient, err := p.customers.FindCustomerByPhone(ctx, phoneNumber)
 	if errors.Is(err, repository.ErrWalletNotFound) {
 		return nil, ErrWalletRecipientNotFound
@@ -282,10 +286,14 @@ func maskName(name string) string {
 	return strings.Join(words, " ")
 }
-// maskPhoneNumber keeps the first two and the last four digits:
+// maskPhoneNumber keeps the first two and the last four digits of the number as
-// "081234561234" → "08**-****-1234".
+// customers write it, with 0 for 62: "6281234561234" → "08**-****-1234".
 func maskPhoneNumber(phone string) string {
-	runes := []rune(strings.TrimSpace(phone))
+	phone = strings.TrimSpace(phone)
 	if strings.HasPrefix(phone, "62") {
 		phone = "0" + phone[2:]
 	}
 	runes := []rune(phone)
 	if len(runes) < 8 {
 		return "****"
 	}
@@ -37,8 +37,8 @@ func sendPoints(amount int64, phone string) models.WalletTransfer {
 func TestWalletTransfer_MovesBalanceWithItsExpiry(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	b := e.member("Budi Santoso", "081234561234")
+	b := e.member("Budi Santoso", "6281234561234")
 	dec, jan := e.at(30*24*time.Hour), e.at(60*24*time.Hour)
 	first := e.credit(t, earn(a, 100, dec))
 	second := e.credit(t, earn(a, 50, jan))
@@ -97,8 +97,8 @@ func TestWalletTransfer_MovesBalanceWithItsExpiry(t *testing.T) {
 func TestWalletTransfer_Coins(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	b := e.member("Budi", "081234561234")
+	b := e.member("Budi", "6281234561234")
 	e.earnCoins(t, a, 10, nil)
 	_, err := e.transfers(nil).Transfer(e.ctx, a, models.WalletTransfer{Currency: "coin", Amount: 4, RecipientPhone: "081234561234"}, "482913", "key-1", models.CustomerPinRequestInfo{})
@@ -109,14 +109,14 @@ func TestWalletTransfer_Coins(t *testing.T) {
 func TestWalletTransfer_RefusesRecipientsItMayNotSendTo(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
 	e.credit(t, earn(a, 100, nil))
-	walkIn := e.member("Walk-in", "081100000000")
+	walkIn := e.member("Walk-in", "6281100000000")
 	e.customers.byID[walkIn].IsDefault = true
-	inactive := e.member("Old", "081100000001")
+	inactive := e.member("Old", "6281100000001")
 	e.customers.byID[inactive].IsActive = false
-	elsewhere := e.member("Other Org", "081100000002")
+	elsewhere := e.member("Other Org", "6281100000002")
 	e.customers.byID[elsewhere].OrganizationID = uuid.New()
 	for phone, want := range map[string]error{
@@ -126,6 +126,7 @@ func TestWalletTransfer_RefusesRecipientsItMayNotSendTo(t *testing.T) {
 		"081100000002": ErrWalletRecipientNotFound, // another organization looks like nobody
 		"081999999999": ErrWalletRecipientNotFound,
 		"":             ErrWalletMoveRejected,
 		"021-1234567":  ErrWalletMoveRejected, // not a mobile number
 	} {
 		_, err := e.transfers(nil).Recipient(e.ctx, a, phone)
 		assert.ErrorIs(t, err, want, phone)
@@ -138,18 +139,20 @@ func TestWalletTransfer_RefusesRecipientsItMayNotSendTo(t *testing.T) {
 func TestWalletTransfer_RecipientIsMasked(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	e.member("Budi Santoso", "081234561234")
+	e.member("Budi Santoso", "6281234561234")
-	got, err := e.transfers(nil).Recipient(e.ctx, a, " 081234561234 ")
+	for _, phone := range []string{" 081234561234 ", "6281234561234", "+62 812-3456-1234"} {
-	require.NoError(t, err)
+		got, err := e.transfers(nil).Recipient(e.ctx, a, phone)
-	assert.Equal(t, &models.WalletTransferRecipient{Name: "Bu*** Sa***", PhoneNumber: "08**-****-1234"}, got)
+		require.NoError(t, err, phone)
 		assert.Equal(t, &models.WalletTransferRecipient{Name: "Bu*** Sa***", PhoneNumber: "08**-****-1234"}, got, phone)
 	}
 }
 func TestWalletTransfer_OrganizationLimits(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	e.member("Budi", "081234561234")
+	e.member("Budi", "6281234561234")
 	e.credit(t, earn(a, 1000, nil))
 	e.settings.Transfer = models.LoyaltyTransferSettings{Enabled: true, MinAmount: 10, MaxPerTransaction: ptr(int64(300)), DailyLimit: ptr(int64(500))}
 	send := func(amount int64, key string) error {
@@ -177,8 +180,8 @@ func TestWalletTransfer_OrganizationLimits(t *testing.T) {
 func TestWalletTransfer_HeldAfterPinReset(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	e.member("Budi", "081234561234")
+	e.member("Budi", "6281234561234")
 	e.credit(t, earn(a, 100, nil))
 	until := e.now.Add(time.Hour)
 	e.pins.err = &PinError{Code: PinErrTransferBlocked, Until: &until}
@@ -192,8 +195,8 @@ func TestWalletTransfer_HeldAfterPinReset(t *testing.T) {
 func TestWalletTransfer_NotEnoughBalance(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	b := e.member("Budi", "081234561234")
+	b := e.member("Budi", "6281234561234")
 	e.credit(t, earn(a, 100, nil))
 	// An expired lot cannot be sent even before the expiry job takes it.
 	e.credit(t, earn(a, 50, e.at(-time.Hour)))
@@ -205,9 +208,9 @@ func TestWalletTransfer_NotEnoughBalance(t *testing.T) {
 func TestWalletTransfer_RetryMovesNothingAndTellsNobodyAgain(t *testing.T) {
 	e := newWalletMoveEnv(t)
-	a := e.member("Anita", "081200005678")
+	a := e.member("Anita", "6281200005678")
-	b := e.member("Budi", "081234561234")
+	b := e.member("Budi", "6281234561234")
-	e.member("Citra", "081255550000")
+	e.member("Citra", "6281255550000")
 	e.credit(t, earn(a, 100, nil))
 	notifier := &notifierFake{}
@@ -0,0 +1,51 @@
 package repository
 import (
 	"context"
 	"fmt"
 	"time"
 	"github.com/redis/go-redis/v9"
 )
 const customerLoginAttemptKeyPrefix = "customer_login:attempts:"
 // CustomerLoginAttemptRepository counts customer login attempts per phone number, so a
 // password cannot be guessed by trying many.
 type CustomerLoginAttemptRepository interface {
 	// Hit counts one attempt for the phone number. It returns the attempts counted in
 	// the current window, this one included, and how long the window still runs. A
 	// window starts at the first attempt after the previous one ended.
 	Hit(ctx context.Context, phoneNumber string, window time.Duration) (int64, time.Duration, error)
 	// Reset forgets the attempts of the phone number.
 	Reset(ctx context.Context, phoneNumber string) error
 }
 type customerLoginAttemptRepository struct {
 	client *redis.Client
 }
 func NewCustomerLoginAttemptRepository(client *redis.Client) CustomerLoginAttemptRepository {
 	return &customerLoginAttemptRepository{client: client}
 }
 func (r *customerLoginAttemptRepository) Hit(ctx context.Context, phoneNumber string, window time.Duration) (int64, time.Duration, error) {
 	key := customerLoginAttemptKeyPrefix + phoneNumber
 	// One transaction, so the key never exists without its expiry: concurrent attempts
 	// all count, and a crash cannot leave a number locked for good.
 	pipe := r.client.TxPipeline()
 	pipe.SetNX(ctx, key, 0, window)
 	count := pipe.Incr(ctx, key)
 	left := pipe.PTTL(ctx, key)
 	if _, err := pipe.Exec(ctx); err != nil {
 		return 0, 0, fmt.Errorf("count login attempt: %w", err)
 	}
 	return count.Val(), left.Val(), nil
 }
 func (r *customerLoginAttemptRepository) Reset(ctx context.Context, phoneNumber string) error {
 	if err := r.client.Del(ctx, customerLoginAttemptKeyPrefix+phoneNumber).Err(); err != nil {
 		return fmt.Errorf("reset login attempts: %w", err)
 	}
 	return nil
 }
@@ -287,7 +287,7 @@ func TestGameSessionRepository_ReadsAndMoves(t *testing.T) {
 	assert.True(t, got.Flagged)
 	assert.NotNil(t, got.CompletionFailedAt)
-	sessions, total, err := f.sessions.ListCustomerSessions(ctx, f.customer, 0, 1)
+	sessions, total, err := f.sessions.ListCustomerSessions(ctx, CustomerSessionFilter{CustomerID: f.customer, Limit: 1})
 	require.NoError(t, err)
 	assert.EqualValues(t, 2, total)
 	assert.Len(t, sessions, 1)
@@ -50,7 +50,7 @@ type GameSessionRepository interface {
 	GetSessionBySpendTransaction(ctx context.Context, spendTransactionID uuid.UUID) (*entities.GameSession, error)
 	// ListCustomerSessions returns a page of a customer's sessions, newest first, and
 	// the total.
-	ListCustomerSessions(ctx context.Context, customerID uuid.UUID, offset, limit int) ([]entities.GameSession, int64, error)
+	ListCustomerSessions(ctx context.Context, filter CustomerSessionFilter) ([]entities.GameSession, int64, error)
 	CompleteSession(ctx context.Context, id uuid.UUID, completion GameSessionCompletion) (bool, error)
 	RefundSession(ctx context.Context, id, refundTransactionID uuid.UUID, reason string, endedAt time.Time) (bool, error)
@@ -70,6 +70,32 @@ type GameSessionRepository interface {
 	CreateSessionRewards(ctx context.Context, rewards []entities.GameSessionReward) error
 	ListSessionRewards(ctx context.Context, sessionID uuid.UUID) ([]entities.GameSessionReward, error)
 	// Leaderboard ranks the active customers of an organization by the EnakCoin their
 	// completed, unflagged sessions started in [from, to) won, and returns the first
 	// limit ranks plus the row of filter.CustomerID wherever it ranks.
 	Leaderboard(ctx context.Context, filter LeaderboardFilter) ([]LeaderboardRow, error)
 }
 // LeaderboardFilter selects the sessions a leaderboard counts.
 type LeaderboardFilter struct {
 	OrganizationID uuid.UUID
 	// Nil for every game.
 	GameID *uuid.UUID
 	From   time.Time
 	To     time.Time
 	Limit  int
 	// The customer asking, returned even below Limit.
 	CustomerID uuid.UUID
 }
 // LeaderboardRow is one customer's total. Equal totals rank by who reached theirs
 // first, so no two rows share a rank.
 type LeaderboardRow struct {
 	Rank       int
 	CustomerID uuid.UUID
 	Name       string
 	Coins      int64
 }
 type gameSessionRepository struct {
@@ -116,8 +142,26 @@ func (r *gameSessionRepository) GetSessionBySpendTransaction(ctx context.Context
 	return r.first(DBFromContext(ctx, r.db).WithContext(ctx).Where("spend_transaction_id = ?", spendTransactionID))
 }
-func (r *gameSessionRepository) ListCustomerSessions(ctx context.Context, customerID uuid.UUID, offset, limit int) ([]entities.GameSession, int64, error) {
+// CustomerSessionFilter selects a customer's sessions.
-	q := DBFromContext(ctx, r.db).WithContext(ctx).Model(&entities.GameSession{}).Where("customer_id = ?", customerID)
+type CustomerSessionFilter struct {
 	CustomerID uuid.UUID
 	// Nil for every game.
 	GameID *uuid.UUID
 	// Empty for every status.
 	Status string
 	Offset int
 	Limit  int
 }
 func (r *gameSessionRepository) ListCustomerSessions(ctx context.Context, filter CustomerSessionFilter) ([]entities.GameSession, int64, error) {
 	q := DBFromContext(ctx, r.db).WithContext(ctx).Model(&entities.GameSession{}).Where("customer_id = ?", filter.CustomerID)
 	if filter.GameID != nil {
 		q = q.Where("game_id = ?", *filter.GameID)
 	}
 	if filter.Status != "" {
 		q = q.Where("status = ?", filter.Status)
 	}
 	offset, limit := filter.Offset, filter.Limit
 	var total int64
 	if err := q.Count(&total).Error; err != nil {
 		return nil, 0, fmt.Errorf("failed to count game sessions: %w", err)
@@ -237,3 +281,45 @@ func (r *gameSessionRepository) ListDueSessions(ctx context.Context, now time.Ti
 	}
 	return due, nil
 }
 func (r *gameSessionRepository) Leaderboard(ctx context.Context, filter LeaderboardFilter) ([]LeaderboardRow, error) {
 	gameFilter, args := "", []any{filter.OrganizationID, filter.From, filter.To, constants.GameSessionStatusCompleted}
 	if filter.GameID != nil {
 		gameFilter = "AND s.game_id = ?"
 		args = append(args, *filter.GameID)
 	}
 	args = append(args, filter.Limit, filter.CustomerID)
 	var rows []struct {
 		Rank       int
 		CustomerID string
 		Name       string
 		Coins      int64
 	}
 	err := DBFromContext(ctx, r.db).WithContext(ctx).Raw(`
 		WITH totals AS (
 			SELECT s.customer_id, SUM(s.reward_total) AS coins, MAX(s.ended_at) AS reached_at
 			FROM game_sessions s
 			WHERE s.organization_id = ? AND s.started_at >= ? AND s.started_at < ?
 				AND s.status = ? AND NOT s.flagged AND s.reward_total > 0 `+gameFilter+`
 			GROUP BY s.customer_id
 		), ranked AS (
 			SELECT t.customer_id, c.name, t.coins,
 				ROW_NUMBER() OVER (ORDER BY t.coins DESC, t.reached_at, t.customer_id) AS rank
 			FROM totals t
 			JOIN customers c ON c.id = t.customer_id AND c.is_active
 		)
 		SELECT rank, customer_id::text AS customer_id, name, coins
 		FROM ranked
 		WHERE rank <= ? OR customer_id = ?
 		ORDER BY rank`, args...).Scan(&rows).Error
 	if err != nil {
 		return nil, fmt.Errorf("failed to read game leaderboard: %w", err)
 	}
 	out := make([]LeaderboardRow, 0, len(rows))
 	for _, row := range rows {
 		l := LeaderboardRow{Rank: row.Rank, Name: row.Name, Coins: row.Coins}
 		l.CustomerID, _ = uuid.Parse(row.CustomerID)
 		out = append(out, l)
 	}
 	return out, nil
 }
@@ -197,10 +197,14 @@ func (r *Router) addAppRoutes(rg *gin.Engine) {
 				enakGame.GET("/sessions", r.enakGameCustomerHandler.ListSessions)
 				enakGame.GET("/sessions/:id", r.enakGameCustomerHandler.GetSession)
 				enakGame.POST("/sessions/:id/complete", r.enakGameCustomerHandler.CompleteSession)
-				enakGame.GET("/vouchers", r.enakGameCustomerHandler.ListVouchers)
+				enakGame.GET("/leaderboard", r.enakGameCustomerHandler.Leaderboard)
 				enakGame.POST("/vouchers/:id/redeem", r.enakGameCustomerHandler.RedeemVoucher)
 				enakGame.GET("/redemptions", r.enakGameCustomerHandler.ListRedemptions)
 			}
 			// Vouchers: what EnakPoint is spent on, whatever it came from (docs/rfc-enakgame.md
 			// §5.7, §7.4), so not under /enakgame.
 			customer.GET("/vouchers", r.enakGameCustomerHandler.ListVouchers)
 			customer.GET("/vouchers/redemptions", r.enakGameCustomerHandler.ListRedemptions)
 			customer.POST("/vouchers/:id/redeem", r.enakGameCustomerHandler.RedeemVoucher)
 		}
 		selfOrder := v1.Group("/self-order")
@@ -634,14 +638,19 @@ func (r *Router) addAppRoutes(rg *gin.Engine) {
 					enakGame.POST("/events", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.CreateEvent)
 					enakGame.PUT("/events/:id", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.UpdateEvent)
 					enakGame.PUT("/events/:id/status", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.SetEventStatus)
 				}
-					enakGame.GET("/vouchers", r.enakGameAdminHandler.ListVouchers)
+				// Vouchers EnakPoint is redeemed for, whatever it came from; not part of
-					enakGame.GET("/vouchers/:id", r.enakGameAdminHandler.GetVoucher)
+				// EnakGame. Writing them takes a loyalty manager.
-					enakGame.GET("/vouchers/:id/codes", r.enakGameAdminHandler.ListVoucherCodes)
+				vouchers := gamification.Group("/vouchers")
-					enakGame.POST("/vouchers", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.CreateVoucher)
+				{
-					enakGame.PUT("/vouchers/:id", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.UpdateVoucher)
+					vouchers.GET("", r.enakGameAdminHandler.ListVouchers)
-					enakGame.PUT("/vouchers/:id/status", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.SetVoucherStatus)
+					vouchers.GET("/:id", r.enakGameAdminHandler.GetVoucher)
-					enakGame.POST("/vouchers/:id/codes", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.ImportVoucherCodes)
+					vouchers.GET("/:id/codes", r.enakGameAdminHandler.ListVoucherCodes)
 					vouchers.POST("", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.CreateVoucher)
 					vouchers.PUT("/:id", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.UpdateVoucher)
 					vouchers.PUT("/:id/status", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.SetVoucherStatus)
 					vouchers.POST("/:id/codes", r.authMiddleware.RequireLoyaltyManager(), r.enakGameAdminHandler.ImportVoucherCodes)
 				}
 				campaignRules := gamification.Group("/campaign-rules")
@@ -72,8 +72,9 @@ type EnakGameCustomerService interface {
 	ListGames(ctx context.Context, customerID uuid.UUID) *contract.Response
 	StartSession(ctx context.Context, customerID uuid.UUID, req *contract.StartGameSessionRequest, idempotencyKey string) *contract.Response
 	CompleteSession(ctx context.Context, customerID, sessionID uuid.UUID, in models.GameSessionCompleteInput) *contract.Response
-	ListSessions(ctx context.Context, customerID uuid.UUID, page, limit int) *contract.Response
+	ListSessions(ctx context.Context, customerID uuid.UUID, q models.GameSessionListQuery) *contract.Response
 	GetSession(ctx context.Context, customerID, sessionID uuid.UUID) *contract.Response
 	Leaderboard(ctx context.Context, customerID uuid.UUID, q models.EnakGameLeaderboardQuery) *contract.Response
 	ListVouchers(ctx context.Context, customerID uuid.UUID) *contract.Response
 	RedeemVoucher(ctx context.Context, customerID, voucherID uuid.UUID, req *contract.RedeemVoucherRequest, idempotencyKey string, info models.CustomerPinRequestInfo) *contract.Response
@@ -371,8 +372,8 @@ func (s *EnakGameCustomerServiceImpl) CompleteSession(ctx context.Context, custo
 	return respond(ctx, completion, err)
 }
-func (s *EnakGameCustomerServiceImpl) ListSessions(ctx context.Context, customerID uuid.UUID, page, limit int) *contract.Response {
+func (s *EnakGameCustomerServiceImpl) ListSessions(ctx context.Context, customerID uuid.UUID, q models.GameSessionListQuery) *contract.Response {
-	sessions, err := s.sessions.ListSessions(ctx, customerID, page, limit)
+	sessions, err := s.sessions.ListSessions(ctx, customerID, q)
 	return respond(ctx, sessions, err)
 }
@@ -381,6 +382,11 @@ func (s *EnakGameCustomerServiceImpl) GetSession(ctx context.Context, customerID
 	return respond(ctx, session, err)
 }
 func (s *EnakGameCustomerServiceImpl) Leaderboard(ctx context.Context, customerID uuid.UUID, q models.EnakGameLeaderboardQuery) *contract.Response {
 	board, err := s.sessions.Leaderboard(ctx, customerID, q)
 	return respond(ctx, board, err)
 }
 // decodeStrict reads a JSON body into v, refusing unknown fields and trailing data.
 // It returns the error response, or nil when the body fits.
 func decodeStrict(body []byte, v any) *contract.Response {
@@ -0,0 +1,41 @@
 package util
 import (
 	"errors"
 	"regexp"
 	"strings"
 )
 // ErrInvalidPhoneNumber means a phone number is not an Indonesian mobile number.
 var ErrInvalidPhoneNumber = errors.New("invalid phone number format")
 // customerPhonePattern is an Indonesian mobile number in its stored form: 62, then the
 // number without its leading 0 (628…, 10 to 14 digits in all).
 var customerPhonePattern = regexp.MustCompile(`^628\d{7,11}$`)
 // NormalizePhoneNumber turns a customer's phone number into the one form it is stored
 // and looked up in, 62…: "0812-3456-1234", "+62 812 3456 1234", "62812…" and "812…"
 // all become "6281234561234". Spaces, dashes, dots and parentheses are dropped.
 func NormalizePhoneNumber(raw string) (string, error) {
 	digits := strings.Map(func(r rune) rune {
 		switch r {
 		case ' ', '-', '.', '(', ')':
 			return -1
 		}
 		return r
 	}, strings.TrimSpace(raw))
 	digits = strings.TrimPrefix(digits, "+")
 	switch {
 	case strings.HasPrefix(digits, "620"):
 		// +62 typed in front of a number that kept its 0.
 		digits = "62" + digits[3:]
 	case strings.HasPrefix(digits, "0"):
 		digits = "62" + digits[1:]
 	case strings.HasPrefix(digits, "8"):
 		digits = "62" + digits
 	}
 	if !customerPhonePattern.MatchString(digits) {
 		return "", ErrInvalidPhoneNumber
 	}
 	return digits, nil
 }
@@ -0,0 +1,49 @@
 package util
 import (
 	"testing"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 func TestNormalizePhoneNumber(t *testing.T) {
 	for _, raw := range []string{
 		"6281234561234",
 		"+6281234561234",
 		"081234561234",
 		"81234561234",
 		"0812-3456-1234",
 		"+62 812 3456 1234",
 		"(+62) 812.3456.1234",
 		"+62081234561234",
 		" 081234561234 ",
 	} {
 		got, err := NormalizePhoneNumber(raw)
 		require.NoError(t, err, raw)
 		assert.Equal(t, "6281234561234", got, raw)
 	}
 	shortest, err := NormalizePhoneNumber("0811234567")
 	require.NoError(t, err)
 	assert.Equal(t, "62811234567", shortest)
 	longest, err := NormalizePhoneNumber("0812345678901")
 	require.NoError(t, err)
 	assert.Equal(t, "62812345678901", longest)
 	_, err = NormalizePhoneNumber("08123456789012")
 	assert.ErrorIs(t, err, ErrInvalidPhoneNumber, "too long")
 	for _, raw := range []string{
 		"",
 		"0",
 		"021-1234567",     // a landline, cannot get the WhatsApp OTP
 		"+6521234567",     // not Indonesian
 		"+1 415 555 0100", // not Indonesian
 		"62812",           // too short
 		"0812abc61234",
 		"0812/3456/1234",
 	} {
 		_, err := NormalizePhoneNumber(raw)
 		assert.ErrorIs(t, err, ErrInvalidPhoneNumber, raw)
 	}
 }
@@ -9,6 +9,7 @@ import (
 	"apskel-pos-be/internal/constants"
 	"apskel-pos-be/internal/contract"
 	"apskel-pos-be/internal/util"
 )
 type CustomerAuthValidator interface {
@@ -36,7 +37,7 @@ func (v *CustomerAuthValidatorImpl) ValidateCheckPhoneRequest(req *contract.Chec
 		return errors.New("phone number is required"), constants.ValidationErrorCode
 	}
-	if !v.isValidPhoneNumber(req.PhoneNumber) {
+	if !v.normalizePhoneNumber(&req.PhoneNumber) {
 		return errors.New("invalid phone number format"), constants.ValidationErrorCode
 	}
@@ -53,7 +54,7 @@ func (v *CustomerAuthValidatorImpl) ValidateRegisterStartRequest(req *contract.R
 		return errors.New("phone number is required"), constants.ValidationErrorCode
 	}
-	if !v.isValidPhoneNumber(req.PhoneNumber) {
+	if !v.normalizePhoneNumber(&req.PhoneNumber) {
 		return errors.New("invalid phone number format"), constants.ValidationErrorCode
 	}
@@ -161,7 +162,7 @@ func (v *CustomerAuthValidatorImpl) ValidateCustomerLoginRequest(req *contract.C
 		return errors.New("phone number is required"), constants.ValidationErrorCode
 	}
-	if !v.isValidPhoneNumber(req.PhoneNumber) {
+	if !v.normalizePhoneNumber(&req.PhoneNumber) {
 		return errors.New("invalid phone number format"), constants.ValidationErrorCode
 	}
@@ -174,10 +175,15 @@ func (v *CustomerAuthValidatorImpl) ValidateCustomerLoginRequest(req *contract.C
 }
 // Helper validation functions
-func (v *CustomerAuthValidatorImpl) isValidPhoneNumber(phoneNumber string) bool {
+// normalizePhoneNumber rewrites the phone number in the form it is stored in, 62…
-	// Basic phone number validation - adjust regex based on your requirements
+// (util.NormalizePhoneNumber), and reports false when it is not a valid one.
-	phoneRegex := regexp.MustCompile(`^\+?[1-9]\d{1,14}$`)
+func (v *CustomerAuthValidatorImpl) normalizePhoneNumber(phoneNumber *string) bool {
-	return phoneRegex.MatchString(phoneNumber)
+	normalized, err := util.NormalizePhoneNumber(*phoneNumber)
 	if err != nil {
 		return false
 	}
 	*phoneNumber = normalized
 	return true
 }
 func (v *CustomerAuthValidatorImpl) isValidDateFormat(date string) bool {
@@ -208,7 +214,7 @@ func (v *CustomerAuthValidatorImpl) ValidateResendOtpRequest(req *contract.Resen
 	}
 	// Validate phone number format
-	if !v.isValidPhoneNumber(req.PhoneNumber) {
+	if !v.normalizePhoneNumber(&req.PhoneNumber) {
 		return errors.New("invalid phone number format"), constants.CustomerEntity
 	}
@@ -2,6 +2,21 @@
 -- which budget (docs/rfc-enakgame.md §5.7, D5). Replaces the unused rewards table for
 -- EnakGame; rewards itself stays.
 -- Some databases still have the vouchers table of the reverted Voucher Undian feature
 -- (commit cfe690a). Keep its data under another name; its primary key index is renamed
 -- too, or vouchers_pkey below would clash.
 DO $$
 BEGIN
    IF EXISTS (
        SELECT 1 FROM information_schema.columns
        WHERE table_schema = current_schema() AND table_name = 'vouchers' AND column_name = 'winner_number'
    ) THEN
        ALTER TABLE vouchers RENAME TO vouchers_undian_legacy;
        ALTER INDEX IF EXISTS vouchers_pkey RENAME TO vouchers_undian_legacy_pkey;
        ALTER INDEX IF EXISTS vouchers_voucher_code_key RENAME TO vouchers_undian_legacy_voucher_code_key;
    END IF;
 END $$;
 CREATE TABLE vouchers (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    organization_id UUID NOT NULL,
@@ -0,0 +1,2 @@
 -- Nothing to undo: the forms the numbers were stored in before are not kept, and 62… is
 -- what the code before this migration accepted too.
@@ -0,0 +1,62 @@
 -- Customer phone numbers are stored in one form, 62… without + (util.NormalizePhoneNumber),
 -- and every number a customer types is rewritten to it before it is looked up. This
 -- rewrites the numbers stored before, so 0812…, +62 812… and 812… become 62812….
 --
 -- Only one customer may have a number. When several stored numbers become the same one,
 -- the customer that already has it keeps it, else a registered one (with a password),
 -- else the oldest; the others are left as they are. A number that is not an Indonesian
 -- mobile number is left as it is too. Neither can log in until it is fixed by hand:
 --
 --   SELECT id, name, phone_number FROM customers
 --   WHERE phone_number IS NOT NULL AND phone_number !~ '^628[0-9]{7,11}$';
 WITH stripped AS (
    SELECT id, phone_number, password_hash, created_at,
           regexp_replace(regexp_replace(phone_number, '[[:space:]().-]', '', 'g'), '^\+', '') AS p
    FROM customers
    WHERE phone_number IS NOT NULL
 ),
 normalized AS (
    SELECT id, phone_number, password_hash, created_at,
           CASE
               WHEN p LIKE '620%' THEN '62' || substr(p, 4)
               WHEN p LIKE '0%' THEN '62' || substr(p, 2)
               WHEN p LIKE '8%' THEN '62' || p
               ELSE p
           END AS new_phone
    FROM stripped
 ),
 ranked AS (
    SELECT id, new_phone,
           row_number() OVER (
               PARTITION BY new_phone
               ORDER BY phone_number = new_phone DESC, password_hash IS NOT NULL DESC, created_at, id
           ) AS rank
    FROM normalized
    WHERE new_phone ~ '^628[0-9]{7,11}$'
 )
 UPDATE customers c
 SET phone_number = r.new_phone, updated_at = NOW()
 FROM ranked r
 WHERE c.id = r.id AND r.rank = 1 AND c.phone_number <> r.new_phone;
 -- A registration started before this migration finishes with the number in its OTP
 -- session, and a resent OTP is found by it.
 UPDATE otp_sessions
 SET phone_number = n.new_phone, updated_at = NOW()
 FROM (
    SELECT id,
           CASE
               WHEN p LIKE '620%' THEN '62' || substr(p, 4)
               WHEN p LIKE '0%' THEN '62' || substr(p, 2)
               WHEN p LIKE '8%' THEN '62' || p
               ELSE p
           END AS new_phone
    FROM (
        SELECT id, regexp_replace(regexp_replace(phone_number, '[[:space:]().-]', '', 'g'), '^\+', '') AS p
        FROM otp_sessions
    ) stripped
 ) n
 WHERE otp_sessions.id = n.id
  AND n.new_phone ~ '^628[0-9]{7,11}$'
  AND otp_sessions.phone_number <> n.new_phone;
Author	SHA1	Message	Date
efrilm	0f60aadbfd	fix: migration	2026-10-12 22:07:22 +07:00
efrilmandClaude Opus 5.5	3af16a1fbc	feat(enakgame): weekly leaderboard GET /customer/enakgame/leaderboard ranks the customers of an organization by the EnakCoin they won from games in one week, Monday to Sunday in Asia/Jakarta. Only completed, unflagged sessions count, by the week they started; entry cost is not subtracted. Equal totals rank by who reached theirs first, so no two customers share a rank. Optional date (any day of the week, this week by default), game_id and limit (10, at most 100). The response holds the top ranks and, under me, the customer asking wherever they rank. Other customers are shown by a masked name: the first word whole, the others by their first letter; a word with a digit keeps only its first character. The EnakGame web game shows it: integration-enakgame.md §10 (checklist now §11) and RFC §11. The DB test needs TEST_DATABASE_URL. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-12 16:15:02 +07:00
efrilmandClaude Opus 5.5	c43baa53e1	docs: EnakGame game list, API list and in-game login integration-enakgame.md was only the flow of a play. It now also has: - §2 the games: Spin is the only one; what each reward_type needs from the client at complete; what to agree on to register a new game. - §3 the endpoints the client calls, in one table. - §5 tokens: with no token, or one the backend refuses, the game shows a customer login (POST /customer-auth/login) and repeats the request once. Standalone mode for a browser without the app finds its game_id by slug. The login errors (304, 429 with locked_until), the attempt limit and the phone formats accepted. A JS helper for all of it. The bridge loses token_expired and token: the game logs the customer in itself. Sections are renumbered. integration-mobile-customer.md: customer phone numbers are 62… (§2), a login section with its errors and the change from 900 to 304 (§2.4), 62… examples, and init carrying the access token. integration-backoffice.md: example responses are the data field, so a list is data.data in a raw response. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-09 22:59:58 +07:00
efrilmandClaude Opus 5.5	a01e651709	fix(customer-auth): refuse a wrong login with 304 and limit attempts A wrong password or an unknown phone number was answered 900 (HTTP 500), like a server error, so clients could only tell them apart by the cause text. Both are now 304 (HTTP 400) from customer_auth_service with one cause, "invalid phone number or password", so a login does not tell which numbers have an account. A customer who never set a password gets 304 "customer not properly registered". Anything else stays 900. Login is limited per phone number: 5 attempts in 15 minutes, counted in Redis before the password is checked, so attempts sent at once all count, and for numbers without a customer too. The sixth is refused with 429 and data.locked_until, even with the right password, until the window ends. A successful login starts the count again. Since the number is normalized first, 0812… and 62812… count as one. When Redis fails, logins go on unlimited and the error is logged. There is no limit per IP: the client IP comes from X-Forwarded-For, which anyone can set while no trusted proxies are configured. Tested over HTTP with fakes; the Redis commands were checked against miniredis outside the repo, not against a real Redis. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-09 22:59:27 +07:00
efrilmandClaude Opus 5.5	19afa50b9c	feat(customers): store customer phone numbers as 62… A customer's phone number (customers.phone_number, the one they log in with) has one stored form, 62 followed by the number without its 0: 6281234561234. util.NormalizePhoneNumber rewrites 0812…, +62 812…, 62812…, 812… and +62 0812…, with spaces, dashes, dots or parentheses, to it, and refuses anything that is not an Indonesian mobile number (628 and 7 to 11 more digits). It is applied wherever a customer types their number: check-phone, register, login and resend-OTP (the validator rewrites the request), and the transfer recipient. Before, the number was matched as typed and a leading 0 was refused, so the same customer written another way was not found. The masked recipient stays 08-**-1234 as customers write numbers. Migration 000116 rewrites the numbers already stored in customers and otp_sessions. When several become the same number, the customer that already has it keeps it, else a registered one, else the oldest; the others, and numbers that are not Indonesian mobile numbers, are left as they are and cannot log in until fixed by hand (the query to find them is in the migration). Down does nothing. The migration was run, twice, against Postgres with a reduced customers and otp_sessions schema and sample numbers; not against the real schema. The Postgres tests were not run. customers.phone (the POS contact number) is not touched. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-09 22:58:24 +07:00
efrilmandClaude Opus 5.5	4b7eddbd3e	fix(cors): allow the Idempotency-Key header The EnakGame client runs at its game_url, another origin than the API, so the browser asks before POST /customer/enakgame/sessions. Idempotency-Key was not in Access-Control-Allow-Headers, so the preflight refused it and a play could not start. X-Idempotency-Key, the older name the backend also reads, is allowed too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-09 22:58:02 +07:00
efrilmandClaude Opus 5.5	52e8fe11c6	feat(enakgame): filter play history by game and status GET /customer/enakgame/sessions takes optional game_id and status, so a game reloaded mid-play finds the session it was running (status=STARTED) instead of starting a new one and charging EnakCoin again. An invalid game_id or status is refused. integration-enakgame.md §4.4 now describes recovery after a reload: keep the session_id in sessionStorage, continue a STARTED session before expires_at, and call complete again for a COMPLETED one to get the full answer, prize included. The mobile guide and RFC §11 mention the filters. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-08 12:51:39 +07:00
efrilmandClaude Opus 5.5	b5d2cd491a	docs: integration guides for mobile customer, POS, EnakGame and backoffice One guide per team, covering EnakPoint, EnakCoin, EnakGame and vouchers: - integration-mobile-customer.md: wallet, history (with the game and voucher ledger types), push, PIN, exchange, transfer, game list and webview, play history, voucher catalog, redeem and my vouchers. - integration-pos.md: linking customers to orders, earning, receipts, void/refund, and vouchers as a known gap (no POS endpoint to mark one used). - integration-enakgame.md: the Phaser client's side of a play: start with Idempotency-Key, complete, rewards, spin, expiry and refunds, retries. - integration-backoffice.md: loyalty settings and customer wallets, plus games, reward configs, spin setup, budgets, metrics and recommendations, events, vouchers and code import, analytics. The JS bridge between the app and the game is a proposal both teams still have to agree on. Replaces api-enakpoint.md, integration-enakpoint.md, mobile-customer-enakpoint.md, backoffice-enakpoint.md and enakgame-spin.md. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-08 11:10:05 +07:00
efrilmandClaude Opus 5.5	1bb071aec6	refactor(vouchers): move voucher routes out of /enakgame Vouchers are what EnakPoint is redeemed for, wherever it came from, so they are not part of EnakGame. Their only link to it is the budget attribution, which does not change. - Admin: /marketing/enakgame/vouchers... -> /marketing/vouchers... - Customer: /customer/enakgame/vouchers -> /customer/vouchers, /customer/enakgame/vouchers/:id/redeem -> /customer/vouchers/:id/redeem, /customer/enakgame/redemptions -> /customer/vouchers/redemptions Roles, handlers and logic stay the same. No client calls these endpoints yet. RFC §7.4 and §11 updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>	2026-10-08 11:09:57 +07:00
		`@@ -0,0 +1,2 @@`
							`-- Nothing to undo: the forms the numbers were stored in before are not kept, and 62… is`
							`-- what the code before this migration accepted too.`