Revert "feat(loyalty): EnakPoint & EnakCoin" (#32)

This reverts merge commit 645da30, returning main to f0ff59f.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/api-enakpoint.md

@@ -1,439 +0,0 @@
-# API EnakPoint & EnakCoin
-
-30 Sep 2026
-
-Semua endpoint EnakPoint (`POINT`, bisa bayar order) 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.
-
-## 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`. `POST /payments` wajib `X-Idempotency-Key` seperti pembayaran lain.
-
-**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/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,PAYMENT` |
-| `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 bayar, kode bayar, 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; pembayaran dan 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: bayar, exchange, transfer, game
-
-| Method | Path | PIN | Idempotency-Key |
-| --- | --- | --- | --- |
-| POST | `/customer/wallet/payment-code` | Ya | – |
-| POST | `/customer/orders/:id/pay-with-points` | Ya | – |
-| 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/spin` | – | – |
-
-### POST /customer/wallet/payment-code
-
-Body `{ "pin": "482913" }`. Response:
-
-```json
-{ "code": "482913", "qr_payload": "enakpoint:482913", "expires_at": "2026-09-30T05:02:00Z" }
-```
-
-Tampilkan `code` sebagai angka dan `qr_payload` sebagai QR untuk kasir. Berlaku 2 menit, sekali pakai, hanya untuk customer ini; kode baru membatalkan kode lama.
-
-### POST /customer/orders/:id/pay-with-points
-
-Body `{ "points": 12500, "pin": "482913" }`. Hanya untuk order milik customer yang login (order lain `404`). Response sama dengan pembayaran POS (bagian POS). Batas dan aturan penolakan juga sama.
-
-### 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`.
-
-### POST /customer/spin
-
-Body `{ "spin_id": "<id game>" }`. Memotong EnakCoin sebesar `metadata.coin_cost` game itu (default 1).
-
-```json
-{
-  "game_play": { "id": "…", "game_id": "…", "coins_used": 1, "created_at": "…" },
-  "prize_won": { "id": "…", "name": "Voucher 10rb" },
-  "coins_remaining": 7
-}
-```
-
-EnakCoin kurang, game nonaktif, atau hadiah baru saja habis → `304`, tidak ada EnakCoin yang terpotong.
-
-## POS: pembayaran EnakPoint
-
-Kasir memakai endpoint pembayaran yang sudah ada dengan payment method bertipe `point`, disetujui customer lewat kode bayar dari aplikasinya; PIN tidak pernah diketik di perangkat kasir.
-
-| Method | Path | Keterangan |
-| --- | --- | --- |
-| GET | `/orders/:id/point-payment/preview` | Batas pembayaran EnakPoint untuk order ini |
-| POST | `/payments` | Bayar dengan method EnakPoint (`points` + `payment_code`) |
-| POST | `/payments/:id/refund` | Refund pembayaran EnakPoint, kembali sebagai EnakPoint |
-
-1. Customer membuat kode di aplikasi (`POST /customer/wallet/payment-code`) dan menunjukkan angka atau QR-nya.
-2. POS memanggil preview untuk tombol "pakai maksimal".
-3. POS memanggil `POST /payments` dengan kode tersebut. Sisa tagihan dibayar dengan method lain seperti biasa.
-
-### GET /orders/:id/point-payment/preview
-
-```json
-{
-  "order_id": "…",
-  "customer_id": "…",
-  "eligible": true,
-  "point_balance": 12500,
-  "point_value": 1,
-  "remaining_amount": 87500,
-  "min_payment_points": 1,
-  "max_payment_percent": 100,
-  "max_points": 12500,
-  "max_amount": 12500
-}
-```
-
-Bila `eligible: false`, `reason` menjelaskan kenapa (order walk-in, outlet tidak menerima EnakPoint, saldo di bawah minimal, dst.). Batas yang dipakai:
-
-```
-batas_rupiah = min(sisa_tagihan, total × max_payment_percent / 100 − sudah_dibayar_EnakPoint)
-maks_point   = min(saldo, floor(batas_rupiah / point_value))
-```
-
-### POST /payments
-
-Header `X-Idempotency-Key` wajib.
-
-```json
-{
-  "order_id": "…",
-  "payment_method_id": "<id method EnakPoint>",
-  "points": 12500,
-  "payment_code": "482913"
-}
-```
-
-- `amount` tidak perlu dikirim; backend menghitung `points × point_value` dan tidak pernah melebihi sisa tagihan (tidak ada kembalian).
-- `payment_code` boleh angka yang diketik atau hasil scan QR apa adanya (`enakpoint:482913`).
-- Response pembayaran membawa `points_used` dan `point_value` untuk struk; response order membawa `points_earned` dan `coins_earned`.
-- Ditolak `304` bila: order tanpa customer atau walk-in, customer nonaktif, outlet tidak menerima EnakPoint, `points` di luar batas, kode salah/kedaluwarsa/sudah dipakai/milik customer lain, atau method EnakPoint dipakai sebagai split. Kode terpakai begitu diterima; bila pembayaran lalu ditolak, minta kode baru.
-- Method EnakPoint dibuat otomatis per organisasi, tidak bisa dihapus atau diubah tipenya, dan tidak muncul di daftar method `?outlet_id=` bila outlet tidak menerima EnakPoint.
-
-### Void dan refund
-
-- **Void order:** semua EnakPoint yang dipakai kembali sebagai EnakPoint.
-- **`POST /payments/:id/refund` pada pembayaran EnakPoint:** kembali `floor(rupiah_direfund / point_value_saat_bayar)`; sisa di bawah 1 EnakPoint hangus.
-- **Refund order ke tunai/method lain** hanya sebesar bagian non-EnakPoint; mencoba merefund bagian EnakPoint secara tunai ditolak `304`.
-- EnakPoint yang kembali memakai tanggal kedaluwarsa asal, minimal 7 hari sejak refund. Earning order ikut ditarik; 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 dan penerimaan EnakPoint 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_per_amount": 100, "earn_value": 1, "min_order_amount": 0, "max_per_order": null },
-  "coin": { "enabled": true, "earn_per_amount": 25000, "earn_value": 1, "min_order_amount": 0, "max_per_order": null },
-  "point_payment": { "accept_payment": true, "min_payment_points": 1, "max_payment_percent": 100 }
-}
-```
-
-Response menambahkan `outlet_id`, `point_value`, `point_cashback_percent` (default di atas = 1%), dan `changes` pada PUT. Validasi: `earn_per_amount > 0`, `earn_value ≥ 0`, `max_payment_percent` 0–100.
-
-### /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" }
-}
-```
-
-| 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": "PAYMENT", "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, exchange, atau refund 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` |
-| `PAYMENT` | − | Membayar order (EnakPoint saja) | `PAYMENT` |
-| `PAYMENT_REFUND` | + | Kembali karena pembayaran di-void/refund | `PAYMENT` |
-| `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.
-
-| Lama | Pengganti |
-| --- | --- |
-| `GET /customer/points` | `GET /customer/wallet` → `point_balance` |
-| `GET /customer/tokens` | `GET /customer/wallet` → `coin_balance` |
-| `total_points`, `total_tokens`, `points_history`, `tokens_history`, `last_updated` di `/customer/wallet` | `point_balance`, `coin_balance`, `recent_transactions` |
-| `token_used`, `tokens_remaining` di response game | `coins_used`, `coins_remaining` |
-| `sort_by=token_used` di daftar game play | `sort_by=coins_used` |
-
-Panduan alur lengkap per tim ada di [`integration-enakpoint.md`](./integration-enakpoint.md).

docs/backoffice-enakpoint.md

@@ -1,305 +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.
-
-## 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 | `PUT` game yang sudah ada, `metadata.coin_cost` | Marketing → Game → edit game |
-
-Penempatan menu di atas adalah usulan; sesuaikan dengan struktur backoffice yang ada.
-
-**Istilah di layar.** EnakPoint (`POINT`) adalah saldo yang bisa membayar order; 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, dan apakah outlet menerima pembayaran EnakPoint. 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.
-
-```json
-{
-  "point": { "enabled": true, "earn_per_amount": 100, "earn_value": 1, "min_order_amount": 0, "max_per_order": null },
-  "coin": { "enabled": true, "earn_per_amount": 25000, "earn_value": 1, "min_order_amount": 0, "max_per_order": null },
-  "point_payment": { "accept_payment": true, "min_payment_points": 1, "max_payment_percent": 100 }
-}
-```
-
-| Field | Label usulan | Tipe | Default | Validasi |
-| --- | --- | --- | --- | --- |
-| `point.enabled` / `coin.enabled` | Beri EnakPoint / EnakCoin | toggle | mati | – |
-| `earn_per_amount` | Setiap belanja Rp … | Rp | 100 (point), 25.000 (coin) | > 0 |
-| `earn_value` | … mendapat | angka | 1 | ≥ 0 |
-| `min_order_amount` | Minimal belanja | Rp | 0 | ≥ 0 |
-| `max_per_order` | Maksimal per order | angka, boleh kosong | kosong = tanpa batas | ≥ 0 |
-| `point_payment.accept_payment` | Terima pembayaran EnakPoint | toggle | mati | – |
-| `min_payment_points` | Minimal EnakPoint per pembayaran | angka | 1 | ≥ 1 |
-| `max_payment_percent` | Maksimal porsi order dibayar EnakPoint | % | 100 | 0–100 |
-
-**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`. Tujuannya agar owner tidak salah membaca skala (1 per Rp 100 bukan 1 per Rp 1).
-
-**Contoh di bawah form.** "Belanja Rp 87.500 mendapat 875 EnakPoint dan 3 EnakCoin." Earning dihitung dari subtotal setelah diskon, sebelum pajak, dan bagian yang dibayar EnakPoint tidak ikut dihitung.
-
-Setelah `PUT`, response membawa `changes` (key yang berubah); tampilkan toast singkat, mis. "2 pengaturan disimpan". Mematikan `accept_payment` langsung menyembunyikan method EnakPoint di kasir outlet itu.
-
-## 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" }
-}
-```
-
-| 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 |
-
-### 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: pembayaran, refund, dan exchange yang sudah terjadi memakai nilai 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=PAYMENT,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 atau kasir penerima pembayaran), `outlet`, `reason`, dan `metadata` (kurs, nilai EnakPoint yang dibekukan, 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": "PAYMENT", "amount": -30, "description": "Bayar #ORD-0456 di Outlet Kemang (Rp 30)", "reference_type": "PAYMENT", "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, game, dan method EnakPoint
-
-### 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. Biaya per main diisi di `metadata.coin_cost` saat membuat atau mengedit game (`/marketing/games`): bilangan bulat ≥ 1, default 1 bila kosong. Nilai pecahan, 0, atau teks membuat game tidak bisa dimainkan. Karena `metadata` dikirim utuh, pertahankan key metadata lain saat menyimpan. Hadiah game juga bernilai rupiah secara tidak langsung, karena EnakCoin bisa ditukar ke EnakPoint.
-
-### Method pembayaran EnakPoint
-
-Method "EnakPoint" (tipe `point`) dibuat otomatis untuk setiap organisasi. Di layar Payment Method (`/payment-methods`):
-
-- Tampilkan sebagai method sistem: tombol hapus dan pilihan ubah tipe disembunyikan; backend menolaknya (`304`). Nama boleh diganti.
-- Tipe `point` tidak ditawarkan saat membuat method baru.
-- Kasir hanya melihatnya di outlet yang menyalakan "Terima pembayaran EnakPoint".
-
-Di laporan per payment method, EnakPoint tampil terpisah dan **tidak** dihitung sebagai kas masuk.
-
-## 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, hapus/ubah method EnakPoint | `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.
-- [ ] Method EnakPoint tampil sebagai method sistem.
-- [ ] Form game punya input `coin_cost`.
-- [ ] Semua nilai rupiah EnakPoint ditulis "setara potongan Rp …".
-
-Pembayaran EnakPoint belum boleh dirilis ke outlet sebelum tinjauan keuangan (N2) dan legal (N3) selesai, dan transfer menunggu tinjauan legal (N3). Layar backoffice boleh disiapkan lebih dulu.

docs/integration-enakpoint.md

@@ -1,635 +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).
-
----
-
-## 1. Konsep inti
-
-| | EnakPoint (`POINT`) | EnakCoin (`COIN`) |
-|---|---|---|
-| Didapat dari | Order lunas (per outlet), adjustment admin, exchange | Order lunas (per outlet), adjustment admin |
-| Dipakai untuk | **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, tidak ada kembalian, dan
-   bagian order yang dibayar EnakPoint hanya bisa kembali sebagai EnakPoint. Tampilkan
-   nilai rupiahnya sebagai **"setara potongan Rp …"**, bukan "saldo Rp …".
-3. **Semua aksi customer yang memindahkan saldo butuh PIN 6 digit** (§3): bayar,
-   buat kode bayar, exchange, 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 dan penerimaan pembayaran 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,PAYMENT&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, pembayaran, 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` |
-| `PAYMENT` | − | Membayar order | `PAYMENT` |
-| `PAYMENT_REFUND` | + | Kembali karena pembayaran di-void/refund | `PAYMENT` |
-| `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**;
-  pembayaran dan 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. Membayar dengan EnakPoint
-
-Ada dua jalur. Keduanya memakai logika perhitungan yang sama.
-
-### 4.1 Batas pembayaran
-
-EnakPoint maksimal yang bisa dipakai untuk satu order:
-
-```
-batas_rupiah = min(sisa_tagihan, total_order × max_payment_percent / 100 − yang_sudah_dibayar_EnakPoint)
-maks_point   = min(saldo_customer, floor(batas_rupiah / point_value))
-```
-
-Ditambah minimal `min_payment_points` per pembayaran. Nominal rupiah pembayaran selalu
-`points × point_value` dan **tidak pernah melebihi sisa tagihan**, jadi tidak ada
-kembalian. Sisa tagihan dibayar dengan method lain seperti biasa (split).
-
-### 4.2 POS — kode bayar dari aplikasi customer
-
-PIN **tidak pernah** diketik di perangkat kasir. Customer menyetujui di HP-nya sendiri:
-
-1. **Customer app:** `POST /api/v1/customer/wallet/payment-code` dengan `{ "pin": "482913" }`.
-
-   ```json
-   { "code": "482913", "qr_payload": "enakpoint:482913", "expires_at": "2026-09-30T05:02:00Z" }
-   ```
-
-   Tampilkan `code` sebagai angka dan `qr_payload` sebagai QR. Kode berlaku **2 menit**,
-   sekali pakai, dan hanya untuk customer itu. Membuat kode baru membatalkan kode lama.
-
-2. **POS:** tampilkan batas untuk tombol "pakai maksimal":
-
-   `GET /api/v1/orders/:id/point-payment/preview`
-
-   ```json
-   {
-     "order_id": "…",
-     "customer_id": "…",
-     "eligible": true,
-     "point_balance": 12500,
-     "point_value": 1,
-     "remaining_amount": 87500,
-     "min_payment_points": 1,
-     "max_payment_percent": 100,
-     "max_points": 12500,
-     "max_amount": 12500
-   }
-   ```
-
-   Bila `eligible: false`, `reason` menjelaskan kenapa (order walk-in, outlet tidak
-   menerima EnakPoint, saldo di bawah minimal, dst.).
-
-3. **POS:** bayar lewat endpoint pembayaran yang sudah ada, dengan payment method
-   bertipe `point`:
-
-   `POST /api/v1/payments` (header `X-Idempotency-Key` wajib seperti pembayaran lain)
-
-   ```json
-   {
-     "order_id": "…",
-     "payment_method_id": "<id method EnakPoint>",
-     "points": 12500,
-     "payment_code": "482913"
-   }
-   ```
-
-   `amount` tidak perlu dikirim; backend menghitungnya. `payment_code` boleh berupa
-   angka yang diketik kasir atau hasil scan QR apa adanya (`enakpoint:482913`).
-
-Response pembayaran membawa `points_used` dan `point_value` untuk struk, misalnya
-"EnakPoint: 12.500 (Rp 12.500)". Jika pembayaran ini melunasi order, order menjadi
-`completed`; jika belum, sisanya dibayar dengan method lain.
-
-Pembayaran ditolak (`304`, `cause` menjelaskan) bila: order tanpa customer atau
-customer walk-in, customer nonaktif, outlet tidak menerima EnakPoint, `points` di luar
-batas §4.1, kode salah/kedaluwarsa/sudah dipakai/milik customer lain, atau method
-EnakPoint dipakai sebagai split (bayar bagian EnakPoint sebagai pembayaran tersendiri,
-lalu split sisanya seperti biasa). Kode bayar dipakai habis begitu diterima, sebelum
-batas dicek ulang; bila pembayaran lalu ditolak (misalnya saldo berubah), minta
-customer membuat kode baru.
-
-**Method EnakPoint** dibuat otomatis untuk setiap organisasi dan tidak bisa dihapus
-atau diubah tipenya (namanya boleh diganti). Daftar payment method yang dikirim
-`?outlet_id=` tidak menampilkannya bila outlet itu tidak menerima EnakPoint.
-
-### 4.3 Customer app / self-order — bayar order sendiri
-
-`POST /api/v1/customer/orders/:id/pay-with-points`
-
-```json
-{ "points": 12500, "pin": "482913" }
-```
-
-Hanya untuk order milik customer yang login; order lain dijawab `404`. Response sama
-dengan response pembayaran di §4.2.
-
-### 4.4 Void dan refund
-
-- **Void order:** semua EnakPoint yang dipakai kembali ke customer sebagai EnakPoint.
-- **Refund pembayaran EnakPoint** (`POST /api/v1/payments/:id/refund` pada pembayaran
-  EnakPoint): yang kembali `floor(rupiah_direfund / point_value_saat_bayar)`. Perubahan
-  nilai EnakPoint setelah pembayaran tidak mengubah jumlah yang kembali; sisa di bawah
-  1 EnakPoint hangus.
-- **Refund order ke tunai / method lain** hanya boleh sebesar bagian yang dibayar
-  dengan method lain. Bagian EnakPoint harus direfund lewat pembayaran EnakPoint-nya
-  sendiri; mencoba lewat tunai dijawab `304`.
-- EnakPoint yang kembali mengikuti tanggal kedaluwarsa asalnya, tapi minimal 7 hari
-  sejak refund.
-- 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.
-
-### 4.5 Earning di layar order dan struk
-
-Response order membawa `points_earned` dan `coins_earned` (0 bila order tidak
-menghasilkan apa-apa). Earning dihitung dari `subtotal − discount − bagian yang
-dibayar EnakPoint`, sebelum pajak, dan diberikan saat order lunas.
-
----
-
-## 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
-
-`POST /api/v1/customer/spin` dengan `{ "spin_id": "<id game>" }`. Tanpa PIN.
-
-Setiap game memotong EnakCoin sebesar `metadata.coin_cost` game itu (default 1).
-Response:
-
-```json
-{
-  "game_play": { "id": "…", "game_id": "…", "coins_used": 1, "token_used": 1, "created_at": "…" },
-  "prize_won": { "id": "…", "name": "Voucher 10rb", … },
-  "coins_remaining": 7,
-  "tokens_remaining": 7
-}
-```
-
-EnakCoin kurang, game nonaktif, atau hadiah baru saja habis dijawab `304`; tidak ada
-EnakCoin yang terpotong. Baca `coins_used` dan `coins_remaining`; `token_used` dan
-`tokens_remaining` hanya salinan untuk versi aplikasi lama.
-
-Di dashboard, `metadata.coin_cost` diisi per game dengan bilangan bulat ≥ 1.
-
----
-
-## 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`) |
-| `GET /customer/tokens` | `GET /customer/wallet` (`coin_balance`) |
-| `total_points`, `total_tokens`, `points_history`, `tokens_history`, `last_updated` di `/customer/wallet` | `point_balance`, `coin_balance`, `recent_transactions` |
-| `token_used`, `tokens_remaining` di respons game | `coins_used`, `coins_remaining` |
-| `sort_by=token_used` di daftar game play | `sort_by=coins_used` |
-
-Beri tahu tim backend setelah aplikasi yang beredar tidak lagi memakai kolom kiri,
-supaya alias dan tabel lama (`customer_points`, `customer_tokens`) bisa dihapus.
-
----
-
-## 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_per_amount": 100, "earn_value": 1, "min_order_amount": 0, "max_per_order": null },
-  "coin": { "enabled": true, "earn_per_amount": 25000, "earn_value": 1, "min_order_amount": 0, "max_per_order": null },
-  "point_payment": { "accept_payment": true, "min_payment_points": 1, "max_payment_percent": 100 }
-}
-```
-
-Field yang tidak dikirim di `PUT` tetap memakai nilai sekarang. Response menambahkan
-`point_value` organisasi dan `point_cashback_percent`
-(`earn_value × point_value / earn_per_amount × 100`). **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 … }
-}
-```
-
-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,
-  exchange, atau refund sampai ke earning/adjustment/migrasi pertama. Contoh: dari
-  pembayaran 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**
-- [ ] Scan QR atau ketik kode bayar, jangan pernah meminta PIN customer di layar kasir.
-- [ ] Pakai `point-payment/preview` untuk tombol "pakai maksimal".
-- [ ] Cetak `points_used`, `points_earned`, dan `coins_earned` di struk.
-- [ ] Refund bagian EnakPoint lewat pembayaran EnakPoint-nya, bukan tunai.
-
-**Dashboard**
-- [ ] Tampilkan `point_cashback_percent`, `impact`, `expiry_preview`, dan
-      `expiry_activations` sebelum owner menyimpan setting.
-- [ ] Isi `metadata.coin_cost` untuk setiap game.