feat(loyalty): EnakPoint & EnakCoin #32
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: apksel-dev/apskel-pos-backend#32
Reference in New Issue
Block a user
Menambahkan program loyalitas EnakPoint & EnakCoin sesuai
docs/prd-point-coin.md(fase 1–6 didocs/tasks-point-coin.md). Token lama diganti EnakCoin; EnakPoint bernilai rupiah dan bisa dipakai membayar order.Isi
WalletProcessorsebagai satu-satunya jalan mengubah saldo (lock wallet, idempotency key, lot per K9); migrasi saldo Point/Token lama (cmd/wallet-migrate); job rekonsiliasi; setting loyalitas bertipe dengan riwayat perubahan.onOrderPaid+ job backfill, reversal saat void/refund,points_earned/coins_earneddi order dan struk.GET /customer/wallet/expiring.customer_devices(PUT/DELETE /customer/devices) untuk transfer masuk, PIN terkunci, saldo hangus, dan pengingat.docs/.Migrasi
000090–000097, semuanya punyadown. Setelah deploy, jalankancmd/wallet-migratesekali untuk memindahkan saldo lama; aman dijalankan ulang.Perlu diperhatikan saat review
TEST_DATABASE_URL, termasuk lock bersamaan, transfer dua arah, dua instance job kedaluwarsa, dan semua migrasi. Mohon jalankanTEST_DATABASE_URL=… go test ./...di database yang sudah dimigrasi sebelum merge. Unit test lain lulus.customer_points/customer_tokens(dibacawallet-migrate) dan alias/customer/points,/customer/tokens,token_used,tokens_remainingsampai aplikasi berpindah.PUT /customer/devices; tanpa itu push tidak terkirim.go vetgagal karena struct tag rusak diinternal/contract/payment_method_contract.go:11. Itu sudah ada sejak 2025, bukan dari PR ini.Dokumentasi:
docs/integration-enakpoint.md,docs/api-enakpoint.md,docs/backoffice-enakpoint.md.🤖 Generated with Claude Code
Adds CalculateEarning (docs/prd-point-coin.md F1, Q1, Q10, PC-202), a pure function returning, per currency, the amount an order earns and the settings that produced it, plus the basis: basis = subtotal − discount − paid with EnakPoint (never negative) amount = 0 below min_order_amount, else floor(basis / earn_per_amount) × earn_value, capped by max_per_order Tax and anything added on top of the subtotal are not part of the basis, and the part paid with EnakPoint earns nothing. Money is handled in whole cents: in float64 some baskets divide to 4956.999… and a naive floor would lose a point, which a test reproduces. Metadata() gives the snapshot the EARN row will freeze. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Adds earning at payment time (docs/prd-point-coin.md F3, PC-203). An order becomes fully paid through UpdateOrder, CreatePayment and both kinds of split bill. All of them now go through one OrderProcessorImpl hook, onOrderPaid, called after the payment has committed; for CreatePayment that is after its transaction, not from updateOrderStatus inside it. The hook runs detached from the caller's transaction and from the request being cancelled, and it runs synchronously so the order response can show what was earned. EarningProcessor.EarnForOrder skips orders that are not paid, are void, have no customer, or whose customer is the walk-in customer or inactive. It computes the earning with CalculateEarning, subtracting any part paid with EnakPoint (none until phase 3), and credits each currency through the wallet engine as EARN with key earn:{order_id}:{currency} and the settings snapshot in metadata. A repeat, even concurrent, credits nothing more. OnOrderPaid never fails the payment: errors and panics are logged. EarningBackfillJob is the safety net: every 30 minutes it earns for orders paid in the last three days that have no EARN row. It only looks at outlets with earning switched on and pages by (updated_at, id), so orders that correctly earned nothing cannot starve the ones that were missed. Lots from earning never expire until the expiry model is decided (F12, note N4). Adds the point payment method type constant, not yet accepted as a payment method. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Adds paying with the EnakPoint method (docs/prd-point-coin.md F9, K7, PC-305). POST /payments with the EnakPoint method now takes points and the customer's payment code and goes through PointPaymentProcessor instead of the generic path, which would record a payment without taking any balance. After checking the order, its customer (not walk-in, active), the outlet (accepts EnakPoint, minimum) and the method, it redeems the code, then in one transaction locks the order row and the wallet, recomputes the F9 limits from fresh data, inserts the payment with points_used and the frozen point_value, writes the PAYMENT ledger row (key payment:{id}, the outlet, the cashier) and updates the order. The limits are min(balance, floor(min(remaining, total × max_payment_percent / 100 − paid with EnakPoint) / point_value)) in cents, so EnakPoint never pays more than what is left and gives no change. Unlike the generic CreatePayment, which always marks the order paid, an EnakPoint payment leaves it partial with the right remaining amount until it is settled, so the rest can be paid in cash. Settling it triggers earning, whose basis leaves out the EnakPoint part. Splitting with the EnakPoint method is refused. Refusals answer 400. The payment response carries points_used and point_value for the receipt. GET /orders/:id/point-payment/preview returns eligibility, balance, point value and the maximum for the use-maximum button. The payment and order repositories write outside transactions, so this path uses its own repository that joins it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Adds GET /customer/wallet/transfer/recipient?phone= and POST /customer/wallet/transfer (docs/prd-point-coin.md F5, Q4, Q16, PC-402). The recipient is found by phone number and must be an active customer of the same organization, not the walk-in customer and not the sender. A number of another organization answers 404 like an unknown one, so the check does not reveal who uses the app elsewhere. The recipient check returns the name and number masked ("Bu*** Sa***", "08**-****-1234"). The organization's transfer settings apply: transfers turned off, the minimum, the maximum per transaction and the daily limit per currency, which starts over at midnight WIB. Everything the request alone can get wrong is refused before the PIN, so it costs no attempt; the PIN then refuses a transfer held for 24 hours after a PIN reset. Both wallets are locked in customer_id order, so transfers in opposite directions cannot deadlock, and the daily limit is summed under the lock. TRANSFER_OUT takes from the sender's lots in K9 order and TRANSFER_IN gives the recipient lots with exactly the same expiries, pointing back at the sender's lots. The rows share a group, reference each other and name the other customer; descriptions carry only the masked name. The Idempotency-Key header is required. A retry is recognised under the lock before the daily limit, so it replays instead of counting twice; the same key towards another recipient is refused. The recipient is told by WhatsApp after the commit, as PIN locks are: NotificationService only reaches staff devices, there is no push channel to customers yet. A failure to send is logged, never undoes the transfer. Transfers must not be released before note N3 (legal) is closed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>The recipient of a transfer now gets a push through FCM instead of a WhatsApp message (docs/prd-point-coin.md F5). Customers had nowhere to keep FCM tokens: user_devices only holds staff devices. Migration 000096 adds customer_devices, and the customer app registers with PUT /customer/devices { device_id, fcm_token, platform, app_version } after login and whenever FCM refreshes the token, and unregisters with DELETE /customer/devices/:device_id on logout. A token belongs to one customer only: registering it takes it away from whoever had it on that phone before, so they stop getting this customer's notifications. The push goes to every device of the recipient after the commit, titled "EnakPoint masuk" or "EnakCoin masuk", with type WALLET_TRANSFER_IN, the TRANSFER_IN transaction id, the group id, the currency and the amount in its data so the app can open it. A retried transfer sends nothing again. It stays best effort: no device, FCM not configured or FCM failing is logged and never undoes the transfer. The app builds one FCM client and shares it between staff notifications and customer pushes. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Settles note N4 of docs/prd-point-coin.md: both expiry models are supported, chosen per currency by the owner, defaulting to one fixed date a year (PC-501, F12). New organization keys, per currency (loyalty.point.* / loyalty.coin.*): - expiry_mode: FIXED_DATE (default) or ROLLING. - expiry_fixed_dates: the days of the year balances expire on, as sorted MM-DD values ("12-31" by default, "06-30,12-31" for twice a year). 29 Feb is refused. - expiry_grace_months: 0 to 24, default 3. A balance lasts at least this long before a fixed date takes it. The existing period, unit and end_of_month keys now belong to ROLLING, and reminder_days to both. ComputeExpiry gives the expiry of a balance received at a time: the first fixed date on or after the day received plus the grace months, or the day received plus the period (to the end of that month when asked). Days are the customer's (WIB), a shorter month keeps to its last day, and a lot lasts to 23:59:59 of its day so the apps group it under that day. Nil when expiry is off. ActivationExpiry, RefundExpiry and EarlierExpiry hold the other decided rules and are used by PC-502. GET and PUT /marketing/loyalty-settings return expiry_preview: when a balance received now would expire, for the dashboard's "received today expires on ..." hint, also on a dry run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>Adds the expiry job (docs/prd-point-coin.md F12, PC-503). Every 15 minutes it lists the lots whose expiry has passed and that still hold something, the longest overdue first, 500 at a time, and expires each in its own transaction through WalletProcessor.ExpireLot: lock the wallet, read the lot again, and take what is left with an EXPIRE row pointing at the lot, keyed expire:{lot_id}. The description is frozen as "Kedaluwarsa: 130 EnakPoint dari Belanja #ORD-0098", using the amount read under the lock. Lots expire at the end of their day, so none stays past it for more than about a quarter of an hour. It is safe on several instances and across restarts, keeping no state in memory as OmsetMilestoneScheduler does. Selecting the lots FOR UPDATE SKIP LOCKED, as PC-503 suggested, would lock a lot before its wallet and deadlock against payments, which lock the wallet first; instead the listing takes no lock, and the wallet lock plus the idempotency key make a second instance find the lot empty or the key used and take nothing. A lot that fails is logged and retried on the next run without stopping the others. Each customer gets one FCM push per currency with the total that expired ("180 EnakPoint kamu sudah kedaluwarsa.", type WALLET_EXPIRED). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>