Finanzas
App de finanzas personales mobile-first en MXN, instalable como PWA. Fases 1-6: Next.js + Supabase Auth + Cuentas + Transacciones + Presupuestos + Deudas + Metas de ahorro + Reportes + PWA/offline + auditoría de seguridad. Ver requerimientos-app-financiera.md para el alcance completo del proyecto.
Stack
- Next.js (App Router) + TypeScript + Tailwind CSS v4
- Supabase (Postgres, Auth, RLS)
- Recharts (gráficas, paleta validada con la skill dataviz — ver
src/lib/constants/chart-colors.ts)
- Vitest + Testing Library
Setup
npm install
cp .env.example .env.local
Completa .env.local con la URL y anon key de tu proyecto Supabase (Project Settings → API). Para el motor de recurrencias (Fase 8) hacen falta además dos variables server-only (nunca con prefijo NEXT_PUBLIC_): SUPABASE_SERVICE_ROLE_KEY (mismo dashboard, Settings → API → service_role — bypassea RLS, no lo compartas ni lo subas a git) y CRON_SECRET (una cadena aleatoria que tú inventas, para que /api/cron/generate-recurring no sea invocable públicamente). En Vercel, agrega ambas en Project Settings → Environment Variables para que el Cron Job funcione en producción.
Migraciones
Corre los archivos de supabase/migrations/ en orden (001 → 019) contra tu proyecto, ya sea con el SQL Editor del dashboard de Supabase o con la CLI de Supabase (supabase db push).
Desarrollo
npm run dev
Pruebas
Ver TESTING.md para la cobertura completa (mapeada contra los casos de prueba del doc de requerimientos) y la checklist manual.
npm run test
Para correr toda la suite de integración contra Supabase real de una sola vez (crea y limpia usuarios de prueba automáticamente):
npm run verify:all
También se puede correr cada verificación por separado. Para las reglas de negocio (saldo negativo, límite de crédito, atomicidad de transferencias), crea un usuario de prueba y corre:
NEXT_PUBLIC_SUPABASE_URL=... NEXT_PUBLIC_SUPABASE_ANON_KEY=... \
TEST_USER_EMAIL=... TEST_USER_PASSWORD=... \
node scripts/verify-transaction-rpc.mjs
Para verificar las reglas de presupuestos (constraint único por categoría/mes, cálculo de gastado vs. presupuestado, aislamiento entre meses):
NEXT_PUBLIC_SUPABASE_URL=... NEXT_PUBLIC_SUPABASE_ANON_KEY=... \
TEST_USER_EMAIL=... TEST_USER_PASSWORD=... \
node scripts/verify-budgets.mjs
Para verificar pagos de deuda (atomicidad cuenta+deuda, rechazo si excede el saldo, reversión al eliminar) y aportaciones a metas (atomicidad cuenta+meta):
NEXT_PUBLIC_SUPABASE_URL=... NEXT_PUBLIC_SUPABASE_ANON_KEY=... \
TEST_USER_EMAIL=... TEST_USER_PASSWORD=... \
node scripts/verify-debt-payment-rpc.mjs
node scripts/verify-goal-contribution-rpc.mjs
Para verificar la fórmula de patrimonio neto histórico usada en Reportes:
NEXT_PUBLIC_SUPABASE_URL=... NEXT_PUBLIC_SUPABASE_ANON_KEY=... \
TEST_USER_EMAIL=... TEST_USER_PASSWORD=... \
node scripts/verify-reports-data.mjs
PWA (íconos, manifest, service worker)
Los íconos se generan con PowerShell + System.Drawing (Windows only, sin dependencias npm):
pwsh ./scripts/generate-icons.ps1
El service worker (public/sw.js) solo se activa en producción (NODE_ENV=production), nunca en npm run dev, para no interferir con el hot-reload. Para probarlo localmente:
npm run build
npm run start
Y luego, con el navegador apuntando a http://localhost:3000, verificar en DevTools → Application → Service Workers que está activo, y que /manifest.webmanifest responde JSON válido. "Agregar a pantalla de inicio" en iPhone requiere HTTPS real (no funciona sobre http://localhost), así que la prueba final en un iPhone físico solo se puede hacer una vez desplegada la app (Vercel/Cloudflare Pages).
Auditoría de seguridad (aislamiento entre usuarios)
Con dos usuarios de prueba ya confirmados, verifica que ninguno pueda leer, insertar-referenciando, actualizar ni borrar datos del otro:
NEXT_PUBLIC_SUPABASE_URL=... NEXT_PUBLIC_SUPABASE_ANON_KEY=... \
USER_A_EMAIL=... USER_A_PASSWORD=... \
USER_B_EMAIL=... USER_B_PASSWORD=... \
node scripts/verify-cross-user-isolation.mjs
Motor de recurrencias (Fase 8)
Verifica los 3 casos del doc (Netflix mensual sin duplicarse, Strava anual sin generar en meses intermedios, recurrencia con recurring_end_date vencida) directo contra la función generate_recurring_occurrence — es security definer y solo la puede invocar el service role, así que este script no depende de un usuario de sesión, crea y borra el suyo propio:
npm run verify:recurring
Para probar la ruta del cron end-to-end en local (requiere CRON_SECRET en .env.local):
curl -H "Authorization: Bearer $CRON_SECRET" http://localhost:3000/api/cron/generate-recurring
Estado
Fase 1 completa: registro/login/recuperación de contraseña, CRUD de cuentas (con catálogo de bancos MX) y CRUD de transacciones (ingreso/gasto/transferencia, con catálogo de comercios MX, categorías, etiquetas y flag de recurrente), todo con la regla de "no saldo negativo" aplicada en la base de datos vía funciones RPC atómicas.
Fase 2 completa: presupuesto mensual por categoría con navegación de mes, comparativo presupuestado vs. real con barra de progreso, alertas visuales configurables (badge de estado ok/alerta/excedido) y widget de resumen en el Dashboard.
Fase 3 completa: CRUD de deudas (tarjeta/préstamo/persona) con registro de pagos atómico (RPC, descuenta cuenta y deuda a la vez), simulador de amortización, sugerencia visual de estrategia bola de nieve/avalancha; CRUD de metas de ahorro con aportaciones atómicas (RPC), barra de progreso y proyección de cumplimiento según ritmo actual.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
