# 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.