mercadodevida/work/artifacts/CLUB-001/architect.md

# Arquitectura — CLUB-001 · Fase 1 Core backend

## Análisis de arquitectura existente

### Superficies del proyecto
- **Backend API**: `project/src/app/build-app.ts` registra módulos Fastify desacoplados bajo `project/src/modules/*`.
- **Frontend tienda**: `project/frontend/` consume la API vía rutas proxy Next.js.
- **Admin panel**: `project/apps/admin/` usa endpoints backoffice/admin ya existentes.
- **TPV/POS**: `project/apps/pos/` usa backend POS y órdenes como fuente de ventas.

### Patrones que debemos reutilizar
- **Módulo aislado por carpeta**: `api/`, `application/`, `domain/`, `infrastructure/`, `index.ts`.
- **Rutas finas**: validación con `zod` + `parseJson`, errores con `AppError`, Swagger con `errorSchema`.
- **Persistencia PostgreSQL**: migraciones `project/migrations/*.js` y repositorios `Pg*Repository`.
- **Auth desacoplada por inyección**: módulos reciben `authenticate` desde `build-app.ts`; no importan internals de identity.
- **Configuración editable**: `store_settings` ya actúa como KV-store para ajustes globales del negocio.
- **Tests reales de integración**: `project/src/app/tests/*.itest.ts` recrean DB, aplican migraciones y prueban la app completa.

## Decisiones técnicas para Fase 1

### 1) Nuevo módulo `club`
Se crea `project/src/modules/club/` con registro de rutas propio desde `build-app.ts`.

### 2) Ledger como fuente de verdad
- `club_transactions` será el **source of truth**.
- `club_members.current_balance_cents` existirá solo como **cache/optimización**.
- Cada escritura de ledger actualizará ambos dentro de la misma transacción.
- El balance podrá reconstruirse con `SUM(balance_delta_cents)`.

### 3) Configuración reutilizando `store_settings`
No se crea un sistema nuevo de configuración.
Se añaden claves:
- `club_enabled`
- `club_cashback_bps`
- `club_allow_anonymous_members`
- `club_allow_recovery_codes`
- `club_minimum_redeem_cents`

Esto mantiene consistencia con la arquitectura actual y simplifica futura UI admin.

### 4) Dispositivo anónimo con token opaco hasheado
- El backend genera `device_token` opaco.
- Solo se persiste `device_token_hash` en `club_devices`.
- El raw token se devuelve al cliente una sola vez en `POST /club/join`.
- Las rutas de lectura de Club aceptarán el token mediante header/cookie para no acoplar la PWA todavía.

### 5) Modelo preparado para fases futuras
Aunque Fase 1 solo activa core backend, la migración deja base para próximas fases:
- `club_members`
- `club_devices`
- `club_transactions`
- `club_recovery_codes`
- `club_rewards`
- `club_campaigns`

### 6) Cashback configurable, no hardcoded
La lógica core leerá `club_cashback_bps` desde settings. El default inicial será **200 bps = 2%**.

## Alcance funcional de CLUB-001

### Sí entra en Fase 1
- Crear socio anónimo.
- Emitir token de dispositivo.
- Consultar tarjeta/resumen del socio por token.
- Consultar movimientos del ledger.
- Configuración backend del Club.
- Infraestructura de migraciones y tests.
- Helper backend para registrar transacciones idempotentes sobre ledger.

### No entra en Fase 1
- PWA visual `/club/*`.
- QR visual y endpoint TPV de identificación.
- Recovery codes funcionales.
- Vinculación a cuenta de usuario.
- Admin UI.
- Integración TPV completa de earn/redeem/refund.

## Esquema inicial propuesto

### `club_members`
- `id uuid pk`
- `user_id uuid null -> identity_users(id)`
- `member_code text unique`
- `status text` (`active|blocked|merged`)
- `tier_code text default 'base'`
- `current_balance_cents integer default 0`
- `created_at`, `updated_at`

### `club_devices`
- `id uuid pk`
- `member_id uuid fk -> club_members(id)`
- `device_token_hash text unique`
- `last_used_at timestamptz`
- `created_at timestamptz`
- `revoked_at timestamptz null`

### `club_transactions`
- `id uuid pk`
- `member_id uuid fk -> club_members(id)`
- `sale_id uuid null -> orders_orders(id)`
- `store_id uuid null -> pos_stores(id)`
- `type text` (`earn|redeem|refund|bonus|adjustment`)
- `amount_cents integer`
- `balance_delta_cents integer`
- `idempotency_key text unique null`
- `metadata jsonb not null default '{}'`
- `created_at`

### `club_recovery_codes`
- Tabla preparada para Fase 4.
- Guardará hash(es) del código, no plaintext.

### `club_rewards`, `club_campaigns`
- Tablas scaffold para evolución posterior sin activar motor complejo aún.

## Endpoints backend de Fase 1

### Públicos / cliente Club
- `GET /club/config`
  - Devuelve flags públicos del módulo.
- `POST /club/join`
  - Crea socio anónimo + device token.
- `GET /club/me`
  - Resuelve socio por device token.
- `GET /club/movements`
  - Lista movimientos del socio actual.

### Admin / configuración
- `GET /admin/club/settings`
- `PATCH /admin/club/settings`

### Aplicación interna
- Servicio backend para registrar ledger idempotente y recalcular balance.
- Se deja listo para ser usado por TPV en CLUB-003.

## Validaciones clave
- Rechazar `join` si `club_enabled=false` o `club_allow_anonymous_members=false`.
- No aceptar tokens sin hash coincidente o revocados.
- `member_code` único y corto, formato `MDV-XXXXXXXX`.
- `type` del ledger restringido por CHECK.
- `current_balance_cents` nunca por debajo de 0 en operaciones que no lo permitan.
- `idempotency_key` único para evitar dobles registros.

## Estrategia de tests
- **Unit tests** para helpers de token/member code/config parsing.
- **Boundary test** para evitar imports indebidos del módulo.
- **Integration test real PostgreSQL** para:
  - migraciones del Club
  - `POST /club/join`
  - `GET /club/me`
  - `GET /club/movements`
  - `GET/PATCH /admin/club/settings`
  - escritura idempotente de ledger

## Riesgos / deuda controlada
- La PWA aún no existe; por eso Fase 1 devolverá el `deviceToken` al cliente y además dejará la ruta preparada para header/cookie.
- El QR opaco persistente se implementará en la fase TPV/PWA, sin bloquear el core del ledger.
- Recovery codes se dejan modelados pero no activados todavía para evitar complejidad prematura.