chore(checkpoint): save club core backend and pending pos fixes

2026-08-26 17:58:45 +02:00
parent cf3c906ed2
commit 49dfd00406
44 changed files with 2241 additions and 219 deletions
--- a/work/artifacts/CLUB-001/architect.md
+++ b/work/artifacts/CLUB-001/architect.md
@@ -0,0 +1,158 @@
+# 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.
--- a/work/artifacts/CLUB-001/implementer.md
+++ b/work/artifacts/CLUB-001/implementer.md
@@ -0,0 +1,88 @@
+# 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.