feat(club-002): club PWA: join flow, digital card and installable shell

work/artifacts/CLUB-002/architect.md

@@ -0,0 +1,87 @@
+# 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`