TotalConnect/doc/walkthrough.md

# Walkthrough - Resumen de Mejoras y Correcciones (TotalConnect Client)

Este documento resume los cambios y optimizaciones realizados para robustecer el panel de monitoreo centralizado de alarmas.

---

## 🛠️ Cambios Realizados

### 1. Actualización en Tiempo Real del Progreso de Carga
* **Problema:** El modal de carga se quedaba en un mensaje estático ("Conectando a los paneles...") y no actualizaba qué sucursal estaba procesando.
* **Solución:**
  * Se configuró la variable global `current_loading_status` para actualizarse en cada paso de `run_update()` (conexión inicial, selección de cuenta y consulta específica de sucursal).
  * Se agregaron cabeceras anti-caché en la respuesta HTTP (`Cache-Control: no-cache, no-store, must-revalidate`).
  * Se implementó un sondeo mediante `fetch` periódico (intervalo de 1.5s) que actualiza el texto de forma dinámica sin retrasos.

### 2. Lista de Exclusiones / Excepciones (`exclude`)
* **Problema:** El usuario deseaba omitir ciertas sucursales de prueba o fuera de servicio de la visualización global.
* **Solución:**
  * Se agregó soporte para una clave `"exclude": [...]` en el archivo de configuración `credentials.json`.
  * El script valida de forma inteligente si el ID numérico de la sucursal o su nombre coincide parcialmente con alguno de los elementos a excluir, omitiendo la consulta y el reporte de manera automática.

### 3. Apertura Automática del Navegador
* **Problema:** Iniciar el ejecutable requería que el usuario abriera manualmente la página en `http://localhost:8080/`.
* **Solución:**
  * Se integró el uso del módulo nativo `webbrowser` para abrir la pestaña al arrancar en modo servidor.
  * **Headless-safety:** El script detecta si el host no posee entorno gráfico (ausencia de `DISPLAY` en sistemas Linux/SSH) y desactiva esta apertura de forma segura para evitar cuelgues o warnings.
  * Se puede personalizar a través de `"open_browser": true/false` en el JSON o usando las banderas `--no-browser` / `-nb` en la CLI.

### 4. Filtrado de Historial de Alarma (Alarm Memory)
* **Problema:** Algunas sucursales desarmadas o armadas normalmente mostraban alertas de alarma activas debido a memorias no limpiadas físicamente en el teclado Honeywell.
* **Solución:**
  * Se rediseñó el bucle de validación de zonas. Ahora, una zona **sólo se marca como `ALARMA`** si la partición correspondiente de la sucursal está activamente disparada (`is_triggered`).
  * Si la sucursal está normal, las zonas cerradas no generan falsas alertas y las abiertas se muestran propiamente como `Abierta/Fallo` (color ámbar).

### 5. Tarjetas Deshabilitadas para Cuentas con Token Revocado
* **Problema:** Cuando una cuenta de Total Connect pierde credenciales o se revoca, sus sucursales se cargaban de la caché local pero se visualizaban igual que las sucursales normales de cuentas activas.
* **Solución:**
  * Se añadió la clase CSS `.branch-card-disabled` a las tarjetas cargadas desde la caché local con estatus `REVOKED`.
  * Esto les otorga un fondo gris medio (`#e2e8f0`), una opacidad del 65% y bloquea los efectos visuales de interacción en hover (sombra y escala), permitiendo distinguir a simple vista qué datos son históricos fuera de línea.

### 6. Diseño Responsivo y Text Wrapping
* **Problema:** En zonas activas largas, las horas de disparo quedaban recortadas con puntos suspensivos en la tarjeta.
* **Solución:**
  * Se eliminó el límite fijo de ancho de `.zone-desc` y se desactivó `white-space: nowrap`.
  * Se aumentó el ancho mínimo de las columnas en el grid responsivo a `290px`. Las descripciones largas ahora realizan un salto de línea natural posicionando la hora debajo de forma sumamente estética.

### 7. Checkboxes de Selección de Cuentas en la UI
* **Problema:** El usuario deseaba poder elegir qué cuentas actualizar para evitar demoras innecesarias (por ejemplo, evitar actualizar cuentas revocadas).
* **Solución:**
  * Se implementaron checkboxes en la cabecera que listan dinámicamente las cuentas de `credentials.json`.
  * Al hacer clic en "Actualizar", la UI envía mediante el cuerpo del POST (JSON) únicamente las etiquetas de las cuentas seleccionadas.

### 8. Persistencia y Mezcla de Estado (`last_state.json`)
* **Problema:** Si se actualizaba únicamente una cuenta, el reporte en el frontend sobrescribía el archivo HTML y hacía desaparecer las demás sucursales.
* **Solución:**
  * Se programó la escritura de `last_state.json` al finalizar cualquier consulta exitosa para guardar el último estado de todas las sucursales.
  * Cuando se realiza una actualización parcial (donde no se seleccionaron todas las cuentas), el backend carga los estados anteriores desde `last_state.json`, los mezcla con los nuevos resultados y genera la vista unificada.

### 9. Priorización de Cuentas Revocadas al Final del Listado
* **Problema:** El usuario deseaba ver las cuentas inactivas/revocadas al final de la página para que no interfieran visualmente con las activas.
* **Solución:**
  * Se definió un cuarto nivel de clasificación de prioridad:
    * `0`: Alarmas Activas (cabeza de página)
    * `1`: Sucursales Desarmadas
    * `2`: Sucursales Armadas (Stay, Away, etc.)
    * `3`: Sucursales Revocadas / Desconectadas (con fondo gris)
  * Todas las tarjetas dentro de cada categoría mantienen su estricto orden secuencial numérico.

### 10. Polling en Segundo Plano & Controles (Kill-Switch y Circuit Breaker)
* **Problema:** El usuario requería monitoreo continuo sin bloqueos de API de Honeywell y con la capacidad de detener el polling manualmente o si Honeywell responde errores de autenticación/rate limit.
* **Solución:**
  * **Motor Poller Daemon (`background_poller_thread`):** Se ejecuta cada 45s en segundo plano en el servidor Python.
  * **Circuit Breaker:** Si se registran 2 fallos de autenticación seguidos (`401` / `429`), el backend desactiva el polling automático previniendo bloqueos de IP de Honeywell.
  * **Endpoints Controladores:** Agregados `GET /polling-status` y `POST /toggle-polling`.
  * **Botonera en UI:** Se agregó el botón interactivo `[ ● Polling: Activo ]` / `[ ○ Polling: Pausado ]` en el encabezado.
  * **Auto-Focus (`visibilitychange`):** El navegador recarga el estatus automáticamente al regresar a la pestaña tras periodos de inactividad.

---

## 🔬 Verificación y Pruebas

* **Compilación y Empaquetado:** Generación exitosa de `totalconnect.exe` en Windows `E:\Software\TotalConnect\dist\totalconnect.exe`.
* **Sincronización:** Actualizado y desplegado en segundo plano en la VM de Linux accesible a través del puerto `8080`.
* **Validación de Funcionalidad:** Todas las rutas del dashboard, filtros por JSON, exclusiones y endpoints de polling operan correctamente.