23 lines
1.1 KiB
Markdown
23 lines
1.1 KiB
Markdown
# 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.
|