feat(loyalty): remind customers before balances expire

Adds what the customer sees of expiry (docs/prd-point-coin.md F6, F12,
PC-504).

GET /customer/wallet/expiring lists everything that will expire, per
currency and day, soonest first. GET /customer/wallet already had the
nearest expiry per currency.

The expiry job now also sends reminders, with the settings of note N4 as
decided: once, reminder_days before (7 by default, 0 for none), per
currency. A customer gets one FCM push per currency and expiry day,
however many lots make it up: "150 EnakPoint akan kedaluwarsa pada 31 Okt
2026. Pakai sebelum hangus.", with type WALLET_EXPIRING, the currency,
amount and expiry_date in its data. Reminders cover whatever falls within
the window, so a run that was missed catches up rather than skipping a day.

Migration 000097 adds wallet_expiry_reminders, one row per customer,
currency and expiry day. The row is written before the push is sent, so
several instances of the job or a restart never remind twice; a push that
then fails is logged and not retried. Lots that expire later on the same
day as an earlier reminder are not reminded of again.

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

internal/service/customer_points_service.go

@@ -13,6 +13,7 @@ type CustomerPointsService interface {
 	GetCustomerTokens(ctx context.Context, customerID string) (*models.GetCustomerTokensResponse, error)
 	GetCustomerWallet(ctx context.Context, customerID string) (*models.GetCustomerWalletResponse, error)
 	GetCustomerWalletTransactions(ctx context.Context, customerID string, query models.ListCustomerWalletTransactionsQuery) (*models.PaginatedResponse[models.CustomerWalletTransaction], error)
+	GetCustomerWalletExpiring(ctx context.Context, customerID string) (*models.CustomerWalletExpiringList, error)
 	GetCustomerGames(ctx context.Context) (*models.GetCustomerGamesResponse, error)
 	GetFerrisWheelGame(ctx context.Context) (*models.GetFerrisWheelGameResponse, error)
 }
@@ -90,3 +91,10 @@ func (s *customerPointsService) GetCustomerWalletTransactions(ctx context.Contex
 	}
 	return s.customerPointsProcessor.GetCustomerWalletTransactionsAPI(ctx, customerID, query)
 }
+
+func (s *customerPointsService) GetCustomerWalletExpiring(ctx context.Context, customerID string) (*models.CustomerWalletExpiringList, error) {
+	if customerID == "" {
+		return nil, fmt.Errorf("customer ID is required")
+	}
+	return s.customerPointsProcessor.GetCustomerWalletExpiringAPI(ctx, customerID)
+}

internal/service/wallet_expiry_job.go

@@ -12,21 +12,23 @@ import (
 // lot from staying past its expiry for more than about that long (PC-503).
 const defaultWalletExpiryInterval = 15 * time.Minute
 
-type dueExpirer interface {
+type walletExpiryWork interface {
 	ExpireDue(ctx context.Context) (int, error)
+	SendReminders(ctx context.Context) (int, error)
 }
 
-// WalletExpiryJob expires the balances whose time is up (docs/prd-point-coin.md F12).
+// WalletExpiryJob expires the balances whose time is up and reminds customers of what
+// is about to (docs/prd-point-coin.md F12, PC-503, PC-504).
 // Unlike OmsetMilestoneScheduler it keeps no state in memory: several instances can
 // run it at once, and a restart repeats nothing, because every lot is expired under
 // its wallet's lock with an idempotency key.
 type WalletExpiryJob struct {
-	expirer  dueExpirer
+	expirer  walletExpiryWork
 	stopCh   chan struct{}
 	stopOnce sync.Once
 }
 
-func NewWalletExpiryJob(expirer dueExpirer) *WalletExpiryJob {
+func NewWalletExpiryJob(expirer walletExpiryWork) *WalletExpiryJob {
 	return &WalletExpiryJob{expirer: expirer, stopCh: make(chan struct{})}
 }
 
@@ -54,7 +56,8 @@ func (j *WalletExpiryJob) Stop() {
 	j.stopOnce.Do(func() { close(j.stopCh) })
 }
 
-// RunOnce expires what is due and returns how many lots it expired.
+// RunOnce expires what is due, sends the reminders that are due, and returns how many
+// lots it expired.
 func (j *WalletExpiryJob) RunOnce(ctx context.Context) int {
 	expired, err := j.expirer.ExpireDue(ctx)
 	if err != nil {
@@ -63,5 +66,12 @@ func (j *WalletExpiryJob) RunOnce(ctx context.Context) int {
 	if expired > 0 {
 		logger.NonContext.Infof("Wallet expiry expired %d lots", expired)
 	}
+	reminded, err := j.expirer.SendReminders(ctx)
+	if err != nil {
+		logger.NonContext.Error("Wallet expiry reminders failed to run", err)
+	}
+	if reminded > 0 {
+		logger.NonContext.Infof("Wallet expiry sent %d reminders", reminded)
+	}
 	return expired
 }