feat(loyalty): earn EnakPoint and EnakCoin when an order is paid

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>
2026-09-30 10:40:05 +07:00
parent 5baed18b22
commit 78c0c11774
10 changed files with 959 additions and 2 deletions
@@ -0,0 +1,184 @@
+package processor
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"github.com/google/uuid"
+
+	"apskel-pos-be/internal/constants"
+	"apskel-pos-be/internal/entities"
+	"apskel-pos-be/internal/logger"
+	"apskel-pos-be/internal/models"
+	"apskel-pos-be/internal/repository"
+)
+
+// Why an order earned nothing.
+const (
+	EarningSkipNotPaid          = "NOT_PAID"
+	EarningSkipVoid             = "VOID"
+	EarningSkipNoCustomer       = "NO_CUSTOMER"
+	EarningSkipDefaultCustomer  = "DEFAULT_CUSTOMER"
+	EarningSkipInactiveCustomer = "INACTIVE_CUSTOMER"
+	EarningSkipNothingToEarn    = "NOTHING_TO_EARN"
+)
+
+// EarningOutcome is what earning did for one order.
+type EarningOutcome struct {
+	Points int64
+	Coins  int64
+	// Set when the order earned nothing, to say why.
+	Skipped string
+}
+
+type outletSettingsReader interface {
+	Outlet(ctx context.Context, outletID uuid.UUID) (*models.OutletLoyaltySettings, error)
+}
+
+// EarningProcessor credits EnakPoint and EnakCoin for paid orders
+// (docs/prd-point-coin.md F3).
+type EarningProcessor struct {
+	orders   repository.EarningRepository
+	settings outletSettingsReader
+	wallet   *WalletProcessor
+	tx       TxRunner
+}
+
+func NewEarningProcessor(orders repository.EarningRepository, settings outletSettingsReader, wallet *WalletProcessor, tx TxRunner) *EarningProcessor {
+	return &EarningProcessor{orders: orders, settings: settings, wallet: wallet, tx: tx}
+}
+
+// OnOrderPaid is called once an order has become fully paid and the payment has
+// committed. It never fails the caller: a failed earning is logged and picked up later
+// by EarnMissing, and the idempotency keys make that retry safe.
+func (p *EarningProcessor) OnOrderPaid(ctx context.Context, orderID uuid.UUID) {
+	defer func() {
+		if r := recover(); r != nil {
+			logger.NonContext.Error(fmt.Sprintf("Earning for order %s panicked; it will be retried", orderID), fmt.Errorf("%v", r))
+		}
+	}()
+	if _, err := p.EarnForOrder(ctx, orderID); err != nil {
+		logger.NonContext.Error(fmt.Sprintf("Earning for order %s failed; it will be retried", orderID), err)
+	}
+}
+
+// EarnForOrder credits what a paid order earns. Calling it again for the same order
+// credits nothing more.
+func (p *EarningProcessor) EarnForOrder(ctx context.Context, orderID uuid.UUID) (*EarningOutcome, error) {
+	order, err := p.orders.GetOrderForEarning(ctx, orderID)
+	if err != nil {
+		return nil, err
+	}
+	if skip := earningSkipReason(order); skip != "" {
+		return &EarningOutcome{Skipped: skip}, nil
+	}
+
+	settings, err := p.settings.Outlet(ctx, order.OutletID)
+	if err != nil {
+		return nil, err
+	}
+	pointPaid, err := p.orders.PointPaidAmount(ctx, orderID)
+	if err != nil {
+		return nil, err
+	}
+	result := CalculateEarning(&entities.Order{Subtotal: order.Subtotal, DiscountAmount: order.DiscountAmount}, pointPaid, *settings)
+	if result.Point.Amount == 0 && result.Coin.Amount == 0 {
+		return &EarningOutcome{Skipped: EarningSkipNothingToEarn}, nil
+	}
+
+	outcome := &EarningOutcome{}
+	err = p.tx.WithTransaction(ctx, func(ctx context.Context) error {
+		for _, c := range []struct {
+			currency string
+			line     EarningLine
+			total    *int64
+		}{
+			{constants.WalletCurrencyPoint, result.Point, &outcome.Points},
+			{constants.WalletCurrencyCoin, result.Coin, &outcome.Coins},
+		} {
+			if c.line.Amount == 0 {
+				continue
+			}
+			outletID := order.OutletID
+			res, err := p.wallet.Credit(ctx, WalletCreditInput{WalletEntry: WalletEntry{
+				CustomerID:     *order.CustomerID,
+				Currency:       c.currency,
+				Type:           constants.WalletTxTypeEarn,
+				Amount:         c.line.Amount,
+				ReferenceType:  constants.WalletRefTypeOrder,
+				ReferenceID:    order.ID,
+				OutletID:       &outletID,
+				Description:    earningDescription(order),
+				Metadata:       result.Metadata(c.line),
+				IdempotencyKey: fmt.Sprintf("earn:%s:%s", order.ID, c.currency),
+				// Lots never expire until the expiry model is decided (F12, note N4).
+			}})
+			if err != nil {
+				return fmt.Errorf("crediting %s: %w", c.currency, err)
+			}
+			*c.total = res.Transaction.Amount
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return outcome, nil
+}
+
+// EarnMissing is the safety net behind OnOrderPaid: it looks for orders paid since the
+// given time that should have earned and have no EARN row, and earns for them. It
+// returns how many orders it looked at and how many now earned. One order failing does
+// not stop the others.
+func (p *EarningProcessor) EarnMissing(ctx context.Context, since time.Time, maxOrders int) (checked, earned int, err error) {
+	const page = 200
+	var after *repository.EarningCursor
+	for checked < maxOrders {
+		batch, err := p.orders.ListPaidOrdersWithoutEarning(ctx, since, after, page)
+		if err != nil {
+			return checked, earned, err
+		}
+		if len(batch) == 0 {
+			break
+		}
+		for _, candidate := range batch {
+			checked++
+			outcome, err := p.EarnForOrder(ctx, candidate.ID)
+			if err != nil {
+				logger.NonContext.Error(fmt.Sprintf("Earning retry for order %s failed", candidate.ID), err)
+				continue
+			}
+			if outcome.Skipped == "" {
+				earned++
+			}
+		}
+		last := batch[len(batch)-1]
+		after = &last
+	}
+	return checked, earned, nil
+}
+
+func earningSkipReason(order *repository.EarningOrder) string {
+	switch {
+	case order.PaymentStatus != string(entities.PaymentStatusCompleted):
+		return EarningSkipNotPaid
+	case order.IsVoid:
+		return EarningSkipVoid
+	case order.CustomerID == nil || order.CustomerIsDefault == nil:
+		return EarningSkipNoCustomer
+	case *order.CustomerIsDefault:
+		return EarningSkipDefaultCustomer
+	case order.CustomerIsActive == nil || !*order.CustomerIsActive:
+		return EarningSkipInactiveCustomer
+	}
+	return ""
+}
+
+func earningDescription(order *repository.EarningOrder) string {
+	description := "Belanja #" + order.OrderNumber
+	if order.OutletName != "" {
+		description += " di " + order.OutletName
+	}
+	return truncateRunes(description, walletDescriptionLimit)
+}