Saltar a contenido

Gestión de Alertas y Eventos

El sistema de Eventos de Nexus Energy proporciona monitoreo continuo y detección temprana de fallos en los equipos instalados. Actúa como el centro operativo para garantizar la disponibilidad del hardware y minimizar el tiempo de inactividad de las instalaciones.

🚦 Niveles de Severidad y Clasificación

Cada incidencia reportada por los dispositivos o detectada por las reglas de telemetría se etiqueta bajo una jerarquía estricta de severidad para facilitar su priorización:

Severidad Nivel Color Indicador Descripción Operativa Ejemplo de Evento
1 Info Azul Eventos operativos normales que no requieren acción, solo registro. Cambio de modo de carga de batería.
2 Warning Amarillo Comportamiento anómalo leve. El sistema sigue operando pero requiere supervisión. Temperatura interna del inversor elevada.
3 Error Naranja Fallo crítico parcial. Afecta el rendimiento general pero el equipo sigue encendido. Desconexión o fallo de un string/tracker solar MPPT.
4 Critical Rojo Fallo total o parada de seguridad. Requiere intervención técnica inmediata. Desconexión de la red pública (Grid Down) o disparo de protección BMS.

🖥️ El Panel de Alertas Activas

En la Vista de Organización del dashboard principal, se expone una sección dedicada a "Alertas Pendientes". Esta sección: * Muestra únicamente los eventos en estado no reconocido (Unacknowledged) o alarmas de telemetría activas. * Agrupa las incidencias de todas las sucursales asignadas en tiempo real. * Ordena de forma cronológica descendente, destacando visualmente la severidad mediante píldoras de colores y animaciones de latido en el caso de las alertas críticas.

🔄 Flujo de Reconocimiento (Acknowledge Workflow)

Para asegurar una auditoría clara y evitar la duplicación de esfuerzos de mantenimiento, la plataforma implementa un proceso formal de reconocimiento de alarmas:

flowchart LR
    A["Alerta Nueva en Campo"] --> B["Petición en Dashboard"]
    B --> C["Acción: Reconocer"]
    C --> D["Registro de Firma en D1"]
  1. Visualización: El operario o administrador del sitio observa la alarma activa en el panel.
  2. Acción de Acknowledge: Al presionar el botón "Reconocer" sobre la alerta:
    • Se envía una solicitud firmada al servidor.
    • La base de datos actualiza el registro del evento en la tabla events: 
      UPDATE events 
SET acknowledged = 1, 
    acknowledged_by = 'clerk_user_id', 
    acknowledged_at = CURRENT_TIMESTAMP
WHERE id = ?;
  3. Auditoría: El sistema graba la firma digital de Clerk (clerk_user_id) y el timestamp preciso en UTC.
  4. Actualización Dinámica: La alerta desaparece del listado de pendientes de forma instantánea gracias a la reactividad de Svelte 5, manteniendo limpia la consola de control.

📡 Sistema de Notificaciones Externas y Directorio de Contactos

Para lograr la máxima flexibilidad de despacho sin comprometer la seguridad ni acoplar las alertas a cuentas con credenciales de acceso a la plataforma, Nexus Energy introduce un modelo decapolado de contactos y reglas de alerta.

flowchart LR
    A["Directorio Contactos<br><small>(Técnicos, Supervisores)</small>"] --> B["Reglas de Alerta<br><small>(Métricas, Histéresis)</small>"]
    B --> C["Hardware de Despacho<br><small>(Pasarela ESP32, SMS/Call)</small>"]

👥 1. Directorio de Contactos Reutilizables

Un Contacto es una ficha o registro independiente de información personal que pertenece a una Organización o Sitio específico. * Independencia de Cuentas: Los contactos no requieren tener una cuenta de Clerk, correo corporativo registrado ni permisos de inicio de sesión en Nexus Energy. * Formatos Validados: El sistema aplica validadores de datos estrictos en tiempo real: * Teléfonos (E.164): Obligatoriamente en formato estándar internacional con el prefijo de país + (ej: +56912345678 en Chile o +5351234567 en Cuba). Esto previene fallos al inyectar comandos SMS o llamadas de voz en redes celulares externas. * Canales Soportados: Teléfono (SMS, Llamadas de Voz, WhatsApp), Correo Electrónico, y Telegram Chat ID.

⚙️ 2. Reglas de Alerta de Telemetría

Los administradores pueden definir condiciones lógicas personalizadas basadas en métricas operativas directas de los equipos en campo. * Alcance (Scope): Las reglas pueden configurarse de forma global (toda la empresa), asociarse a un Sitio específico o limitarse a un único Inversor/Analizador. * Métricas del Inversor: Configuración de umbrales en parámetros como: * soc: Estado de Carga de las Baterías (%). * temp_inverter: Temperatura interna del equipo (°C). * inverter_voltage_phase_a: Voltaje de Fase de Salida (V). * current_leakage: Fuga de corriente residual (mA). * com_interval_ok: Cantidad de lecturas exitosas en el último intervalo.

🔬 Flapping Avoidance (Histéresis) y Tiempos de Cooldown

Para aplicaciones industriales, la telemetría fluctúa continuamente cerca de un límite crítico. Sin controles apropiados, un sensor oscilante provocaría ráfagas insoportables de notificaciones ("flapping"). Nexus Energy soluciona esto con lógica avanzada a nivel de servicio.

📉 A. El Margen de Histéresis

La histéresis define un búfer físico de tolerancia antes de permitir que una alerta activa retorne al estado resuelto.

  • Reglas de Límite Máximo (HIGH) (ej. Temperatura Inversor > 50°C con Histéresis de 5°C):
    • Disparo (ON): Se activa de inmediato cuando la temperatura es superior a 50°C.
    • Resolución (OFF): Solo se marca como resuelta cuando la temperatura desciende de manera estable por debajo de 45°C ($50 - 5 = 45$).
  • Reglas de Límite Mínimo (LOW) (ej. SoC de Batería < 20% con Histéresis de 5%):
    • Disparo (ON): Se activa de inmediato cuando la carga de la batería es menor al 20%.
    • Resolución (OFF): Solo se resuelve cuando la batería se carga y supera el 25% ($20 + 5 = 25$).

⏱️ B. Tiempo de Cooldown (Espera entre Notificaciones)

El Cooldown (Tiempo de espera) es un temporizador definido en minutos por cada regla que previene el spam repetitivo mientras la alarma siga encendida: * Si una alerta continúa activa por varias horas, el sistema no volverá a despachar mensajes hasta que transcurra el tiempo de cooldown programado (ej. cada 15 o 30 minutos).

📝 Plantillas Dinámicas de Mensajes

Cada canal mapeado a una regla de alerta admite personalización de texto mediante un motor de sustitución de variables. Puedes utilizar los siguientes marcadores de posición que el sistema traducirá automáticamente en tiempo real:

Variable Descripción Ejemplo de Traducción
[Nombre] Nombre completo del destinatario. Ing. Pedro Rodríguez
[Cargo] Posición del contacto técnico. Supervisor de Planta
[Dispositivo] Nombre descriptivo del inversor asignado. Inversor Principal Sur
[Sitio] Ubicación física o sucursal. Planta Solar Nitza
[Metrica] Nombre técnico de la variable. soc
[Valor] Medición actual detectada en campo. 18.5
[Operador] Símbolo lógico de la condición. <
[Umbral] Valor límite configurado. 20
  • Ejemplo de Plantilla: > Estimado [Cargo] [Nombre]: Alerta de [Metrica] en [Dispositivo] de [Sitio]. Valor actual: [Valor] (Umbral: [Operador] [Umbral])
  • Mensaje Resultante: > Estimado Supervisor de Planta Ing. Pedro Rodríguez: Alerta de soc en Inversor Principal Sur de Planta Solar Nitza. Valor actual: 18.5 (Umbral: < 20)

📡 Integración con Hardware: La Pasarela ESP32

El envío real de notificaciones basadas en telefonía móvil (SMS, Llamadas automáticas y WhatsApp) se delega a un hardware de pasarela en campo (basado en microcontroladores ESP32 con módulos GSM/LTE).

flowchart TD
    Sensor["Sensor en Campo"] -->|Ingesta API| Rules["Motor de Reglas"]
    Rules -->|Inserta en D1| Queue["Cola de Tareas"]
    Queue -->|Telemetry ACK| Gateway["Gateway ESP32"]
    Gateway -->|SMS / Call| Phone["Celular Técnico"]
    Phone -->|Confirma ACK| Audit["Registro Auditoría"]

1. Mecanismo de Polling Asíncrono

  • Cuando la plataforma detecta que una regla se ha disparado, crea una tarea pendiente en la tabla esp32_notification_tasks con el estado 'pending'.
  • El gateway ESP32, al enviar sus pings de telemetría regular a /api/devices/upload o /api/v1/ingest, recibe en el cuerpo de la respuesta un listado de tareas pendientes (tasks) que debe procesar y enviar.

2. Cancelaciones en Tiempo Real (cancel_tasks)

  • Si una variable crítica se normaliza e ingresa al rango seguro determinado por la histéresis antes de que el hardware logre enviar el SMS, el servidor detecta el cambio de estado y agrega el ID de la tarea a la lista cancel_tasks en la siguiente respuesta.
  • El hardware cancela de inmediato la cola local de despacho, evitando enviar alertas obsoletas o innecesarias al personal técnico.

3. Registro de Confirmaciones (Real-Time ACK)

  • Una vez que el módulo GSM/LTE del ESP32 despacha con éxito el SMS o completa la llamada telefónica, envía una confirmación HTTP POST al endpoint /api/esp32/tasks/ack.
  • El servidor actualiza tanto la tarea como el historial general de notificaciones (notification_logs) a estado 'sent' (o 'failed' con detalles si hubo pérdida de señal en campo), garantizando una bitácora de auditoría 100% fidedigna y transparente.