ADR-0003 — Ledger imutável de pepitas

Status: Aceito — 2026-08-11

Contexto

Pepitas (pontos de fidelidade) são um passivo: cada ponto emitido é uma dívida da atlética com o sócio. Calcular saldo "na mão" (um campo editável) é fonte clássica de bugs — pontos duplicados, sumidos ou divergentes entre telas.

Decisão

O saldo é sempre a soma de um livro-razão imutável (loyalty_transactions, append-only). Nunca há UPDATE/DELETE de transação — correção é uma nova transação (adjust/reversal). O profiles.points_balance é apenas um cache reconciliável, protegido por trigger contra escrita via cliente. O crédito por compra (earn_points) é idempotente por pedido, para o webhook poder reprocessar sem duplicar.

Consequências

Positivas

• Auditabilidade total (cada centavo de pepita tem origem).
• Impossível "perder" ou "duplicar" saldo por concorrência do webhook.
• Estorno de compra reverte pontos de forma rastreável.

Negativas / trade-offs

• Saldo é derivado — leituras usam o cache; reconciliação exige somar o ledger.
• Toda mudança de pontos precisa passar por uma função de servidor (earn_points, adjust_points, redeem_reward, reverse_purchase_points).

Quando revisitar

Se o ledger crescer a ponto de a reconciliação ficar cara, considerar snapshots periódicos de saldo (mantendo o ledger como fonte da verdade).