Initial commit: Hybrid polling, interactive log modal and 3-second hard reset

doc/polling_modes_explanation.md

@@ -0,0 +1,45 @@
+# 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.