Arquitectura — CLUB-002 · PWA Club

Objetivo

Construir la primera experiencia frontend del Club sobre el backend ya entregado en CLUB-001:

alta/join del Club
tarjeta digital móvil
shell instalable tipo PWA

Análisis del frontend actual

La tienda usa Next App Router en project/frontend/src/app.
No existe manifiesto PWA ni rutas /club/* todavía.
Los flujos autenticados usan proxies Next.js (/api/auth/*) para preservar cookies same-origin.
CLUB-001 ya expone backend suficiente para esta fase:
- GET /club/config
- POST /club/join
- GET /club/me
- GET /club/movements

Diseño propuesto

1) Proxy Next dedicado para Club

Añadir project/frontend/src/app/api/club/[...path]/route.ts.

Motivo:

preservar la cookie mdv_club como same-origin
reenviar set-cookie del backend en POST /club/join
evitar que componentes cliente hablen directo con NEXT_PUBLIC_API_URL

2) Rutas frontend Club

Crear páginas:

/club → landing/resumen del Club
/club/join → alta anónima o acceso al card si ya existe identidad Club
/club/card → tarjeta digital con member code, saldo y últimos movimientos

3) Shell móvil instalable

Añadir:

app/manifest.ts
iconos PWA a partir del branding existente
metadatos PWA en app/layout.tsx (themeColor, appleWebApp, manifest)
CTA de instalación desde cliente (beforeinstallprompt) en la superficie Club

4) Estado de Club en cliente

No crear aún un provider global complejo. En CLUB-002 basta con fetch puntual desde páginas/componentes Club:

GET /api/club/config
POST /api/club/join
GET /api/club/me
GET /api/club/movements

Esto minimiza acoplamiento y deja abierta una futura extracción a ClubContext si la PWA crece.

5) Tarjeta digital

La card mostrará:

member code
saldo actual
estado del Club
últimos movimientos
superficie visual tipo credencial móvil

6) Código visual de identificación

CLUB-002 mostrará un identificador visual en la tarjeta usando datos ya emitidos por CLUB-001.

Nota de alcance:

CLUB-003 es la fase de integración TPV/identificación en caja.
Por tanto, CLUB-002 prioriza la UX de tarjeta digital e instalación móvil.
La semántica exacta de escaneo en TPV se cerrará en CLUB-003 para no fijar prematuramente un contrato visual incompatible con caja.

Alcance

Sí entra

proxy Next para Club
landing/join/card frontend
manifiesto e iconos PWA
CTA de instalación
movimientos recientes y saldo en tarjeta

No entra

earn/redeem en TPV
linking con usuario registrado
recovery codes
admin UI del Club
contrato final de lectura en caja

Validación prevista

cd project/frontend && npm run build
cd project && npm run build
cd project && npm run typecheck
./scripts/verify.sh

2.8 KiB Raw Blame History