[FEATURE] Loyalty Points API — Balance, history, redemption, and tier management

[gelluisaac]

Description

Implement the backend for the loyalty points system that powers the
LoyaltyDashboard in the web frontend.

Endpoints

• GET /api/v1/loyalty/{account_id}/summary — Current tier, points balance, next tier info
• GET /api/v1/loyalty/{account_id}/history?page=1&page_size=20 — Points earning history
• POST /api/v1/loyalty/{account_id}/redeem — Redeem points
  • Input: {"points": 500, "reward_id": "reward_xyz"}
  • Validates: balance check, minimum redemption, one-per-day limits
• GET /api/v1/loyalty/tiers — List all loyalty tiers with thresholds and multipliers
• GET /api/v1/loyalty/{account_id}/referral — Referral link and stats

Implementation Details

• Atomic database transactions for point redemption
• Tier recalculation after any points change
• Referral tracking (unique referral codes, bonus on signup)

Acceptance Criteria

• Summary endpoint returns data matching LoyaltySummary type
• Redemption fails with 400 if insufficient points
• History returns paginated results sorted by date descending
• Tier upgrade/downgrade is automatically recalculated

Labels

enhancement, api, loyalty