Taller 11: Monitoreo de Colas en Tiempo Real - Resumen Ejecutivo

Extensión del panel web con dashboard de monitoreo de colas usando Server-Sent Events (SSE) y eventos AMI para control en tiempo real

📊 Taller 11: Monitoreo de Colas en Tiempo Real - Resumen Ejecutivo

🏗️ Arquitectura del Sistema

La extensión del panel web seguirá una arquitectura orientada a eventos en tiempo real:

Stack Tecnológico

Frontend:

React 19 + Next.js 15
Zustand (estado global)
Server-Sent Events (SSE)
Recharts (gráficos)
shadcn/ui (componentes)

Backend:

Next.js API Routes
asterisk-manager
Event filtering
WebSocket fallback

Tiempo Real:

SSE para eventos AMI
Reconexión automática
Heartbeat cada 30s

📡 Eventos AMI a Capturar

Eventos Críticos del Sistema

QueueMemberStatus

Estado de agente

idle: Disponible
inuse: Ocupado
paused: Pausado
unavailable: No disponible

QueueCallerJoin

Llamada entra a cola

Queue: nombre de la cola
Position: posición en cola
CallerIDNum: número llamante

AgentCalled

Agente siendo contactado

Queue: cola origen
Interface: agente llamado
CallerIDNum: número llamante

AgentConnect

Agente contesta

Queue: cola
Interface: agente
HoldTime: tiempo en espera

AgentComplete

Llamada finaliza

Queue: cola
Interface: agente
TalkTime: duración conversación
Reason: razón terminación

QueueCallerAbandon

Llamante cuelga

Queue: cola
Position: posición que tenía
HoldTime: tiempo esperado

⚙️ Configuración AMI Especializada

Crear Usuario AMI para Dashboard

Agregar en /etc/asterisk/manager.conf:

; === USUARIO ESPECIALIZADO PARA DASHBOARD DE COLAS ===
[dashboard_colas]
secret = DashboardColas2025!

; Permisos mínimos necesarios
read = agent,call
write = agent

; Filtros de eventos - SOLO eventos de colas
eventfilter(action(include),name(QueueMemberStatus)) =
eventfilter(action(include),name(AgentCalled)) =
eventfilter(action(include),name(AgentConnect)) =
eventfilter(action(include),name(AgentComplete)) =
eventfilter(action(include),name(QueueCallerJoin)) =
eventfilter(action(include),name(QueueCallerAbandon)) =
eventfilter(action(include),name(QueueMemberAdded)) =
eventfilter(action(include),name(QueueMemberRemoved)) =
eventfilter(action(include),name(QueueMemberPause)) =

; Denegar otros eventos para reducir tráfico
eventfilter(action(exclude),name(*)) =

; Acceso solo desde localhost
deny = 0.0.0.0/0.0.0.0
permit = 127.0.0.1/255.255.255.0

🖥️ Funcionalidades del Dashboard

Panel Principal de Monitoreo

✅ Estado de Colas

Tiempo Real:

Llamadas en espera
Tiempo promedio de espera
SLA actual del día
Estado de cada cola

✅ Control de Agentes

Gestión Completa:

Ver estado (disponible/ocupado/pausado)
Pausar/despausar desde web
Agregar/quitar de colas
Tiempo en estado actual

✅ Llamadas Activas

Monitoreo Live:

Quién atiende a quién
Duración de llamada actual
Cola de origen
Botón para colgar (opcional)

✅ Métricas del Día

KPIs en Tiempo Real:

Llamadas atendidas/abandonadas
Tiempo promedio de respuesta
Service Level por cola
Distribución de llamadas por agente

✅ Notificaciones

Alertas Visuales:

Cola saturada (>5 esperando)
Agente hace timeout
SLA bajo umbral
Sistema desconectado

✅ Gráficos Trend

Visualización Avanzada:

Llamadas por hora
Tiempo de espera trend
Comparativa de colas
Heatmap de ocupación

🧩 Estructura de Componentes

Frontend Architecture

src/
├── app/
│   ├── dashboard/
│   │   └── colas/
│   │       ├── page.tsx              # Página principal
│   │       ├── components/
│   │       │   ├── QueueCard.tsx     # Tarjeta de cola
│   │       │   ├── AgentList.tsx     # Lista de agentes
│   │       │   ├── MetricsPanel.tsx  # Panel de métricas
│   │       │   ├── CallsList.tsx     # Llamadas activas
│   │       │   ├── QueueChart.tsx    # Gráficos trend
│   │       │   └── AlertsPanel.tsx   # Panel de alertas
│   │       └── loading.tsx
│   └── api/
│       └── ami/
│           ├── queue-events/
│           │   └── route.ts          # SSE endpoint
│           ├── pause-agent/
│           │   └── route.ts          # Pausar/despausar
│           ├── queue-status/
│           │   └── route.ts          # Estado actual
│           └── add-remove-agent/
│               └── route.ts          # Agregar/quitar de cola
├── stores/
│   └── queueStore.ts                 # Estado global con Zustand
├── hooks/
│   ├── useSSE.ts                     # Hook para SSE
│   ├── useQueueMetrics.ts            # Hook para métricas
│   └── useAMIActions.ts              # Hook para acciones AMI
└── types/
    └── queue.ts                      # TypeScript types

Estado Global con Zustand

interface QueueStore {
  // Estado
  queues: Queue[]
  agents: Agent[]
  activeCalls: ActiveCall[]
  metrics: DayMetrics
  isConnected: boolean

  // Acciones
  updateQueueStatus: (queueName: string, status: QueueStatus) => void
  updateAgentStatus: (agentId: string, status: AgentStatus) => void
  addActiveCall: (call: ActiveCall) => void
  removeActiveCall: (callId: string) => void
  updateMetrics: (metrics: Partial<DayMetrics>) => void

  // AMI Actions
  pauseAgent: (agentId: string, queueName: string) => Promise<void>
  unpauseAgent: (agentId: string, queueName: string) => Promise<void>
  addAgentToQueue: (agentId: string, queueName: string) => Promise<void>
  removeAgentFromQueue: (agentId: string, queueName: string) => Promise<void>
}

🔧 Implementación con Prompts

Prompt Tipo para Extensiones

Necesito agregar [FUNCIONALIDAD] al dashboard de colas de Asterisk.

Contexto:
- Panel Next.js 15 con App Router
- Zustand para estado global
- SSE para eventos AMI en tiempo real
- Ya implementado: estado de colas, agentes, pausar/despausar

Nueva funcionalidad:
[DESCRIBIR REQUERIMIENTO ESPECÍFICO]

Tecnologías disponibles:
- Recharts para gráficos
- shadcn/ui para componentes UI
- Zustand para manejo de estado
- TanStack Query para caché
- Lucide React para iconos

Estructura del proyecto:
- API Routes: src/app/api/ami/
- Componentes: src/components/
- Store: src/stores/queueStore.ts
- Página principal: src/app/dashboard/colas/page.tsx
- Hooks: src/hooks/
- Types: src/types/

Por favor genera:
1. Código del componente React
2. Modificaciones necesarias en queueStore.ts
3. API route si es necesario
4. TypeScript types
5. Integración en página principal
6. Hook personalizado si aplica

Estilo de código:
- TypeScript strict
- Componentes funcionales con hooks
- shadcn/ui para UI consistency
- Manejo de errores con toast
- Loading states apropiados

Ejemplos de Funcionalidades a Implementar

📊 Gráfico de Llamadas por Hora

Mostrar tendencia de llamadas entrantes en las últimas 24 horas con Recharts

🔔 Sistema de Alertas

Notificaciones push cuando una cola supera el umbral de espera

📱 Vista Móvil

Dashboard responsivo optimizado para tablets y móviles

🎯 SLA Monitor

Medidor visual del Service Level Agreement por cola

📋 Reportes Exportables

Generar reportes PDF/Excel de métricas del día

🌙 Modo Oscuro

Toggle entre tema claro y oscuro con persistencia

🧪 Pruebas del Sistema

Plan de Verificación

# 1. Verificar conexión SSE
curl -N http://localhost:3000/api/ami/queue-events

# 2. Monitorear eventos AMI
sudo asterisk -rx "manager show connected"

# 3. Generar eventos de prueba
sudo asterisk -rx "queue add member PJSIP/1001 to cola-ventas"
sudo asterisk -rx "queue pause member PJSIP/1001 queue cola-ventas"

# 4. Verificar logs del panel
pm2 logs panel-asterisk | grep AMI

Checklist de Funcionalidades

Conexión SSE: Indicador “Conectado” en verde
Estado en tiempo real: Login agente → Ver cambio inmediato
Control desde web: Click “Pausar” → Verificar en CLI
Métricas actualizadas: Generar llamadas → Ver números cambiar
Reconexión automática: Reiniciar Asterisk → Se reconnecta
Notificaciones: Cola saturada → Alerta visual
Performance: < 100ms latencia en eventos
Móvil responsive: Funciona en tablet/móvil

⚡ Mejores Prácticas

Optimización de Performance

🔄 Reconexión Automática

Si se pierde conexión SSE, reintenta cada 5 segundos con backoff exponencial

💓 Heartbeat System

Ping cada 30 segundos para detectar conexiones zombie

🚨 Error Handling

Toast notifications para errores con botón de reintento

⚡ Optimistic Updates

UI actualiza inmediatamente, rollback si falla

💾 Caché Inteligente

React Query para cachear estado inicial y reducir llamadas

🐛 Debug Mode

Logs detallados de eventos AMI para troubleshooting

Configuración de Producción

// Configuración por ambiente
const config = {
  development: {
    SSE_RETRY_INTERVAL: 1000,
    HEARTBEAT_INTERVAL: 10000,
    DEBUG_MODE: true
  },
  production: {
    SSE_RETRY_INTERVAL: 5000,
    HEARTBEAT_INTERVAL: 30000,
    DEBUG_MODE: false
  }
}

📚 Recursos de Aprendizaje

Documentación Técnica

📖 Asterisk AMI Events

Documentación oficial de eventos AMI disponibles

docs.asterisk.org/Latest_API/AMI_Events

🌊 Server-Sent Events

Guía completa de SSE en Next.js App Router

nextjs.org/docs/app/api-reference

🐻 Zustand Documentation

Estado global simple y eficiente para React

zustand-demo.pmnd.rs

📊 Recharts Examples

Biblioteca de gráficos para React

recharts.org/examples

Tutoriales Complementarios

WebSockets vs SSE: Cuándo usar cada tecnología
AMI Security: Mejores prácticas de seguridad
React Performance: Optimización de renders
TypeScript Patterns: Patrones avanzados para APIs

🎯 Casos de Uso Reales

Escenarios de Implementación

🚀 Próximos Pasos

🎓 Continuación del Aprendizaje

Una vez completado este taller, tendrás las bases para:

Crear dashboards personalizados según necesidades específicas
Integrar con sistemas externos (CRM, ticketing)
Implementar funcionalidades avanzadas (wallboards, reportes)
Escalar el sistema para múltiples sucursales

👉 Explorar Casos de Uso Avanzados

¡Dashboard en Tiempo Real Listo!

¡El ecosistema Asterisk + Web moderno está a tu disposición! 🚀

03-voip-protocolos-codecs