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

doc/proposed_events_integration_plan.md

@@ -0,0 +1,70 @@
+# Plan de Implementación y Walkthrough Propuesto: Integración de Eventos en Tiempo Real
+
+Este documento detalla el plan de diseño técnico y la arquitectura de los cambios que se implementarán en el proyecto TotalConnect (`index.py`) para integrar el monitoreo por eventos en tiempo real.
+
+---
+
+## 🎯 Objetivos de la Implementación
+
+1. **Monitoreo Automático en Segundo Plano:** El servidor Python consultará a Honeywell mediante `GetEvents` cada 45–60 segundos sin requerir la intervención del usuario.
+2. **Actualización Ultra-Rápida (Delta Update):** En lugar de consultar las 285 sucursales (1-2 minutos), el sistema identificará únicamente las sucursales que registraron eventos nuevos y actualizará el reporte en **1 a 3 segundos**.
+3. **Cero Retraso al Abrir la Página (`GET /`):** La carga inicial seguirá leyendo `last_state.json` de inmediato (< 5 milisegundos).
+4. **Control Manual y Circuit Breaker (Botonera & Kill-Switch):**
+   * Botón en la cabecera del dashboard para **Pausar / Reanudar Polling**.
+   * Pausa automática inteligente si Honeywell responde errores de autenticación (401) o límite de peticiones (429).
+5. **DOM Patching Silencioso en la Interfaz (JS):** Actualización instantánea en el navegador únicamente de los nodos/tarjetas que cambiaron de estado, evitando parpadeos o animaciones molestas.
+6. **Manejo Resiliente Multicuenta y Revocados:** Las cuentas fuera de línea se mantendrán clasificadas con prioridad 3 al final del listado con fondo gris.
+
+---
+
+## 🏗️ Cambios Arquitectónicos por Componente
+
+### 1. Backend (`index.py`)
+
+#### A. Hilo Demonio de Polling en Segundo Plano (`BackgroundPollerThread`)
+* Se agregará un `threading.Thread(daemon=True)` que se ejecuta automáticamente al arrancar el servidor.
+* Mantiene variables globales en memoria:
+  * `polling_enabled` (`True` / `False`): Estado global del motor de consulta.
+  * `last_event_ids`: Diccionario `{ "Ccontrol2020": 850123, "Ccontrol2019": 412099 }` con el último ID de evento procesado por cuenta.
+  * `consecutive_errors`: Contador de fallos consecutivos por cuenta.
+
+#### B. Flujo del Poller (`poll_events_cycle()`):
+1. **Verificación de Pausa:** Si `polling_enabled` es `False`, el hilo espera 15 segundos y re-evalúa.
+2. **Petición Delta `GetEvents`:**  
+   Para cada cuenta activa en `credentials.json`, envía una llamada ligera `GetEvents` pasando `LastEventIdReceived`.
+3. **Evaluación de Resultados:**
+   * **Sin cambios:** Honeywell responde `[]`. No se hace nada más.
+   * **Con cambios:** Extrae los `LocationID` afectados. Ejecuta `fullStatus` únicamente para esos IDs.
+4. **Actualización de Estado:** Consolida la información en `last_state.json` y vuelve a generar `status.html`.
+5. **Manejo de Errores (Circuit Breaker):** Si una cuenta recibe 2 errores `401` o `429` seguidos, el servidor pausa el polling automático para esa cuenta y notifica a la UI.
+
+#### C. Endpoints HTTP Nuevos en `DashboardHandler`
+* `GET /polling-status`: Devuelve el estado actual (`enabled`, `last_run`, `active_errors`).
+* `POST /toggle-polling`: Permite a la interfaz web activar o pausar manualmente el polling.
+
+---
+
+### 2. Frontend (`status.html` / Template en `index.py`)
+
+#### A. Botón de Control de Polling en Cabecera
+Junto al botón "Actualizar" y al selector de cuentas, se agregará un nuevo botón dinámico:
+```html
+<button id="toggle-polling-btn" class="btn-polling-active" onclick="togglePolling()">
+    <span class="polling-indicator">●</span> Polling: Activo
+</button>
+```
+
+#### B. Polling Local JS y DOM Patching
+Un script JS en el cliente ejecutará una consulta ultrarrápida a `GET /polling-status` cada 15 segundos:
+* Si la respuesta indica un cambio en el timestamp del último estado, realiza un `fetch('/')` silencioso.
+* Compara los estados de las sucursales y actualiza el HTML **únicamente de las tarjetas que cambiaron**, manteniendo la posición y el foco del usuario.
+* **Auto-Check por Visibilidad (`visibilitychange`):** Al volver a la pestaña tras estar inactivo, el navegador refresca los datos al instante.
+
+---
+
+## 📝 Plan de Verificación
+
+1. **Prueba de Polling en Segundo Plano:** Iniciar el servidor, alterar el estado de una sucursal de prueba y verificar en consola que la consulta toma < 2 segundos.
+2. **Prueba de Kill-Switch:** Presionar el botón "Pausar Polling" en la interfaz y verificar que cesan las llamadas HTTP a Honeywell.
+3. **Prueba de Circuit Breaker:** Simular una credencial inválida y verificar que el servidor desactiva automáticamente el polling tras 2 intentos fallidos.
+4. **Prueba de Rendimiento:** Confirmar que la carga inicial `GET /` sigue respondiendo en < 5ms.