finanzas-py

Aplicación de gestión financiera familiar: ingresos, gastos, plantillas mensuales, control del fondo mutuo y previsiones a 12 meses.

Estado del proyecto

Etapa 1 — completada: infraestructura base.

• Next.js 14 + TypeScript + Tailwind
• Autenticación con Google vía Supabase, con soporte para vincular un segundo correo Gmail a la misma cuenta familiar (linkIdentity)
• Schema completo de base de datos con Row Level Security (supabase/schema.sql), en esquema dedicado finanzas_py para convivir con otras apps del mismo proyecto Supabase
• Configuración: métodos de pago, categorías, destinatarios de Telegram
• Endpoint de cron protegido por secreto, listo para recibir la llamada diaria de cron-job.org (lógica de negocio completa se agrega en Etapa 5)

Etapa 2 — completada: plantillas y aplicación mensual.

• /plantillas: alta, edición (día/monto/método/categoría) y activación de plantillas de gastos e ingresos mensuales
• /mes-actual: respeta el ciclo de facturación 27–26; botón para generar los movimientos del período vigente a partir de las plantillas activas (sin duplicar si ya existen)
• Edición de día/monto por movimiento del mes sin afectar la plantilla
• Estados de gasto: pendiente → rescatado → pagado (con reversa)
• Estados de ingreso: pendiente → confirmado (con reversa)
• Al marcar un gasto como "pagado" o un ingreso como "confirmado", se genera automáticamente el movimiento correspondiente en el libro mayor del fondo (fund_movements); si se revierte el estado, el movimiento se elimina para mantener el saldo consistente
• Fix de autenticación: se agregó middleware.ts, que obliga a iniciar sesión para cualquier página que no sea /login, y redirige al dashboard si ya estás logueado y entrás a /login. También se agregó el botón de "Cerrar sesión" (con el email de la cuenta activa) en el sidebar, y se separó el layout para que /login no muestre el menú lateral.
• Fix de creación de cuenta: la primera cuenta familiar y el vínculo de correos adicionales ahora se crean con funciones de base de datos SECURITY DEFINER (create_account_for_user, link_email_to_my_account) en vez de inserts directos, evitando un problema de RLS+RETURNING en la primera fila de un usuario nuevo.

Etapa 3 — completada: extras y control de saldo del fondo.

• /extras: alta de gastos e ingresos puntuales (con fecha de vencimiento/aplicación, no plantilla), mismos estados y misma lógica de libro mayor que los movimientos regulares
• /fondo: carga única de saldo inicial; registro del saldo real informado por el usuario con cálculo automático del interés generado (diferencia contra el saldo calculado por el sistema); historial de chequeos de saldo; libro mayor de los últimos movimientos del fondo
• Las acciones de edición/estado de movimientos (updateExpenseEntry, cambiarEstadoGasto, etc.) se centralizaron en src/lib/actions/entries.ts, compartidas entre /mes-actual y /extras
• Fix de alineación de columnas en la tabla de plantillas de gastos (se pasó de una tabla HTML con colSpan a un grid CSS por fila)
• Fix de fondo: el egreso del fondo ahora se registra en el momento del "rescate" (que es cuando la plata realmente sale del fondo mutuo), no al marcar "pagado" — antes solo se registraba al pagar, lo cual no reflejaba el saldo real del fondo. Una vez rescatado, el monto queda bloqueado para edición.

Etapa 4 — completada: dashboard, previsiones y extracto.

• / (Dashboard): saldo actual del fondo, gráfico de ingresos vs. egresos de los últimos 6 períodos, y tabla de próximos vencimientos del período vigente
• /previsiones: proyección de saldo a 12 períodos, asumiendo que las plantillas activas se repiten; arranca del saldo real ajustado por lo pendiente del período actual; alerta si el saldo proyectado se vuelve negativo, con la fila resaltada en rojo (igual que el Excel anterior); gráfico de evolución
• /extracto: descarga en CSV de los movimientos confirmados del fondo, filtrado por rango de fechas

Nota de diseño: a diferencia del Excel anterior, las plantillas de este sistema no tienen banderas mes a mes (como las columnas Ene–Dic para "Cuota Rafa"/"Cuota Benja" aplicando solo Feb–Nov). Por ahora todas las plantillas activas se proyectan como recurrentes en todos los períodos. Si hace falta ese nivel de detalle estacional, se puede agregar como mejora — avisame si lo querés para la próxima etapa.

Ajustes post-Etapa 4:

• Menú simplificado: Métodos de pago, Categorías y Telegram ahora viven bajo un solo ítem "Configuración" (/configuracion, con pestañas internas). El sidebar bajó de 10 a 8 ítems.
• Auto-generación en Mes Actual: al entrar a /mes-actual, si el período vigente todavía no tiene movimientos generados desde las plantillas, se crean solos (mismo mecanismo idempotente que el botón manual, que sigue disponible por si se agrega una plantilla nueva después).
• Filtros y totales en Mes Actual y Extras: ambas pantallas ahora tienen filtro por nombre, estado y rango de fechas/días, con el total filtrado mostrado arriba de cada tabla.
• Gráfico de categorías en el Dashboard: torta con la distribución de gastos del período vigente por categoría.
• Extracto renombrado a Movimientos (/movimientos): vista unificada de TODOS los gastos e ingresos de la cuenta (regulares y extra), con filtros por nombre/tipo/origen/estado/fecha, totales, y descarga en Excel (antes era CSV) reflejando los mismos filtros aplicados.

Ajustes adicionales:

• Movimientos ahora muestra solo confirmados: gastos pagados e ingresos confirmados únicamente (antes mostraba todo, incluyendo pendientes). Se sacó el filtro de "Estado" de la pantalla porque ya no aporta (todo lo que aparece está confirmado por definición).
• Previsiones ahora suma extras futuros: si cargás un gasto o ingreso extra en /extras con una fecha futura, se va a sumar automáticamente al período que le corresponde en la proyección de 12 meses (se marca con una etiqueta "+ extra" en la tabla). Esto requirió corregir un bug: el campo periodo de un extra se calculaba con la fecha de HOY en vez de con la fecha de vencimiento/aplicación elegida, por lo que un extra futuro terminaba mal ubicado.
• Eliminar en Mes Actual: los gastos/ingresos generados desde plantillas ahora se pueden borrar individualmente (solo si están en estado "pendiente" — si ya está rescatado/pagado/confirmado hay que revertir primero). Borrar un movimiento del mes nunca toca la plantilla de origen, y editar/desactivar una plantilla nunca afecta movimientos ya generados o confirmados — son filas independientes por diseño, y la base de datos lo refuerza a nivel estructural.
• Saldo inicial editable: ahora se puede corregir el monto/fecha del saldo inicial del fondo después de cargado (antes era de una sola vez, sin vuelta atrás). Al editarlo, el movimiento correspondiente en el libro mayor (fund_movements) se actualiza junto con él, para que el saldo del fondo siga siendo consistente.
• Orden en Mes Actual y Plantillas: los gastos ahora se ordenan por día (respetando el ciclo 27→26, no el orden numérico 1-31), después por método de pago, y después por nombre. Los ingresos se ordenan por día y nombre (no tienen método de pago).
• Buscador en vivo en Plantillas: las tablas de gastos e ingresos mensuales ahora filtran mientras se escribe, sin recargar la página (se extrajo la lógica a componentes cliente GastosTemplateTable e IngresosTemplateTable).
• Menú reordenado: Dashboard, Mes actual, Extras, Fondo mutuo, Movimientos, Plantillas, Previsiones, Configuración.

Reorganización mayor (post-Etapa 4, ronda 2):

• Buscador en vivo en Mes Actual: igual que en Plantillas, ahora las tablas de gastos e ingresos del período filtran por nombre al instante. Los filtros de estado y rango de día siguen siendo por botón (consultan la base directamente).
• Pendientes de meses anteriores visibles en Mes Actual: si arrancó un período nuevo y quedó algo sin resolver del anterior (por ejemplo, un gasto que nunca se rescató), ahora aparece en una sección aparte arriba de todo, con la misma posibilidad de editar/cambiar estado/eliminar — no hace falta ninguna pantalla adicional para encontrarlo.
• Fondo mutuo y Movimientos se fusionaron: /movimientos ya no existe como pantalla separada; todo su contenido (filtros, totales, descarga Excel) ahora vive dentro de /fondo, debajo del saldo actual y del registro de saldo del fondo. Además, la lista de movimientos ahora también incluye los intereses y el saldo inicial (antes esos solo se veían en la sección vieja de "últimos movimientos" del fondo, separados de gastos/ingresos).
• Saldo inicial trasladado a Configuración: la carga/edición del saldo inicial del fondo ahora es una pestaña más dentro de Configuración, no una sección de la pantalla de Fondo.
• Plantillas trasladado a Configuración: ya no es un ítem del menú principal — ahora es la primera pestaña dentro de Configuración (/configuracion/plantillas).
• Menú final: Dashboard, Mes actual, Extras, Fondo mutuo, Previsiones, Configuración (con pestañas: Plantillas, Métodos de pago, Categorías, Saldo inicial, Telegram).

Etapa 5 — completada: notificaciones diarias por Telegram.

• src/lib/avisos.ts arma el mensaje: gastos que vencen hoy, atrasados sin rescatar, total a rescatar antes del mediodía y saldo del fondo. Calcula la fecha real de cada gasto (los extras la tienen explícita; los regulares se derivan del período 27–26 y el día).
• GET /api/cron/notificar-vencimientos recorre las cuentas con destinatarios activos y envía. Autenticación por Authorization: Bearer <CRON_SECRET> o ?token=<CRON_SECRET>.
• Si no hay vencimientos ni atrasados, no manda nada: un aviso diario que llega siempre se vuelve ruido que se ignora.
• Un destinatario que falle (por ejemplo, alguien que bloqueó el bot) no corta el envío a los demás; el resultado detallado vuelve en la respuesta del endpoint.
• Botón "Enviar aviso de prueba" en Configuración → Telegram, para verificar token y chat_id sin esperar al horario del cron.

Alcance original completo. Todos los requisitos funcionales del pedido inicial están implementados.

Puesta en marcha

1. Supabase

Este proyecto está pensado para compartir un proyecto de Supabase existente (por ejemplo vacamanager o irp-py) sin afectar esas apps: todas las tablas de finanzas-py viven en su propio esquema de Postgres, finanzas_py, separado de public. También podés usar un proyecto nuevo si preferís; el esquema dedicado funciona igual en ambos casos.

1. Elegí el proyecto de Supabase a usar (existente o nuevo).
2. En el SQL Editor, ejecutar el contenido de supabase/schema.sql. Esto crea el esquema finanzas_py y todas las tablas ahí adentro — no toca nada de public ni de otros esquemas.
3. Paso obligatorio y fácil de olvidar: ir a Project Settings > API > "Exposed schemas" y agregar finanzas_py a la lista (sin sacar public, que puede estar en uso por las otras apps). Sin este paso, el cliente de Supabase no puede leer ni escribir estas tablas.
4. En Authentication > Providers, habilitar Google y cargar el Client ID / Secret de Google Cloud (si ya está habilitado por otra app del mismo proyecto, no hay que volver a configurarlo).
5. En Authentication > URL Configuration, agregar como Redirect URL: https://<tu-dominio>.vercel.app/api/auth/callback (agregarla a la lista existente, no reemplaza las de las otras apps).

Nota sobre reutilizar el proyecto: la tabla auth.users de Supabase es compartida por todas las apps del mismo proyecto (es la única parte no aislada por esquema). Esto no genera conflicto: si te logueás con el mismo Gmail que usás en vacamanager o irp-py, simplemente ya existe ese usuario en auth.users, y finanzas-py de todos modos solo ve y escribe filas de finanzas_py.account_users — sus propios datos, sin mezclarse con las otras apps.

2. Variables de entorno

Copiar .env.example a .env.local y completar con los valores de tu proyecto de Supabase y tu bot de Telegram.

3. Instalación local

npm install
npm run dev

4. Deploy en Vercel

1. Subir este repositorio a GitHub.
2. Importar el repo en Vercel.
3. Cargar las mismas variables de entorno del .env.local en la configuración del proyecto en Vercel.
4. Deploy.

5. Cron job (cron-job.org)

1. Crear una tarea nueva apuntando a: https://<tu-dominio>.vercel.app/api/cron/notificar-vencimientos
2. Agregar el header Authorization: Bearer <CRON_SECRET> (el mismo valor que pusiste en la variable de entorno CRON_SECRET).
3. Programar el horario deseado (ej. todos los días a las 8:00).

6. Vincular un segundo correo Gmail a la misma cuenta

Una vez logueado con el primer correo, desde Configuración (se habilita en Etapa 2) se puede invocar linkIdentity para sumar el segundo Gmail a la misma cuenta familiar, sin crear una cuenta separada.

---

Optimizaciones de performance (agosto 2026)

PASO OBLIGATORIO antes de desplegar esta versión

Ejecutar en el SQL Editor de Supabase:

supabase/optimizaciones_performance.sql

Crea dos tablas nuevas (entry_omisiones, period_generations) y varios índices. Es idempotente. Sin este script la app sigue funcionando, pero el borrado de movimientos regulares vuelve a fallar (reaparecen) y no hay ganancia de velocidad en /mes-actual.

Qué se corrigió

Bug de eliminación. /mes-actual regenera los movimientos desde las plantillas en cada render. Al borrar un gasto regular, el render inmediatamente posterior lo volvía a crear: parecía que el botón "Eliminar" no hacía nada. Ahora, al borrar un movimiento que vino de una plantilla, se anota la omisión en entry_omisiones y esa plantilla ya no se regenera para ese período. Si el borrado fue sin querer, aparece un botón "Restaurar movimientos eliminados" al pie de la página.

Lentitud al cambiar de estado. Tres frentes:

1. Feedback inmediato: los botones Rescatar / Pagar / Revertir / Eliminar ahora actualizan la fila en el acto y muestran "Guardando…", en vez de dejar la pantalla congelada hasta que vuelve la respuesta del servidor.
2. Menos viajes a la base: un cambio de estado pasó de 4 consultas secuenciales a 2 (el UPDATE devuelve la fila con .select() y la búsqueda del movimiento del fondo va en paralelo).
3. Menos trabajo por render: la generación mensual se saltea entera si el período ya está marcado como generado — de 6 consultas a 1 liviana en cada visita a /mes-actual. La autenticación se memoiza por request en vez de consultarse 2-3 veces.

---

Método/categoría de plantillas ahora se propagan a los gastos generados

PASO OBLIGATORIO antes de desplegar esta versión

Ejecutar en el SQL Editor de Supabase:

supabase/sincronizar_metodo_categoria_gastos.sql

Sincroniza, de una sola vez, el método de pago y la categoría de todos los gastos ya generados con los de su plantilla actual. Es idempotente. Sin este script, los gastos generados antes de este cambio van a seguir mostrando el método/categoría viejo hasta que se edite la plantilla de nuevo.

Qué se corrigió

A diferencia del monto (que tiene vigencias y queda "congelado" en la fecha de cada movimiento), método de pago y categoría son solo datos de clasificación. Antes, cambiar cualquiera de los dos en una plantilla (Configuración → Plantillas) no se reflejaba en los gastos ya generados desde ella — ni los históricos ni los del mes actual, que seguían mostrando el valor con el que se habían generado. Ahora, al editar una plantilla, el cambio se propaga automáticamente a todos los gastos generados desde ella, sin importar su estado.

---

Descuentos de salario (/salario)

PASO OBLIGATORIO antes de desplegar esta versión

Ejecutar en el SQL Editor de Supabase:

supabase/descuentos_salario.sql

Crea tres tablas nuevas en finanzas_py (salary_sources, salary_deductions, salary_deduction_payments) con RLS y el patrón de auth_account_ids(). Es idempotente. Sin este script la pantalla /salario aparece vacía y no permite guardar nada, pero el resto de la app (y el aviso diario) sigue funcionando igual.

Qué es

Registro y recordatorio de lo que se paga con el salario antes de transferir al fondo mutuo: cuotas de préstamos, otros descuentos y la propia transferencia al fondo. Es un módulo aparte: no escribe ni lee fund_movements, income_entries ni expense_entries, así que no cambia el saldo del fondo, las previsiones, el extracto mensual ni los rescates.

Reglas

• Fuentes de salario: nombre, titular (solo etiqueta: los dos usuarios de la cuenta ven y editan todo), día de cobro, monto bruto, activo, orden.
• Conceptos por salario: tipo prestamo, transferencia_fondo u otro, monto de la cuota y, para préstamos, cuotas totales (opcional) y cuotas ya pagadas antes de empezar a usar el módulo.
• Período: ciclo 27→26 de src/lib/period.ts. La fecha del recordatorio es el día de cobro de la fuente dentro de ese período.
• Pendiente = concepto activo (y salario activo), sin registro en el período y, si es préstamo con cuotas totales, con cuotas restantes > 0. Se calcula al vuelo (src/lib/salario.ts): no se generan filas por adelantado ni se usa period_generations/entry_omisiones. Solo cuenta el período vigente: un concepto que no se registró en un período ya cerrado no se arrastra al siguiente.
• Cuotas restantes = cuotas totales − cuotas ya pagadas antes − suma de cuotas_cubiertas de los registros pagado. El fin estimado es la fecha de cobro del período en que cae la última cuota.
• Marcar pagado: precarga cuota × cuotas cubiertas, editable. Se pueden cubrir varias cuotas a la vez (adelanto): acorta el préstamo, pero el mes siguiente el concepto vuelve a figurar como pendiente.
• Omitir este mes: registro omitido, deja de figurar como pendiente.
• Revertir: borra el registro del período y vuelve a pendiente.
• Un solo registro por concepto y período (unique (salary_deduction_id, periodo)): el adelanto va en ese mismo registro con cuotas_cubiertas > 1.
• Saldo pendiente = bruto − lo ya debitado − lo que falta debitar en el período (cuota de cada concepto pendiente; lo omitido, inactivo o terminado no resta) − lo ya transferido al fondo. Antes de transferir es el sugerido para la transferencia (editable); una vez transferido baja a 0.
• Transferencia al fondo: se precarga con el saldo pendiente. Es informativa: no crea ningún movimiento en el fondo; el ingreso al fondo se sigue cargando como hasta ahora (plantilla de ingreso o extra).

Dónde aparece

• /salario (menú "Salario"): una tarjeta por salario con bruto, descuentos del período y su estado, cuotas restantes y fin estimado, y lo transferido al fondo. En escritorio el formulario de pago de un pendiente está siempre visible; en móvil va detrás de "Editar"/"Cerrar".
• Dashboard: panel "Pendientes del salario", solo si hay pendientes, agrupado por salario (mismo formato desplegable que "Para rescatar antes del mediodía"). El botón "Pagado" registra con el monto precargado y 1 cuota.
• Aviso diario de Telegram: sección "Pendientes del salario" con los pendientes cuya fecha de cobro del período ya llegó. El aviso sigue sin mandarse solo si no hay nada ni para rescatar ni del salario.

---

Préstamos en cuotas en las plantillas de gastos

PASO OBLIGATORIO antes de desplegar esta versión

Ejecutar en el SQL Editor de Supabase:

supabase/cuotas_plantillas.sql

Agrega cuotas_total y cuotas_pagadas_inicial a expense_templates, y numero_cuota a expense_entries. Es idempotente. Sin este script, Mes actual, Configuración → Plantillas y Previsiones fallan, porque ya leen esas columnas.

Qué hace

Mismo concepto que los préstamos de /salario, aplicado a los gastos de la plantilla mensual (src/lib/cuotas.ts):

• En Configuración → Plantillas, cada gasto tiene un botón "Cuotas" para cargar las cuotas totales y cuántas lleva pagadas en total hasta hoy. Las que ya figuran rescatadas/pagadas en la app se descuentan solas; en la base se guarda solo la diferencia (cuotas_pagadas_inicial). Dejar "Cuotas totales" vacío lo vuelve un gasto sin fin, como antes.
• La plantilla muestra "quedan N de T cuotas · fin estimado dd/mm/aaaa".
• Cuota pagada = el gasto llegó a rescatado o pagado (lo primero que pase), igual que la regla del fondo. Revertir a pendiente la vuelve a sumar a las restantes.
• Cada gasto generado guarda su número de cuota (numero_cuota) y Mes actual muestra "cuota 13 de 60". Se congela al generar, como el monto; si se cambia la configuración de cuotas de la plantilla, se renumeran los gastos ya generados de esa plantilla.
• Al llegar a la última cuota, la plantilla deja de generar gastos sola, sin tener que desactivarla.
• Previsiones proyecta el préstamo solo por las cuotas que quedan.
• Un gasto de préstamo borrado a mano en un mes (omisión) no cuenta como cuota: el préstamo se corre un mes.
• Sin adelantos de cuotas por ahora: si alguna vez se adelanta, se corrige subiendo "Ya pagadas".

---

Fondo mutuo: secciones plegables y "Variación" en vez de "Neto"

• "Registrar saldo real" y "Extracto mensual" quedan plegados por defecto (SeccionPlegable): se usan de vez en cuando. Plegado, el primero igual muestra el último registro (fecha y saldo).
• Movimientos confirmados ya no muestra "Neto" (ingresos − egresos): dejaba afuera intereses y saldo inicial, así que nunca coincidía con el saldo del fondo. Ahora muestra Variación = ingresos + intereses − egresos, el Saldo inicial cuando entra en la lista y, sin filtros, Rescatado sin pagar (gastos rescatados que todavía no se marcaron pagados: la plata ya salió del fondo pero no figuran en la lista de confirmados). Sin filtros, si la cuenta cierra, se muestra: saldo inicial + variación − rescatado sin pagar = saldo actual.
• Las fechas de la pantalla se muestran dd/mm/aaaa.

---

Aviso de gastos que caen en fin de semana

Los días fijos de las plantillas caen en sábado o domingo según el mes, y esos días no se pueden hacer los rescates del fondo. Por ahora es solo aviso: la fecha se corrige a mano.

• Mes actual y Extras: un gasto pendiente cuya fecha cae en fin de semana muestra "· cae sábado" / "· cae domingo" en ocre, en la línea gris debajo del nombre (escritorio y móvil). Lo ya rescatado o pagado no se marca.
• Telegram, día 27 (primer día del ciclo, junto con el extracto): un mensaje aparte con los gastos del ciclo que arranca que caen en fin de semana. Como ese día los gastos regulares pueden no estar generados todavía, se arma desde las plantillas vigentes con las mismas reglas que la generación (vigencias, omisiones, préstamos en cuotas terminados); si el gasto ya existe, usa su día real. Suma los extras pendientes del período. Si no hay ninguno, no se manda nada.