88 lines
2.8 KiB
Markdown
88 lines
2.8 KiB
Markdown
# 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`
|