TransferData-main/Documentacion/Flujo_de_Datos.md

Flujo de Datos

Pipeline ETL General

DataTransferV2 sigue un patrón ETL clásico con etapas bien definidas y manejo de errores resiliente.

EXTRACT → TRANSFORM → LOAD → NOTIFY

Diagrama de Flujo

Inicio
  ↓
Cargar Configuraciones (PG, FEDURO)
  ↓
Para cada Proyecto:
  ┌─────────────────────────────────────┐
  │ Para cada Reporte:                  │
  │   Para cada Fecha (3 días):         │
  │     ┌─────────────────────────────┐ │
  │     │ EJECUTAR ETL                │ │
  │     │  ┌─────────┐  ┌──────────┐ │ │
  │     │  │ EXTRACT │→ │TRANSFORM│ │ │
  │     │  └─────────┘  └──────────┘ │ │
  │     │         ↓                  │ │
  │     │    ┌─────────┐             │ │
  │     │    │  LOAD   │             │ │
  │     │    └─────────┘             │ │
  │     └─────────────────────────────┘ │
  └─────────────────────────────────────┘
  ↓
Agregar Resultados
  ↓
Enviar Notificación
  ↓
Fin

Etapa EXTRACT

Proceso

1. Conectar a Base de Datos

   • Usar pyodbc para conexión SQL Server
   • Pooling de conexiones para eficiencia

2. Construir Query

   SELECT * FROM {TableName} WHERE Fecha = '{YYYY-MM-DD}'
   

3. Ejecutar Consulta

   • Timeout de 30 segundos
   • Manejo de excepciones de conexión

4. Validar Resultados

   • Contar registros obtenidos
   • Verificar integridad de datos

Estados Posibles

• SUCCESS: Datos encontrados (>0 registros)
• WARNING: Sin datos (=0 registros)
• FAILED: Error de conexión/query

Etapa TRANSFORM

Proceso

1. Crear DataFrame

   • Usar pandas para manipulación de datos
   • Validar tipos de datos

2. Generar Excel

   • Usar openpyxl para formato Excel
   • Crear hoja única con datos tabulares
   • Aplicar formato básico (headers en negrita)

3. Guardar Archivo

   Reportes/{PROJECT}/{REPORT}/{REPORT}-{YYYYMMDD}.xlsx
   

4. Validar Archivo

   • Verificar que se creó correctamente
   • Comprobar tamaño del archivo

Formato de Salida

• Nombre: {Reporte}-{Fecha}.xlsx
• Estructura: Hoja única con headers
• Encoding: UTF-8
• Separador: Sin separador (datos crudos)

Etapa LOAD

Destinos Múltiples

Cada reporte puede distribuirse a múltiples destinos según flags de configuración.

FTP Upload

1. Conectar al Servidor

   ftp = FTP(host, user, password)
   

2. Crear Directorios

   /TranferData_APP_PYTHON/{PROJECT}/{REPORT}/
   

3. Subir Archivo

   • Batch de 100 archivos
   • Reintentos automáticos en caso de fallo

4. Verificar Upload

   • Comparar tamaños local/remoto

SFTP Upload (FEDURO)

1. Conectar via SSH

   ssh = paramiko.SSHClient()
   ssh.connect(host, username, password)
   sftp = ssh.open_sftp()
   

2. Navegar a Directorio

   • Mapeo específico por reporte en feduroConfig.py

3. Subir Archivo

   • Transferencia segura
   • Verificación de integridad

SharePoint Upload (PG)

1. Autenticar con Office365

   ctx = ClientContext(site_url).with_credentials(credentials)
   

2. Subir a Document Library

   • Mapeo de carpetas por reporte
   • Sobrescribir archivos existentes

3. Verificar Upload

   • Confirmar presencia en SharePoint

N8N Webhook

1. Construir Payload

   {
     "project": "pg",
     "report": "Cobertura",
     "date": "2024-01-15",
     "file_path": "/path/to/file.xlsx"
   }
   

2. Enviar POST Request

   • Trigger automatización N8N
   • No espera respuesta

Estrategia de Distribución

• Paralelo: Todos los destinos se procesan simultáneamente
• Resiliente: Fallo en un destino no afecta otros
• Logging: Cada upload se registra individualmente

Agregación de Resultados

Reglas de Negocio

1. Éxito (SUCCESS)

   • Datos encontrados, Excel creado, todos los uploads exitosos

2. Completado con Errores (COMPLETED_WITH_ERRORS)

   • Datos procesados, pero algunos uploads fallaron
   • No bloquea el pipeline

3. Advertencia (WARNING)

   • Sin datos para la fecha
   • Ignorado si es domingo

4. Fallo (FAILED)

   • Error en consulta DB o creación de Excel
   • Detiene procesamiento del reporte

Lógica de Consolidación

# Reglas de negocio para warnings
if consecutive_warnings >= 3:
    status = "FAILED"
elif is_sunday and no_data:
    status = "IGNORED"
elif no_data:
    status = "WARNING"
else:
    status = "SUCCESS"

Notificaciones

WhatsApp Summary

Después de completar cada proyecto:

✅ PG - Completado
Total: 16, Éxito: 15, Errores: 1, Advertencias: 0
Tiempo de ejecución: 45 minutos
Detalles de errores: Cobertura-2024-01-15 (FTP timeout)

Contenido del Mensaje

• Estado del proyecto: ✅ ⚠️ ❌
• Estadísticas: Total, éxito, errores, advertencias
• Tiempo: Duración total
• Errores específicos: Lista de reportes/fechas con problemas

Manejo de Errores

Tipos de Error

1. Errores de Conexión

   • DB: Reintentar conexión
   • FTP/SFTP: Reintentar upload
   • SharePoint: Reautenticar

2. Errores de Datos

   • Sin datos: Advertencia (no error)
   • Datos corruptos: Fallo crítico

3. Errores de Sistema

   • Disco lleno: Fallo crítico
   • Memoria insuficiente: Reinicio automático

Recuperación

• Reintentos: Hasta 3 intentos para operaciones de red
• Fallback: Continuar con otros destinos si uno falla
• Logging: Todos los errores se registran con contexto completo

Rendimiento

Métricas Típicas

• Tiempo por reporte: 30-120 segundos
• Throughput: 16-18 reportes por proyecto (~30-60 min)
• Uso de memoria: 100-500MB por ejecución
• I/O: 10-50MB por reporte Excel

Optimizaciones

• Conexiones pool: Reutilización de conexiones DB
• Procesamiento por lotes: Múltiples fechas en una ejecución
• Compresión: Archivos Excel optimizados
• Paralelización: Uploads simultáneos

Auditoría

Logging a Base de Datos

Cada ejecución se registra en ExecutionLog:

INSERT INTO ExecutionLog (
    ProcedureID, Name, Status, Message, 
    StartTime, EndTime, Duration
) VALUES (
    1001, 'Cobertura', 'SUCCESS', 'Processed 1500 records',
    '2024-01-15 08:00:00', '2024-01-15 08:02:30', 150
)

Logs de Aplicación

• Logs/etl.log: Progreso detallado
• Logs/api.log: Requests API
• Logs/reports.log: Generación de reportes

Monitoreo

KPIs Principales

• Tasa de éxito: % de reportes procesados correctamente
• Tiempo promedio: Duración por reporte/proyecto
• Errores por tipo: DB, red, sistema
• Volumen de datos: Registros/filas procesadas

Alertas

• Error rate > 10%
• Duración > 2x promedio
• Fallos consecutivos en mismo reporte