rikrdo/mercadodevida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
mercadodevida/work/artifacts/CLUB-003/documenter.md

1.1 KiB
Raw Permalink Blame History

CLUB-003 — Documentation notes

New endpoint

  • GET /club/resolve?memberCode=MDV-XXXXXXXX — resolves an active Club member by code. Returns { member, config } or 404.

POS sale integration

  • POST /pos/sales accepts optional clubMemberId: string (UUID of the Club member).
  • When the sale completes (state: 'COMPLETED'):
    • reads club_cashback_bps from store_settings
    • computes cashbackCents = round(totalCents * cashbackBps / 10_000)
    • inserts into club_transactions with idempotency_key = club-earn-{orderId}, type = 'earn'
  • Sale response includes clubEarnedCents and clubMemberCode.

Idempotency contract

  • Each completed sale generates exactly one ledger entry per member.
  • If the same sale is retried (same idempotency key on POST /pos/sales), the ledger entry is not duplicated (ON CONFLICT DO NOTHING).
  • Failed ledger writes do not block the sale.

Out of scope for CLUB-003

  • Club member lookup UI in the TPV terminal frontend (API ready; UI pending).
  • Cashback refund when items are returned (CLUB-004).
  • Redeem balance at POS.