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