# Implementer evidence — CLUB-001

## Resumen
Implementé la **Fase 1 — Core backend** del nuevo módulo **Club de Clientes**.

## Qué se creó

### 1) Nuevo módulo backend `club`
Archivos nuevos en `project/src/modules/club/`:
- `api/club.routes.ts`
- `application/club-service.ts`
- `domain/club.ts`
- `domain/errors.ts`
- `domain/ports.ts`
- `infrastructure/device-token.ts`
- `infrastructure/member-code.ts`
- `infrastructure/pg-club-repository.ts`
- `index.ts`
- `tests/token-and-code.test.ts`
- `tests/boundary.test.ts`

### 2) Migración core del Club
- Nueva migración: `project/migrations/066_club_core.js`
- Crea tablas:
  - `club_members`
  - `club_devices`
  - `club_transactions`
  - `club_recovery_codes`
  - `club_rewards`
  - `club_campaigns`
- Añade seeds en `store_settings` para:
  - `club_enabled`
  - `club_cashback_bps`
  - `club_allow_anonymous_members`
  - `club_allow_recovery_codes`
  - `club_minimum_redeem_cents`

### 3) Endpoints backend de Fase 1
- `GET /club/config`
- `POST /club/join`
- `GET /club/me`
- `GET /club/movements`
- `GET /admin/club/settings`
- `PATCH /admin/club/settings`

### 4) Comportamiento implementado
- Alta anónima de socio Club.
- Generación de `deviceToken` opaco.
- Persistencia solo del `device_token_hash`.
- Reutilización del socio actual si el dispositivo ya tenía token válido.
- `memberCode` corto formato `MDV-XXXXXXXX`.
- Ledger `club_transactions` como fuente de verdad.
- `current_balance_cents` como cache transaccional.
- Registro de transacciones idempotentes mediante `idempotencyKey`.
- Configuración Club reutilizando `store_settings`.

### 5) Wiring en la app
- Registré el módulo en `project/src/app/build-app.ts`.

## Tests añadidos
- `project/src/modules/club/tests/token-and-code.test.ts`
- `project/src/modules/club/tests/boundary.test.ts`
- `project/src/app/tests/club.itest.ts`

## Fixes necesarios para poder ejecutar itest reales
Las itest reales del proyecto estaban bloqueadas por migraciones previas mal definidas con `pgm.addColumn(...)`.
Corregí:
- `project/migrations/057_product_variant_weight_and_expiry.js`
- `project/migrations/058_identity_email_confirmation.js`

Esto no cambia la intención funcional de esas migraciones; corrige únicamente su forma para que node-pg-migrate pueda aplicarlas.

## Validación ejecutada
- `./scripts/verify.sh` ✅
- `cd project && npm run typecheck` ✅
- `cd project && npm run build` ✅
- `cd project && npx vitest run src/modules/club/tests/token-and-code.test.ts src/modules/club/tests/boundary.test.ts` ✅
- `cd project && TEST_DATABASE_URL=postgres://mdv:mdv_dev_only@localhost:5432/mercadodevida_test npx vitest run src/app/tests/club.itest.ts --no-file-parallelism` ✅
- `git diff --check` ✅

## Decisiones técnicas relevantes
- Reutilicé `store_settings` para configuración del Club en vez de crear otro subsistema.
- El token de dispositivo sigue el patrón de sesiones existente: token opaco en cliente, hash SHA-256 en BD.
- El módulo ya queda preparado para fases posteriores (PWA, TPV, recovery, linking, admin UI) sin introducirlas todavía.

## Deuda / siguiente paso
- Fase 2 debería construir la PWA `/club/*` consumiendo estos endpoints y mostrando la tarjeta digital.
- `npm run lint:boundaries` sigue fallando por violaciones **preexistentes y ajenas** en módulos `pos` y `security`; no introducidas por CLUB-001.