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

2.6 KiB
Raw Blame History

Implementer evidence — CLUB-003

Resumen

Implementé la integración del Club en el TPV: resolución de socio por código, acumulación de cashback en ledger idempotente y campos de respuesta en venta POS.

Qué se añadió

1) Endpoint de resolución de socio

  • GET /club/resolve?memberCode=MDV-XXXXXXXX en project/src/modules/club/api/club.routes.ts
  • Método resolveByCode en ClubService
  • Método findMemberByCode en PgClubRepository (solo socios activos)

2) Integración de cashback en venta POS

  • PosSaleInput ahora acepta clubMemberId?: string (domain type)
  • PosSaleResult ahora devuelve clubEarnedCents y clubMemberCode
  • CreatePosSaleUseCase:
    • Al completar una venta (orderState === 'COMPLETED'), si hay clubMemberId:
      • Consulta club_enabled y club_cashback_bps de store_settings
      • Calcula cashbackCents = round(totalCents * cashbackBps / 10_000)
      • Inserta transacción de ledger idempotente con idempotency_key = club-earn-${orderId} dentro de la misma transacción DB que la venta
      • Si la insercción falla, continúa sin bloquear la venta (fail-safe)
  • loadResult recupera el clubEarnedCents del ledger al recargar una venta por idempotency key
  • receive-rest-payment.ts devuelve clubEarnedCents: 0 (pagos adicionales no re-acumulan cashback)

3) API del TPV

  • El body de POST /pos/sales acepta clubMemberId con validación UUID
  • La respuesta de venta incluye clubEarnedCents y clubMemberCode

4) Tipos frontend

  • PosSaleResponse en apps/pos/src/types/checkout.ts incluye clubEarnedCents y clubMemberCode

Decisiones técnicas

  • El cashback se acumula solo cuando la venta pasa a COMPLETED, no en ventas PENDING.
  • Si la escritura de ledger falla, la venta sigue adelante (fail-safe).
  • El idempotency key del ledger incluye el orderId (club-earn-${orderId}), garantizando una única acumulación por venta.
  • El loadResult recupera el cashback del ledger para mantener consistencia en respuestas por idempotency.

Validación ejecutada

  • cd project && npm run typecheck ✅
  • cd project && npm run build ✅
  • cd project/apps/pos && npm run build ✅
  • ./scripts/verify.sh ✅
  • cd project && npx vitest run src/modules/pos/tests/payment-allocation.test.ts ✅
  • cd project && npx vitest run src/modules/club/tests/ ✅
  • git diff --check ✅

Riesgos / siguiente paso

  • CLUB-004 debe implementar el flujo de devolución TPV que revierte el cashback acumulado cuando se reintegran artículos.
  • El frontend TPV (interfaz de búsqueda de socio Club) queda pendiente de implementar en la UI del terminal; los campos del endpoint ya están listos.