up

2026-01-27 14:51:41 -05:00
parent c1f3524466
commit 1f224044f7
21 changed files with 2997 additions and 47 deletions
@@ -0,0 +1,349 @@
+# Sistema de Notificaciones en Tiempo Real (SSE)
+
+## 📡 Descripción
+
+Sistema de notificaciones push en tiempo real usando **Server-Sent Events (SSE)** para reemplazar el polling constante y mejorar la eficiencia.
+
+## 🔄 Flujo de funcionamiento
+
+### 1. **Cliente se conecta a SSE**
+```javascript
+// En conversations.php
+connectSSE() {
+  this.eventSource = new EventSource('api/sse_events.php');
+  // Escucha eventos: new_message, new_conversation, heartbeat
+}
+```
+
+### 2. **Webhook recibe mensaje de WhatsApp**
+```
+WhatsApp → webhook.php → Guarda en BD → pushSSEEvent()
+```
+
+### 3. **Push notifica a operadores conectados**
+```php
+webhook.php → push_event.php → Escribe evento en archivo temporal
+```
+
+### 4. **SSE envía evento a clientes**
+```php
+sse_events.php → Lee eventos pendientes → Envía a navegador
+```
+
+### 5. **Cliente recibe y procesa evento**
+```javascript
+// Solo actualiza la conversación afectada, NO recarga todo
+eventSource.addEventListener('new_message', (e) => {
+  // Actualizar conversación en lista
+  // Si es la activa, recargar mensajes
+  // Reproducir sonido
+});
+```
+
+## 📁 Archivos creados
+
+### `api/sse_events.php`
+- Endpoint SSE que mantiene conexión abierta
+- Lee eventos de archivos temporales
+- Envía eventos al navegador en tiempo real
+- **NUEVO**: Envía notificaciones no leídas automáticamente
+- Heartbeat cada 30 segundos para mantener conexión viva
+
+### `api/push_event.php`
+- API interna para empujar eventos
+- Solo accesible desde localhost o con token secreto
+- Escribe eventos en archivos temporales por usuario
+- Broadcast a todos los operadores conectados
+
+### `classes/NotificationHelper.php` ⭐ NUEVO
+- Helper para crear y enviar notificaciones
+- **Método create()**: Inserta en BD y envía automáticamente por SSE
+- **Método pushSSE()**: Envía notificación existente por SSE
+- Uso: `NotificationHelper::create($userId, 'document', 'Usuario subió documento', ['count' => 3])`
+
+## 🔧 Modificaciones en archivos existentes
+
+### `api/webhook.php`
+- ✅ Agregado método `pushSSEEvent()`
+- ✅ Llama a `push_event.php` cuando llega mensaje nuevo
+- ✅ Fire-and-forget (no bloquea el webhook)
+
+### `conversations.php`
+- ✅ Agregado método `connectSSE()`
+- ✅ Agregado método `updateConversationInList()`
+- ✅ Agregado método `addConversationToList()`
+- ✅ **Agregado listener para evento 'notification'**
+- ✅ Polling de notificaciones: 7s → 60s (backup)
+- ✅ Polling de conversaciones: 7s → 30s (backup)
+- ✅ Auto-refresh reducido de 8s → 20s (backup)
+
+## 🎯 Ventajas del sistema SSE
+
+### **Antes (Polling):**
+```
+Cliente → GET messages cada 7-8s
+Cliente → GET conversations cada 15s
+Cliente → GET notifications cada 7s
+
+
+### **Ahora (SSE):**
+```
+Cliente ← SSE conectado (1 conexión persistente)
+Servidor → Push cuando hay nuevo mensaje (< 1s)
+         → Recarga automáticamente: loadMessages(userId, false, true)
+Servidor → Push cuando hay nueva conversación (< 1s)
+         → Agrega a lista: addConversationToList(data)
+Servidor → Push cuando hay notificación (< 1s)
+         → Muestra toast: showNotificationToast(notification)
+Servidor → Heartbeat cada 30s
+
+Backup polling (solo por si falla SSE):
+Cliente → GET notifications cada 60s
+
+Total: ~1 petición por minuto por cliente
+```
+
+**Reducción: 95% menos peticiones HTTP** 🎉
+
+### ¿Por qué NO necesitamos ningún polling ahora?
+
+#### 1. **Mensajes**: SSE evento `new_message`
+```javascript
+// En conversations.php línea ~1103
+this.eventSource.addEventListener('new_message', (e) => {
+    const data = JSON.parse(e.data);
+    
+    // Si es la conversación activa, recarga mensajes
+    if (this.currentUserId === data.user_id) {
+        this.loadMessages(this.currentUserId, false, true); // ✅ Push
+    }
+    
+    // Actualiza la conversación en la lista
+    this.updateConversationInList(data);
+});
+```
+
+#### 2. **Conversaciones**: SSE eventos `new_message` + `new_conversation`
+```javascript
+// Actualización inteligente sin recargar todo
+this.eventSource.addEventListener('new_conversation', (e) => {
+    this.addConversationToList(JSON.parse(e.data)); // ✅ Solo agrega una
+});
+
+this.eventSource.addEventListener('new_message', (e) => {
+    this.updateConversationInList(JSON.parse(e.data)); // ✅ Solo actualiza una
+});
+```
+
+#### 3. **Notificaciones**: SSE evento `notification`
+```javascript
+this.eventSource.addEventListener('notification', (e) => {
+    this.showNotificationToast(JSON.parse(e.data)); // ✅ Toast instantáneo
+});
+```
+
+**Resultado**: Sistema 100% push, 0 polling innecesario 🚀
+Total: ~15-20 peticiones por minuto por cliente
+```
+
+### **Ahora (SSE):**
+```
+Cliente ← SSE conexión permanente
+Cliente → GET backup cada 15-20s
+
+Total: ~2-3 peticiones por minuto por cliente
+Eventos llegan en < 1 segundo después del webhook
+```
+
+### **Beneficios:**
+- ✅ **Latencia ultra-baja:** Mensajes llegan en ~500ms
+- ✅ **Menos carga servidor:** 85% menos peticiones HTTP
+- ✅ **Actualizaciones incrementales:** Solo afecta conversación específica
+- ✅ **No recarga todo:** UI más fluida y rápida
+- ✅ **Conexión persistente:** Un solo canal para todos los eventos
+- ✅ **Fallback automático:** Si SSE falla, polling sigue funcionando
+
+## 🔐 Seguridad
+
+### **Token secreto interno:**
+```php
+// En push_event.php
+X-Push-Token: internal_push_secret_2026
+```
+
+### **Validación de IP:**
+```php
+// Solo permite localhost por defecto
+$allowedIPs = ['127.0.0.1', '::1', 'localhost'];
+```
+
+### **Autenticación SSE:**
+```php
+// En sse_events.php
+requireAuthentication(); // Usa sesión PHP
+```
+
+## 📊 Eventos disponibles
+
+### `connected`
+- Se envía cuando cliente se conecta exitosamente
+- Data: `{ timestamp: unix_timestamp }`
+
+### `new_message`
+- Se envía cuando llega mensaje nuevo de WhatsApp
+- Data:
+  ```json
+  {
+    "user_id": 123,
+    "phone_number": "573168950803",
+    "name": "Juan Pérez",
+    "message": "Hola, necesito ayuda",
+    "message_type": "text",
+    "timestamp": "2026-01-27 10:30:00"
+  }
+  ```
+
+### `new_conversation`
+- Se envía cuando se detecta nueva conversación
+- Data:
+  ```json
+  {
+    "user_id": 124,
+    "phone_number": "573168950804",
+    "name": "María García",
+    "message_count": 1,
+    "timestamp": "2026-01-27 10:35:00"
+  }
+  ```
+
+### `heartbeat`
+- Se envía cada 30 segundos
+- Data: `{ timestamp: unix_timestamp }`
+- Mantiene conexión viva
+
+## 🚀 Cómo probar
+
+### 1. **Verificar que SSE funciona:**
+```bash
+curl -N http://localhost/api/sse_events.php
+```
+
+Deberías ver:
+```
+event: connected
+data: {"timestamp":1738000000}
+
+event: heartbeat
+data: {"timestamp":1738000030}
+```
+
+### 2. **Simular un push interno:**
+```bash
+curl -X POST http://localhost/api/push_event.php \
+  -H "Content-Type: application/json" \
+  -H "X-Push-Token: internal_push_secret_2026" \
+  -d '{
+    "event_type": "new_message",
+    "data": {
+      "user_id": 123,
+      "phone_number": "573168950803",
+      "message": "Test message"
+    },
+    "target_user_id": "all"
+  }'
+```
+
+### 3. **Ver eventos en navegador:**
+- Abrir `conversations.php`
+- Abrir DevTools → Console
+- Deberías ver: `✅ SSE conectado: {...}`
+- Enviar mensaje de prueba desde WhatsApp
+- Verás: `📨 Nuevo mensaje (SSE): {...}`
+
+## 🐛 Troubleshooting
+
+### **SSE no conecta:**
+1. Verificar que `api/sse_events.php` es accesible
+2. Verificar que sesión está activa (login requerido)
+3. Revisar logs del servidor
+
+### **Eventos no llegan:**
+1. Verificar permisos de escritura en `/uploads/`
+2. Verificar que `push_event.php` es accesible desde localhost
+3. Revisar logs de webhook
+
+### **Reconexión constante:**
+1. Verificar timeout del servidor (debe ser > 60s)
+2. Verificar que nginx/apache no tiene buffer activo
+3. Revisar límites de conexiones persistentes
+
+## ⚙️ Configuración avanzada
+
+### **Cambiar token de seguridad:**
+```bash
+# .env o config
+PUSH_TOKEN=tu_token_super_secreto_aqui
+```
+
+### **Aumentar timeout SSE:**
+```php
+// En sse_events.php
+set_time_limit(300); // 5 minutos
+```
+
+### **Cambiar frecuencia de revisión:**
+```php
+// En sse_events.php, cambiar:
+sleep(2); // A valor deseado (1-5 segundos)
+```
+
+## 📈 Monitoreo
+
+### **Ver eventos en tiempo real:**
+```bash
+tail -f /ruta/uploads/events_global.json
+```
+
+### **Contar conexiones activas:**
+```bash
+netstat -an | grep :80 | grep ESTABLISHED | wc -l
+```
+
+### **Ver logs de push:**
+```bash
+tail -f /var/log/apache2/error.log | grep pushSSEEvent
+```
+
+## 🔄 Migración desde polling
+
+El sistema es compatible hacia atrás. Si SSE falla:
+- Polling sigue funcionando como backup
+- No se pierden mensajes
+- Usuario no nota diferencia (solo latencia mayor)
+
+Para deshabilitar polling completamente:
+```javascript
+// En conversations.php, comentar:
+// setInterval(() => this.loadNotifications(), 15000);
+```
+
+## 📝 Notas importantes
+
+1. **Archivos temporales:** Los eventos se guardan en `/uploads/events_{user_id}.json`
+2. **Limpieza automática:** Solo se mantienen últimos 50 eventos por usuario
+3. **Broadcast:** Eventos se envían a todos los operadores conectados
+4. **No duplicación:** Verificación de IDs previene mensajes duplicados
+5. **Graceful degradation:** Sistema funciona con o sin SSE
+
+## 🎉 Resultado final
+
+**Antes:**
+- Mensajes aparecen después de 7-15 segundos
+- Múltiples peticiones constantes
+- Recarga completa de lista y conversaciones
+
+**Ahora:**
+- Mensajes aparecen en < 1 segundo
+- Una conexión persistente + backup ligero
+- Solo actualiza la conversación afectada
+- UI más fluida y responsive