TotalConnect/doc/polling_modes_explanation.md

Explicación de Modos de Polling (Rápido vs. Full)

Este documento describe la arquitectura de consultas del monitor de TotalConnect 2.0, especificando el funcionamiento del Polling Rápido (Ligero) y del Polling Completo (Profundo), así como las circunstancias en las que se ejecuta cada uno.

---

1. Polling Rápido (Ligero / Delta)

El Polling Rápido es un mecanismo altamente optimizado diseñado para detectar cambios de estado en tiempo real con el mínimo consumo de ancho de banda y rendimiento.

• Tecnología Utilizada:
  • SOAP: Método GetLiveEvents (usando el SessionID GUID).
  • REST (Respaldo): Endpoint /sessiondetails (ejecutado únicamente si SOAP está desactivado o falla).
• Funcionamiento:
  • Solicita al servidor de Honeywell la lista de eventos ocurridos a partir de un ID de evento de referencia (LastEventIdReceived).
  • En modo de respaldo REST, solicita una lista compacta de las sucursales y sus estados básicos en una sola petición.
  • No realiza consultas directas a los paneles físicos de las sucursales, lo que permite que la respuesta tarde menos de 1 segundo para cientos de ubicaciones.
• Cuándo se ejecuta:
  • De forma automática y continua: Cada 45 segundos en el hilo de segundo plano del servidor (background_poller_thread).

---

2. Polling Completo (Profundo / Full)

El Polling Completo obtiene el estado exhaustivo de una o todas las sucursales, interactuando directamente con el panel físico a través de la nube de Resideo.

• Tecnología Utilizada: Endpoint REST /partitions/fullStatus de cada sucursal.
• Funcionamiento:
  • Consulta el estado en tiempo real de cada partición (P1-P6) y zona (Z1-Z285).
  • Extrae detalles críticos como fallos de zonas (puertas/ventanas abiertas), alarmas de fuego/gas/intrusión activas y horas localized de disparo de alarma.
  • Actualiza la persistencia local en last_state.json y regenera el reporte visual status.html.
• Cuándo se ejecuta:

A. Para sucursales individuales (Optimización Delta):

Se ejecuta únicamente para las sucursales específicas que cambiaron, durante el ciclo automático de 45 segundos, si el Polling Rápido detecta alguna de las siguientes circunstancias:

1. Actividad reportada por SOAP: Un evento nuevo en el delta de SOAP indica que hubo cambios en esa sucursal.
2. Cambio de estado general: El estatus de armado básico en la respuesta REST de respaldo cambió respecto al valor en caché (ej: Desarmado ➔ Armado Stay).
3. Alarma activa: La sucursal entra en un estado de alarma disparada (ALARMING, ALARMING_FIRE_SMOKE, etc.).
4. Validación de restablecimiento: La sucursal tenía particiones disparadas en el ciclo anterior (necesario para verificar si ya se desactivó/silenció la alarma).
5. Nueva sucursal: Se detecta una sucursal en la cuenta que no existía previamente en la caché.

B. Para todas las sucursales de la cuenta (Fuerza Bruta):

Se ejecuta una consulta completa para todas las sucursales de la cuenta bajo las siguientes circunstancias:

1. Refresco manual: El usuario hace clic en el botón "Actualizar" en el panel web (lo que envía una solicitud POST a /refresh con full_refresh=True).
2. Arranque inicial sin caché: El servidor inicia por primera vez y no existe el archivo last_state.json, lo que obliga a crear la base de datos de estatus desde cero.