💰 BethaSpend

Sistema de gestión de gastos personales desarrollado por Bethalabs. Incluye presupuestos mensuales, gastos recurrentes automatizados y análisis estadístico.

🚀 Características

• Registro de Gastos: Interfaz intuitiva para registrar gastos diarios con categorías y métodos de pago
• Gastos Recurrentes: Sistema automatizado que genera gastos periódicos (mensuales/semanales) mediante cron jobs
• Presupuestos Mensuales: Control detallado de presupuestos por categoría con seguimiento en tiempo real
• Estadísticas Detalladas: Análisis visual de gastos por categoría, período y tendencias
• Multi-Usuario: Autenticación segura con NextAuth.js y Supabase
• Filtros Avanzados: Búsqueda y agrupación por día, semana o mes
• Etiquetas en gastos: ver docs/EXPENSE_TAGS.md
• Compras en el exterior con impuesto: ver docs/FOREIGN_TAX.md
• Importación de movimientos bancarios desde el correo y sugerencias web: ver docs/WEB_EXPENSE_SUGGESTIONS.md
• PWA instalable con caché offline controlada: ver docs/PWA.md
• MCP para ChatGPT: ver docs/MCP.md

🛠️ Tecnologías

• Frontend: Next.js 16 (App Router), React 18, TypeScript, Tailwind CSS
• UI Components: shadcn/ui (Radix UI)
• Backend: Next.js API Routes
• Base de Datos: Supabase (PostgreSQL)
• Autenticación: NextAuth.js + Supabase Auth
• Automatización: Schedule diario en Dokploy
• Utilidades: date-fns, sonner

📦 Instalación

# Clonar el repositorio
git clone https://github.com/elrichi31/control-gastos.git
cd control-gastos

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env.local
# Completar .env.local (cada variable indica si es obligatoria u opcional)

# Ejecutar servidor de desarrollo
npm run dev

Abre http://localhost:3000 en tu navegador.

🗄️ Configuración de Base de Datos

1. Crea un proyecto en Supabase
2. Aplica en orden, por nombre, las migraciones de supabase/migrations/ en el SQL Editor
3. Cada tabla nueva debe activar RLS y revocar anon/authenticated (ver docs/CODE_REVIEW.md)

⚙️ Variables de Entorno

Todas están en .env.example, agrupadas por bloque (Supabase, NextAuth, Google, sesiones, cron, MCP, correo Yahoo, Jev) e indicando si son obligatorias. Las mínimas para levantar la app: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, NEXTAUTH_URL y NEXTAUTH_SECRET; CRON_SECRET para los cron.

El único cron de recurrentes requiere también SUPABASE_SERVICE_ROLE_KEY privada y aplicar la migración SQL en Supabase. Guardar una regla no genera un gasto inmediatamente. Ver modelo, compatibilidad y activación.

🤖 MCP para ChatGPT

Servidor autenticado para consultar y gestionar gastos manuales propios desde ChatGPT. Configuración OAuth, migración y guía de conexión en docs/MCP.md.

🤖 Cron Job (Dokploy)

Un Schedule diario de Dokploy (5 5 * * * UTC = 00:05 en Ecuador, shell sh) dentro del contenedor genera los gastos recurrentes vencidos:

wget -qO- --header="Authorization: Bearer $CRON_SECRET" http://127.0.0.1:3000/api/cron/process-recurring-expenses

Otro Schedule cada 30 min (*/30 * * * *, shell sh) trae los movimientos bancarios del correo de las últimas 2 semanas:

wget -qO- --header="Authorization: Bearer $CRON_SECRET" http://127.0.0.1:3000/api/cron/sync-email

La imagen es node:20-alpine: trae wget pero no curl. La última corrida de cada cron se ve en el sidebar (Automatizaciones).

📱 Estructura del Proyecto

src/
├── app/                      # App Router de Next.js
│   ├── api/                  # API Routes
│   ├── auth/                 # Páginas de autenticación
│   ├── detalle-gastos/       # Vista detallada de gastos
│   ├── estadisticas/         # Análisis y gráficos
│   ├── form/                 # Formulario de gastos
│   ├── gastos-recurrentes/   # Gestión de gastos recurrentes
│   └── presupuesto/          # Gestión de presupuestos
├── components/               # Componentes React
│   ├── ui/                   # shadcn/ui y piezas genéricas
│   ├── layout/               # Sidebar, TopBar, providers y tema
│   ├── gastos/               # Formulario, lista y edición de gastos
│   ├── gastos-recurrentes/   # Formulario, lista y modales de recurrentes
│   ├── dashboard/            # Widgets del dashboard
│   ├── detalle-gastos/       # Componentes de vista detallada
│   ├── presupuesto/          # Componentes de presupuestos
│   ├── stats/                # Componentes de estadísticas
│   ├── conexiones/           # Sesiones y conexiones MCP
│   └── landing/              # Página pública
├── hooks/                    # Custom React hooks
├── lib/                      # Utilidades y configuración
│   ├── auth/                 # Configuración de autenticación
│   ├── database/             # Cliente service-role de Supabase (solo servidor)
│   └── constants/            # Constantes globales
├── services/                 # Capa de servicios/API
└── types/                    # Definiciones de TypeScript

🎯 Flujo de Gastos Recurrentes

1. Usuario crea gasto recurrente con frecuencia (mensual/semanal)
2. Sistema genera instancia pendiente automáticamente
3. Cron diario procesa instancias cuya fecha programada llegó
4. Gasto real se crea en la tabla gasto con flag is_recurrent: true
5. Instancia se marca como generado
6. Usuario puede eliminar gasto individual o desactivar serie completa

🎨 Características de UI

• Diseño responsive (móvil y desktop)
• Tema claro con Tailwind CSS
• Componentes accesibles de Radix UI
• Notificaciones toast elegantes
• Modales de confirmación intuitivos
• Badges visuales para gastos recurrentes

📄 Licencia

Este proyecto es de código abierto bajo licencia MIT.

👨‍💻 Desarrollo

# Ejecutar en modo desarrollo
npm run dev

# Build de producción
npm run build

# Servidor de producción
npm run start

# Pruebas y tipos
npm test
npm run typecheck

# Linter
npm run lint

🚢 Despliegue en Vercel

1. Conecta tu repositorio de GitHub
2. Configura las variables de entorno
3. Despliega automáticamente

---

Desarrollado con ❤️ usando Next.js y Supabase