# 📘 Arquitectura Técnica: Panel de Administración Asterisk

## 📋 Resumen Ejecutivo

El **Panel de Administración Asterisk** es una aplicación web moderna construida con **Next.js 15** que proporciona una interfaz gráfica completa para administrar y monitorear un servidor Asterisk PBX mediante **AMI (Asterisk Manager Interface)**.

---

## 🛠️ Stack Tecnológico

### Frontend
- **Next.js 15.2.4** - Framework React con App Router
- **React 19** - Biblioteca UI
- **TypeScript 5.8** - Tipado estático
- **Tailwind CSS 4** - Framework CSS
- **shadcn/ui** - Componentes UI
- **TanStack Query 5** - Gestión de estado del servidor

### Backend
- **Node.js 20+** - Runtime
- **Better Auth 1.2** - Autenticación
- **Drizzle ORM 0.41** - ORM para PostgreSQL
- **asterisk-manager 0.2** - Cliente AMI

---

## 🏗️ Arquitectura del Sistema

```
NAVEGADOR → Next.js Server → AMI Manager → ASTERISK
                ↓
          PostgreSQL (panel_asterisk + aulaswitch)
```

### Flujo de Datos en Tiempo Real (SSE)

1. Cliente abre `EventSource("/api/ami/events")`
2. Servidor crea `ReadableStream` SSE
3. AMI emite evento → EventEmitter → SSE → Cliente
4. Frontend actualiza UI reactivamente

---

## 📦 Módulos Principales

### 1. AMI Manager (`/src/lib/ami-manager.ts`)

Gestiona conexión con Asterisk:
- Singleton pattern
- EventEmitter para broadcasting
- Reconexión automática
- Funciones helper: `executeAmiAction()`, `getPJSIPEndpointDetails()`

### 2. API Routes

- `/api/ami/events` - SSE para eventos en tiempo real
- `/api/ami/endpoints` - Lista de endpoints PJSIP
- `/api/ami/action` - Ejecutar acciones AMI
- `/api/reportes/cdr` - Reportes CDR con filtros
- `/api/reportes/cel` - Reportes CEL
- `/api/users` - CRUD de usuarios

### 3. Dashboard (`/dashboard`)

Monitoreo en tiempo real con hooks personalizados:
- `useAmiConnection()` - Estado de conexión
- `useExtensions()` - Estado de extensiones
- `useAmiEvents()` - Consumo de SSE
- `useCallOperations()` - Originar/colgar llamadas

---

## 🔌 Integración con Asterisk

### Eventos AMI Procesados

| Evento | Acción |
|--------|--------|
| `PeerStatus` | Actualizar estado de extensión |
| `Newchannel` | Agregar canal activo |
| `Hangup` | Remover canal |
| `ContactStatusDetail` | Actualizar latencia |

### Acciones AMI Ejecutadas

| Acción | Propósito |
|--------|-----------|
| `PJSIPShowEndpoints` | Listar endpoints |
| `Originate` | Originar llamada |
| `Hangup` | Colgar canal |

---

## 🔐 Sistema de Autenticación

### Roles y Permisos

| Rol | Permisos |
|-----|----------|
| **superAdmin** | Acceso total, gestiona admins |
| **admin** | Gestiona usuarios, ve reportes |
| **user** | Solo visualización |

### Flujo
1. Usuario ingresa credenciales en `/sign-in`
2. Better Auth valida contra tabla `account`
3. Crea sesión en tabla `session`
4. Retorna cookie de sesión
5. Middleware valida en cada request

---

## 🗄️ Base de Datos

### `panel_asterisk` (Usuarios del Panel)
- `user` - Usuarios
- `account` - Credenciales
- `session` - Sesiones activas

### `aulaswitch` (Datos de Asterisk)
- `cdr` - Call Detail Records
- `cel` - Channel Event Logging

---

## ✅ Funcionalidades Implementadas

### Dashboard
- ✅ Monitoreo de extensiones/troncales en tiempo real
- ✅ Visualización de latencia
- ✅ Filtros por estado
- ✅ Originar/colgar llamadas
- ✅ Ver detalles de endpoint

### Reportes
- ✅ CDR: Tabla paginada con filtros avanzados
- ✅ CEL: Eventos detallados de llamadas
- ✅ Exportación a CSV
- ✅ Métricas agregadas

### Gestión de Usuarios
- ✅ CRUD completo
- ✅ Sistema de roles
- ✅ Búsqueda y filtrado

---

## 🚀 Funcionalidades Futuras

### Corto Plazo
1. Gestión de extensiones PJSIP desde el panel
2. Gestión de troncales SIP
3. Editor de dialplan visual
4. Gestión de colas (Queues)
5. Constructor de IVR
6. Reproductor de grabaciones
7. Notificaciones en tiempo real

### Mediano Plazo
8. Dashboard de métricas avanzadas
9. Gestión de voicemail
10. Gestión de conferencias
11. Monitoreo de canales activos
12. Blacklist/Whitelist
13. Integración con CRM

### Largo Plazo
14. Softphone WebRTC integrado
15. Análisis de calidad (QoS)
16. Backup automático
17. Multi-tenancy
18. API REST pública
19. App móvil
20. Inteligencia artificial

---

## 📥 Instalación Rápida

```bash
# Clonar repositorio
git clone https://github.com/giandiego/panel-admin-asterisk.git
cd panel-admin-asterisk

# Instalar dependencias
pnpm install

# Configurar .env
cp _example_env .env
nano .env

# Aplicar esquema de BD
pnpm db:push

# Crear super admin
pnpm db:seed:super-admin

# Iniciar en desarrollo
pnpm dev
```

Accede a: **http://localhost:3000**

---

## 🔗 Complemento con Asterisk

El panel se complementa con Asterisk del Taller 8:

1. **AMI** proporciona eventos y control en tiempo real
2. **PostgreSQL** almacena CDR/CEL generados por Asterisk
3. **Panel** consulta CDR/CEL para reportes
4. **Panel** ejecuta acciones AMI para control remoto

### Flujo Completo

```
Usuario marca → Asterisk procesa → CDR/CEL a PostgreSQL
                     ↓
              AMI emite eventos
                     ↓
              Panel recibe vía SSE
                     ↓
         Dashboard actualiza en tiempo real
```

---

## 🎯 Casos de Uso

### 1. Monitoreo de Call Center
- Ver agentes disponibles en tiempo real
- Métricas de llamadas atendidas/perdidas
- Tiempo promedio de atención
- Alertas de colas saturadas

### 2. Auditoría de Llamadas
- Reportes CDR con filtros avanzados
- Búsqueda de llamadas específicas
- Exportación para contabilidad
- Reproducción de grabaciones

### 3. Gestión Remota
- Administrar extensiones sin acceso SSH
- Originar llamadas de prueba
- Colgar canales problemáticos
- Ver estado de troncales

### 4. Soporte Técnico
- Diagnosticar problemas de conectividad
- Ver latencia de endpoints
- Analizar eventos CEL de llamadas fallidas
- Verificar registro de extensiones

---

## 🔒 Seguridad

### Mejores Prácticas Implementadas

✅ Autenticación con Better Auth  
✅ Hash de contraseñas con bcrypt  
✅ Validación de entrada con Zod  
✅ Protección CSRF  
✅ Roles y permisos granulares  
✅ AMI solo accesible desde localhost  
✅ Variables de entorno para secretos  
✅ Sesiones con cookies HTTP-only

### Recomendaciones Adicionales

- Usar HTTPS en producción (Nginx + Let's Encrypt)
- Configurar firewall (ufw) para limitar acceso
- Rotar credenciales periódicamente
- Implementar rate limiting
- Logs de auditoría de acciones administrativas
- Backup automático de base de datos

---

## 📊 Métricas de Rendimiento

- **Tiempo de carga inicial**: < 2s
- **Actualización SSE**: < 100ms
- **Consulta CDR (1000 registros)**: < 500ms
- **Acción AMI**: < 200ms
- **Conexiones concurrentes**: 100+ usuarios

---

## 🤝 Contribución

El proyecto está abierto a contribuciones:

1. Fork del repositorio
2. Crear rama feature (`git checkout -b feature/nueva-funcionalidad`)
3. Commit cambios (`git commit -m 'Agregar nueva funcionalidad'`)
4. Push a la rama (`git push origin feature/nueva-funcionalidad`)
5. Abrir Pull Request

---

## 📄 Licencia

MIT License - Ver archivo LICENSE para más detalles

---

## 📞 Soporte

- **GitHub Issues**: https://github.com/giandiego/panel-admin-asterisk/issues
- **Email**: soporte@aulautil.com
- **Documentación**: https://docs.aulautil.com

---

**Desarrollado con ❤️ para la comunidad Asterisk**