Finanzas

English

Aplicación local de finanzas personales construida con Flask y SQLite. Permite organizar deudas, consultar un calendario de pagos, registrar abonos e importar ingresos desde CFDI. Incluye un complemento para Obsidian de escritorio. La interfaz está en español y los importes se expresan en MXN.

Complemento de Obsidian

El complemento Finanzas abre esta aplicación en una pestaña de Obsidian de escritorio. Requiere que instales manualmente la aplicación Python en .finanzas/ dentro de tu bóveda siguiendo los pasos de abajo. Instalar el complemento desde el catálogo no instala Python, Flask ni la aplicación.

Después configura el ejecutable de Python en los ajustes del complemento. Abre Finanzas con el icono de billetera o los comandos Abrir Finanzas y Abrir deudas. Al abrir una vista, puede iniciar el servidor local existente; el inicio al abrir la bóveda está desactivado por defecto y se activa en Ajustes. El servidor continúa funcionando al cerrar la vista.

Dependencias, red y privacidad

• Solo funciona en escritorio: utiliza APIs de Node.js y una vista web de Electron.
• Se comunica con http://127.0.0.1:5028 en tu equipo para mostrar Finanzas y consultar su estado.
• Ejecuta el Python que configures, que puede estar fuera de la bóveda, y el archivo .finanzas/run.py dentro de ella. No instala ni actualiza dependencias automáticamente.
• No incluye telemetría ni envía tus notas o datos financieros a un servicio externo. La integración opcional de Gmail pertenece a la aplicación Python y usa IMAP/SMTP de Gmail cuando la configuras.
• Requiere el acceso local que configures con el asistente; usar el complemento no exige una cuenta en un servicio de Finanzas.
• Mantiene las opciones locales del complemento en data.json. Las distribuciones y releases omiten ese archivo y la configuración privada del servidor.

Funciones

• Calendario mensual con edición de montos y fechas, arrastre de pagos en escritorio y vista por día en móvil.
• Deudas de una sola vez con total pendiente. Completarlas las elimina de la lista.
• Recordatorios recurrentes: completar una fecha la retira del calendario y conserva las siguientes repeticiones.
• Deudas con abonos, calendario de cuotas, saldo pendiente e historial de pagos.
• Comparación opcional de pagos programados con un ingreso quincenal configurable.
• Importación opcional de CFDI desde Gmail, con detección de duplicados.
• Acceso mediante contraseña, verificación CSRF y credenciales de Gmail cifradas en la base local.
• Complemento de Obsidian que abre la aplicación en una pestaña y adopta el tema de la bóveda.

Requisitos

Python 3.11 o superior. Obsidian de escritorio es opcional. La primera instalación requiere acceso a internet para descargar dependencias.

Instalación

Desde la carpeta del repositorio, en Windows:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe scripts/bootstrap_auth.py --username admin
.\.venv\Scripts\python.exe run.py

En Linux o macOS:

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python scripts/bootstrap_auth.py --username admin
.venv/bin/python run.py

El asistente pide una contraseña, crea .env a partir de .env.example y guarda un hash de la contraseña y una clave de sesión aleatoria. Abre http://127.0.0.1:5028 e inicia sesión con el usuario elegido. Una instalación nueva comienza sin deudas ni movimientos.

Configuración

Configura los valores privados en .env, que está excluido de Git. Reinicia el servidor después de modificarlo.

Variable	Uso
PROJECT_NAME	Nombre de la aplicación.
PORT	Puerto local; por defecto, 5028.
APP_TIMEZONE	Zona horaria; por defecto, America/Mexico_City.
AUTH_USERNAME / AUTH_PASSWORD_HASH	Acceso configurado por el asistente.
SECRET_KEY	Clave de sesiones y cifrado. Consérvala junto con tus respaldos privados.
DATABASE_URL	Ubicación SQLite; por defecto, sqlite:///instance/finanzas.sqlite3.
QUINCENAL_INCOME_CENTS	Ingreso por quincena en centavos. 0 desactiva la comparación; 1000000 representa $10,000.00 MXN.
GMAIL_EMAIL	Cuenta opcional de Gmail. También puedes configurarla en Ajustes.
XML_SENDER_EMAIL	Remitente autorizado para importar CFDI.

Para importar desde Gmail, configura la cuenta y una contraseña de aplicación en Ajustes, y define XML_SENDER_EMAIL en .env. El botón Actualizar CFDI inicia la importación. También puedes ejecutar:

python import_gmail_xml.py --dry-run
python import_gmail_xml.py --days 30 --max-messages 100
python send_reminders.py

Sustituye python por el ejecutable del entorno virtual. La ejecución periódica de estos scripts requiere un programador externo; la aplicación no instala tareas automáticamente.

Obsidian

Coloca la aplicación en .finanzas/ dentro de tu bóveda. Copia main.js, manifest.json y styles.css de la raíz del repositorio a .obsidian/plugins/finanzas-local/. Activa Finanzas en los complementos de comunidad y configura el ejecutable de Python del entorno virtual en sus ajustes. El complemento utiliza el puerto 5028.

Los cambios de Python requieren reiniciar el servidor; los cambios del complemento requieren desactivarlo y volverlo a activar.

Pruebas

python -m pytest tests/ -q

Las pruebas utilizan bases temporales y simulan Gmail. La revisión opcional de interfaz requiere Playwright y Microsoft Edge:

python -m pip install playwright
python tests/browser_check.py

Datos y publicación

El repositorio contiene código, recursos de interfaz y pruebas con datos sintéticos. .gitignore excluye configuración privada, catálogos de usuarios, bases SQLite, respaldos, archivos subidos, registros, cachés y entornos virtuales. Los correos y montos personales no están preconfigurados.

Los datos se guardan en instance/. Respalda la base SQLite con la aplicación detenida o mediante la API de respaldo de SQLite. Guarda también .env y los archivos subidos en un destino privado. Conserva SECRET_KEY para poder descifrar las credenciales de Gmail existentes.

La versión publicable omite las migraciones privadas y la antigua descarga que empaquetaba datos y credenciales. Para distribuir exclusivamente los archivos versionados:

git archive --format=zip --output=finanzas-source.zip HEAD

El servidor de run.py escucha solamente en 127.0.0.1. Un despliegue accesible por internet requiere configurar un servidor WSGI, HTTPS y una clave estable; este repositorio no incluye un despliegue de producción. El estado local puede consultarse en /api/health.

Licencia

MIT.