feat(loyalty): exchange EnakCoin into EnakPoint

Adds GET /customer/wallet/exchange/preview?coins= and
POST /customer/wallet/exchange (docs/prd-point-coin.md F4, K3, PC-401).

The customer exchanges a multiple of the organization's coin_amount and
gets (coins / coin_amount) x point_amount EnakPoint, approved by their PIN
(K8). A malformed amount is refused before the PIN is checked, so it costs
no attempt. In one transaction the wallet is locked, EXCHANGE_OUT takes the
EnakCoin in K9 order and EXCHANGE_IN adds the EnakPoint; the two rows share
a group, point at each other and both freeze the rate in their metadata.

The EnakPoint are split over the EnakCoin lots they came from, each part
keeping its lot's expiry and pointing back at it, so exchanging cannot
extend a balance's life. The split takes floor(coins so far x rate) per
lot, which adds up exactly because the total is a multiple of coin_amount.
EnakPoint have no validity of their own until the expiry model is decided
(N4), so the EnakCoin lot is for now the only bound.

The Idempotency-Key header (or X-Idempotency-Key) is required. A retry
with the same key is recognised under the wallet lock and replayed with
the ids and rate the first attempt froze, even if the rate has changed
since; the same key for another amount is refused.

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

internal/models/wallet_move.go

@@ -0,0 +1,44 @@
+package models
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+// WalletExchangePreview is GET /customer/wallet/exchange/preview
+// (docs/prd-point-coin.md F4): the rate, and what exchanging Coins would give.
+type WalletExchangePreview struct {
+	// The rate: CoinAmount EnakCoin exchange into PointAmount EnakPoint.
+	CoinAmount  int64 `json:"coin_amount"`
+	PointAmount int64 `json:"point_amount"`
+	CoinBalance int64 `json:"coin_balance"`
+	Coins       int64 `json:"coins"`
+	Points      int64 `json:"points"`
+	// Whether Coins can be exchanged now, and why not when it cannot.
+	Valid  bool   `json:"valid"`
+	Reason string `json:"reason,omitempty"`
+}
+
+// WalletMovedLot is part of what an exchange or a transfer delivered, with the
+// expiry it carried over from the lot it came from (K9).
+type WalletMovedLot struct {
+	Amount int64 `json:"amount"`
+	// Nil when it never expires.
+	ExpiresAt *time.Time `json:"expires_at"`
+}
+
+// WalletExchangeResult is POST /customer/wallet/exchange.
+type WalletExchangeResult struct {
+	GroupID     uuid.UUID `json:"group_id"`
+	Coins       int64     `json:"coins"`
+	Points      int64     `json:"points"`
+	CoinAmount  int64     `json:"coin_amount"`
+	PointAmount int64     `json:"point_amount"`
+	// The EnakPoint received, split by expiry.
+	Lots         []WalletMovedLot `json:"lots"`
+	CoinBalance  int64            `json:"coin_balance"`
+	PointBalance int64            `json:"point_balance"`
+	// True when this was a retry of an exchange already made; nothing moved again.
+	Replayed bool `json:"replayed"`
+}