Arquitectura de Conexión Bancaria en Vivo · Finanzas Personales

Diseñado para proveer saldo consolidado en tiempo real, calendario de vencimientos y conciliación automática de cuentas personales de Gabriel Busso (BBVA, Banco Galicia, Mercado Pago).

🏛️ Diagnóstico y Principio Rector

Para tener el saldo real de todas las cuentas en vivo con máxima velocidad, 100% de fiabilidad y cero riesgo de bloqueos bancarios por 2FA/seguridad, se adopta una Arquitectura Híbrida de 3 Capas:

flowchart TD
    subgraph Fuentes ["Bancos e Instituciones"]
        MP["Mercado Pago (Personal)"]
        BBVA["BBVA Francés"]
        GAL["Banco Galicia Éminent"]
        CARD["InfoTarjetas (Visa/Mastercard)"]
    end

    subgraph CapaIngesta ["Motor de Ingesta Inteligente"]
        API_MP["Capa 1: API Oficial Directa<br>(OAuth / Access Token · Latencia <200ms)"]
        WATCHER["Capa 2: Push-Watcher Inmediato<br>(Parseo de Avisos y Transferencias en 0s)"]
        PLAYWRIGHT["Capa 3: Playwright Stealth Worker<br>(Posición Global y Cierre Oficial)"]
    end

    subgraph Almacenamiento ["Bóveda Local Segura"]
        SQLITE[("finanzas_personales.sqlite<br>~/Proyectos/plant-personal/datos/")]
    end

    subgraph Experiencia ["Consumo y Control"]
        DASH["Tablero Haute Horlogerie<br>(docs/tablero_finanzas.html)"]
        WSP["Agente WhatsApp Finance<br>(Audios y Consultas en Vivo)"]
    end

    MP --> API_MP
    BBVA --> WATCHER
    GAL --> WATCHER
    CARD --> WATCHER
    BBVA --> PLAYWRIGHT
    GAL --> PLAYWRIGHT

    API_MP --> SQLITE
    WATCHER --> SQLITE
    PLAYWRIGHT --> SQLITE

    SQLITE --> DASH
    SQLITE --> WSP

⚡ Detalle de las 3 Capas de Conexión

1. Mercado Pago · API Oficial en Vivo (Capa 1)

• Mecanismo: Conexión directa contra la API pública y privada de Mercado Pago (https://api.mercadopago.com/users/me/mercadopago_account/balance).
• Autenticación: Personal Access Token generado desde el portal de desarrolladores de Mercado Pago para la cuenta personal de Gabriel.
• Datos en tiempo real:
• Saldo disponible en pesos (ARS).
• Dinero invertido en Fondos Comunes de Inversión (con rendimientos devengados día a día).
• Retenciones temporales o pagos en tránsito.
• Frecuencia: Consulta en vivo al abrir el tablero o a demanda (< 200 ms). Cero fricción, cero captchas.

2. Push-Watcher de Notificaciones Inmediatas (Capa 2 · Tiempo Real Cero Fricción)

• Mecanismo: Los bancos argentinos notifican por canal transaccional (email / push) en menos de 5 segundos tras cualquier movimiento. El watcher local de plant-personal procesa estos eventos:
• BBVA: avisos@bbva.com.ar («Acreditación de haberes», «Realizaste una transferencia», «Aviso débito automático»).
• Galicia: bancogalicia@mail.galicia.ar y alertas de operaciones.
• InfoTarjetas / Prisma: alertas@infomistarjetas.com («Aviso de consumo autorizado», con comercio, moneda e importe exacto de la tarjeta terminada en 3958).
• Ventaja insuperable: Mantiene el saldo disponible actualizado al segundo de haber realizado una compra o recibido un pago, sin depender de levantar un navegador ni arriesgar bloqueos por sesiones concurrentes.

3. Playwright Stealth Worker · Conciliación de Posición Global (Capa 3)

• Mecanismo: Motor headless automatizado basado en la arquitectura ya probada en producción en plant-hub/apps/scraper (Playwright con plugin puppeteer-extra-plugin-stealth y huellas de browser de usuario real).
• Persistencia de Sesión (storageState.json):
• Se realiza una única vinculación asistida en el navegador local para ingresar usuario, clave y token de seguridad.
• Las cookies de sesión se preservan de forma local y cifrada.
• Endpoints Internos Extraídos:
• BBVA: Consulta al servicio de posición global (/fnetcore/servicios/posicion-global) para obtener el saldo oficial contable de la caja de ahorro en pesos y en dólares, más el resumen liquidado de Visa Signature.
• Galicia: Consulta a la posición consolidada de cuentas Éminent y tarjetas.
• Frecuencia de Ejecución: Una vez al día en horario bancario (o mediante un botón "Sincronizar Oficial" en el tablero de finanzas).

🔒 Privacidad, Seguridad y Bóveda de Claves

1. Aislamiento Total: El código, los datos y las credenciales viven estrictamente en el repositorio privado ~/Proyectos/plant-personal.
2. Cero Exposición a Repositorios Públicos: Las credenciales y tokens residen exclusivamente en ~/.config/plant-personal/secrets.env, ignorado por Git.
3. Esquema de Base de Datos:

• cuentas: ID, entidad (BBVA, Galicia, MP), tipo (Caja de Ahorro ARS, Caja de Ahorro USD, Billetera), saldo_actual, fecha_corte.
• tarjetas: Entidad, marca (Visa Signature, Mastercard, MP), últimos 4 dígitos, fecha_cierre, fecha_vencimiento, saldo_pesos, saldo_dolares, pago_minimo.
• movimientos: Timestamp, cuenta_id, comercio/origen, categoría, importe, moneda, saldo_resultante.

🚀 Plan de Despliegue en 3 Fases

Temas/conexion-bancaria-en-vivo