finanzas/gemini.md

Análisis del Proyecto Finanzas (gemini.md)

Note

Estado de la Revisión (28/01/2026): Se han aplicado las correcciones de arquitectura:

• Store Refactorizado: Dividido en slices (debts, cards, budget, alerts) y unificado en lib/store.ts.
• UUID: Implementado uuidv4 para generación de IDs.
• Modales: Implementados funcionalmente en components/modals/* con formularios completos.

El código ahora cumple con las buenas prácticas establecidas.

Este documento sirve como guía técnica, revisión de código y hoja de ruta para el desarrollo continuo del proyecto "Finanzas". Está diseñado para ser interpretado tanto por desarrolladores humanos como por agentes de IA (Minimax, GLM, Claude, etc.) para mantener la coherencia y calidad del código.

1. Visión General del Stack

• Framework: Next.js 14+ (App Router)
• Lenguaje: TypeScript
• Estilos: Tailwind CSS
• Estado Global: Zustand (con persistencia en localStorage)
• Utilidades UI: clsx, tailwind-merge, lucide-react
• Fechas: date-fns, Intl.DateTimeFormat

2. Puntos Fuertes Detectados

• Estructura Limpia: Separación clara entre lógica de negocio (lib), UI (components) y rutas (app).
• Tipado Fuerte: Uso consistente de interfaces en lib/types.ts.
• Estado Persistente: Buena implementación de zustand con middleware de persistencia para mantener los datos entre recargas.
• Utilidades Reutilizables: Funciones auxiliares bien definidas en lib/utils.ts para formateo de moneda y fechas.

3. Correcciones y Mejoras Inmediatas

A. Gestión de IDs

Estado Actual: Se usa crypto.randomUUID() con un fallback a Date.now(). Mejora: uuid ya está en package.json. Es preferible usar la librería uuid (v4) para garantizar colisiones nulas, especialmente si se planea sincronizar datos en el futuro.

import { v4 as uuidv4 } from 'uuid';
// Reemplazar generateId() por uuidv4()

B. Separación de Responsabilidades en el Store

Estado Actual: useFinanzasStore es un store monolítico. Mejora: A medida que la aplicación crezca, dividir el store en "slices" (ej: createBudgetSlice, createDebtsSlice) mantendrá el código más mantenible.

C. Optimización de Renderizado (use client)

Estado Actual: app/page.tsx es un componente de cliente ('use client') gigante. Mejora:

1. Mover la lógica de modales y efectos a componentes más pequeños.
2. Mantener la página principal lo más ligera posible.
3. Extraer los modales (AddDebtModal, etc.) a sus propios archivos en components/modals.

4. Buenas Prácticas (Standard Guidelines)

Cualquier IA que trabaje en este proyecto debe seguir estas reglas:

1. Strict Typing: No usar any. Definir interfaces para todas las props y estructuras de datos.
2. Modular CSS: Usar siempre cn() (clsx + tailwind-merge) para clases condicionales.
3. Componentes Funcionales: Preferir componentes pequeños y composables.
4. Nombrado:
   • Componentes: PascalCase (ej: BudgetCard.tsx)
   • Funciones/Variables: camelCase (ej: calculateTotal)
   • Archivos de utilidad: kebab-case o camelCase (ej: date-utils.ts)

5. Nice to Have (Futuras Implementaciones)

Funcionalidades

• Validación de Formularios: Implementar zod + react-hook-form para validar entradas de usuario (montos negativos, fechas inválidas).
• Exportación de Datos: Permitir exportar el estado a JSON/CSV para backup.
• Temas: Soporte real para modo claro/oscuro (actualmente parece hardcodeado a oscuro/slate).
• Gráficos Avanzados: Expandir el uso de recharts para mostrar tendencias de gastos vs ingresos.

Calidad de Código

• Tests Unitarios: Agregar Vitest para probar lógica crítica en lib/utils.ts y reducers del store.
• Barrel Files: Mantener actualizados los index.ts en las carpetas de componentes para importaciones más limpias.

Accesibilidad (a11y)

• Asegurar que todos los botones tengan aria-label si son solo íconos.
• Verificar contraste de colores en las tarjetas de deuda.

6. Instrucciones para Agentes de IA

Al generar código para este proyecto:

1. Contexto: Lee siempre lib/types.ts antes de modificar el estado.
2. Estilo: Replica el diseño visual existente (bg-slate-950, bordes sutiles, texto slate-400 para secundario).
3. Estado: Si agregas una nueva funcionalidad que requiere persistencia, agrégala a AppState en lib/types.ts y actualiza lib/store.ts.
4. UI: Usa componentes de lucide-react para íconos.

7. Snippets Comunes

Formateo de Moneda:

import { formatCurrency } from '@/lib/utils';
// Uso: formatCurrency(1500) -> "$ 1.500,00"

Clases Condicionales:

import { cn } from '@/lib/utils';
<div className={cn("p-4 bg-white", isError && "bg-red-50")} />