siip-available-ips/CHANGELOG.md

# Changelog

Todos los cambios notables en este proyecto serán documentados en este archivo.

El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.0.0/),
y este proyecto adhiere a [Semantic Versioning](https://semver.org/lang/es/).

---

## [1.6.1] - 2025-12-08

### 🚀 Mejoras de UX/UI
- Reorganización de elementos del formulario: Checkboxes agrupados y dropdown de límite al final.
- **Mensajes de progreso persistentes**: Los mensajes de estado ("Validando por ping...", "Consultando...") ahora permanecen visibles durante todo el proceso.
- **Badge de IP**: Ahora muestra "No disponible" en rojo cuando una IP está en uso por ping o validación de sitios (antes mostraba "Cliente" en verde).
- **Estadísticas reales**: Los contadores de "IPs Disponibles" y "IPs en Uso" ahora reflejan exactamente lo que se muestra en la tabla después de la validación progresiva.

### 🐛 Bug Fixes
- **Límite de IPs**: Corregido bug donde la validación progresiva ignoraba el límite seleccionado (5, 10, 20) y validaba todas.
- **Indicadores de carga**: Corregido problema donde el spinner y mensajes desaparecían prematuramente antes de terminar la validación progresiva.

---

## [1.6.0] - 2025-12-06

### ✨ Añadido
- **Sistema de Validación Multi-Capa de IPs**: Implementación completa de 4 capas de validación para garantizar IPs 100% disponibles.
  - **Capa 1 - Filtrado UISP**: Filtra IPs de dispositivos registrados en UISP
  - **Capa 2 - Filtrado CRM**: Filtra IPs de servicios suspendidos/finalizados
  - **Capa 3 - Validación por Búsqueda de Sitios**: Detecta IPs de clientes activos usando `/sites/search?type=subscriber`
  - **Capa 4 - Verificación por Ping**: Detecta dispositivos de terceros (opcional)
- **IpValidator.php**: Nueva clase para validación de IPs usando búsqueda de sitios en UISP.
- **Validación Progresiva en Frontend**: Las IPs se validan una por una antes de mostrarse en la tabla.
- **Endpoint API `action=validate`**: Nuevo endpoint para validar IPs individuales.
- **Parámetro `type=subscriber`**: Búsqueda específica en sitios de clientes para evitar falsos positivos.

### 🔧 Mejorado
- **CrmService.php**: Filtrado mejorado de servicios suspendidos y finalizados.
  - Mapeo de IPs a sitios bloqueados
  - Extracción de `unmsClientSiteId` de servicios
  - Logging detallado del proceso de filtrado
- **IpSearchService.php**: 
  - Integración con CrmService para filtrado de servicios
  - Parámetro `suspended=true` en API de UISP para incluir dispositivos suspendidos
  - Extracción de todas las IPs de `ipAddressList` además de IP principal
- **public.php**: 
  - Handler para `action=validate` con carga correcta de configuración
  - Integración de validación progresiva en frontend
- **Frontend JavaScript**:
  - Función `runProgressiveValidation()` para validar IPs progresivamente
  - Función `updateRowStatus()` para actualizar estado de filas
  - Solo renderiza IPs que pasan todas las validaciones
  - Mejor feedback visual durante validación

### 🐛 Corregido
- **Bug de variable `$config` indefinida**: Corregido cargando configuración dentro del handler de validación.
- **Falsos positivos en búsqueda de sitios**: Solucionado agregando `type=subscriber` al endpoint.
- **IPs secundarias no detectadas**: Ahora se extraen todas las IPs de `ipAddressList`.
- **Servicios suspendidos/finalizados mostrando IPs disponibles**: Filtrado completo por estado de servicio CRM.

### 📝 Documentación
- **README.md**: Sección completa sobre "Sistema de Validación Multi-Capa de IPs" con:
  - Descripción detallada de cada capa
  - Diagrama de flujo completo de validación
  - Casos de uso y ejemplos
- **Logs mejorados**: Mensajes detallados en cada capa de validación para debugging.

### 🎯 Casos de Uso Resueltos
- ✅ IPs de servicios finalizados ya no aparecen como disponibles
- ✅ IPs de servicios suspendidos ya no aparecen como disponibles
- ✅ IPs de clientes activos (no en `/devices/ips`) son detectadas y filtradas
- ✅ IPs secundarias de dispositivos son detectadas correctamente
- ✅ Dispositivos de terceros son detectados con ping opcional

## [1.5.1] - 2025-12-01

### ✨ Añadido
- **Funcionalidad de Edición en Editor Avanzado**: Completado el CRUD con la capacidad de editar segmentos existentes.
  - Botón "✏️ Editar" en cada fila de la tabla de segmentos
  - Formulario se pre-llena con datos del segmento seleccionado
  - Modo visual de edición con título y botón dinámicos
  - Campo de número de segmento se deshabilita durante edición (no se puede cambiar el ID)

### 🔧 Mejorado
- **Función `addSegmentToTable()`**: Ahora maneja tanto creación como actualización de segmentos.
- **Funciones Helper**: Agregadas funciones auxiliares para gestión de rangos:
  - `clearRangeContainers()` - Limpia contenedores de rangos
  - `addInitialRangeWithData()` / `addFinalRangeWithData()` - Agregan rangos con datos pre-cargados
  - `resetForm()` - Resetea formulario al modo agregar
  - `editSegment()` - Carga datos del segmento en el formulario
- **UX del Editor**: Scroll automático al inicio del formulario al editar.
- **Validación**: Verificación de duplicados solo en modo creación, no en edición.

### 🎨 Interfaz
- Botón de editar con estilo azul distintivo
- Indicadores visuales claros de modo edición vs. agregar
- Mensajes de éxito diferenciados ("agregado" vs. "actualizado")

## [1.5.0] - 2025-11-27

### ✨ Añadido
- **Configuración Avanzada de IPs Administrativas por Segmento**: Sistema completo de gestión de rangos administrativos personalizados por segmento.
  - Editor visual protegido por contraseña
  - Configuración JSON por segmento
  - Múltiples rangos iniciales y finales por segmento
  - Interfaz amigable para gestionar rangos
- **Botón de Configuración Avanzada** (⚙️): Acceso rápido al editor desde la interfaz principal.
- **Modal de Autenticación**: Protección por contraseña para acceso al editor.
- **Fallback Inteligente**: Segmentos no configurados en JSON usan automáticamente rangos globales.
- **Indicador Visual de Modo**: Badge que muestra si está activo "Rangos Personalizados" o "Rangos Globales".
- **Logs de Depuración**: Mensajes detallados en consola para diagnosticar clasificación de IPs.

### 🔧 Mejorado
- **AdminRangeHelper.php**: Nueva clase helper para procesar configuración JSON por segmento.
- **IpSearchService.php**: Lógica mejorada con soporte para rangos personalizados y fallback.
  - Configuración inyectada en constructor para consistencia
  - Rangos dinámicos en lugar de hardcodeados
  - Logs de depuración opcionales con `debugMode`
- **Validación de Cambios**: Advertencia al salir del editor con cambios sin guardar.
- **Tabla de Resultados**: Eliminada columna redundante "Tipo de IP" en escritorio, badge ahora aparece junto a la IP.
- **Inicialización de Datos**: `editorData` se carga correctamente al inicio para asegurar que los rangos personalizados se apliquen inmediatamente.

### 🐛 Corregido
- **Error de Escape de Strings**: Reemplazado `addslashes()` por `json_encode()` para variables PHP en JavaScript, evitando errores de sintaxis.
- **Guardado de Configuración**: Implementada escritura directa a `config.json` debido a limitaciones del SDK de UCRM.
- **Clasificación de IPs en Frontend**: Función `getIpType()` ahora respeta rangos personalizados por segmento, no solo globales.
- **Carga de Configuración Personalizada**: Corregido bug crítico donde `editorData` se inicializaba vacío y nunca se cargaba hasta abrir el editor, causando que los rangos personalizados fueran ignorados.
- **Comparación de Segmentos**: Mejorada robustez con conversión explícita a string y trim para evitar fallos por espacios o tipos de datos.

### 🎨 Interfaz
- Editor visual completo con formularios dinámicos
- Tabla de segmentos configurados
- Agregar/eliminar rangos en tiempo real
- Diseño responsive con soporte para temas claro/oscuro
- Valor por defecto de 254 para rangos finales (optimización UX)

## [1.4.0] - 2025-11-27

### ✨ Añadido
- **Rangos de IPs Administrativas Configurables**: Ahora puedes configurar qué rangos de IPs se consideran administrativas mediante 4 campos numéricos en la configuración del plugin (inicio/fin de rango inicial y final), en lugar de tener valores fijos (1-30 y 254).

### 🔧 Mejorado
- **Flexibilidad**: Permite adaptar la clasificación de IPs según las necesidades específicas de cada red.
- **Backend y Frontend**: Toda la lógica de clasificación ahora usa configuración dinámica.

## [1.3.3] - 2025-11-27

### ✨ Añadido
- **Modo Claro/Oscuro**: Botón toggle (☀️/🌙) en esquina superior derecha para cambiar entre temas con persistencia en localStorage.
- **Tema Claro**: Paleta de colores profesional para uso diurno con fondo claro y textos oscuros.

### 🔄 Mejorado
- **Tabla Móvil**: Optimizada para pantallas pequeñas ocultando columna "Tipo de IP" y mostrando el badge bajo la dirección IP (3 columnas en lugar de 5).
- **Límite por Defecto**: Cambiado a 5 IPs para búsquedas más rápidas.
- **Tipografía**: Direcciones IP más destacadas con fuente más grande y negrita.

## [1.3.2] - 2025-11-26

### ✨ Añadido
- **Botón de Cancelar Verificación**: Nuevo botón dinámico que aparece durante la verificación por ping, permitiendo detener el proceso en cualquier momento mientras se conservan los resultados ya obtenidos.

### 🔄 Mejorado
- **Responsividad Móvil**: Optimizada la alineación de checkboxes en dispositivos móviles para una mejor experiencia visual.

## [1.3.1] - 2025-11-26

### 🔄 Refinado
- **Renderizado Secuencial**: Las IPs de cliente aparecen una por una en la tabla conforme se inician sus verificaciones, creando un efecto visual más limpio y ordenado.
- **Limpieza de Resultados**: Si se selecciona un límite (ej. 5 IPs), la tabla solo muestra esas 5 IPs de cliente (más las administrativas), ocultando el resto del segmento.
- **Textos UI**: Actualizados para mayor claridad ("Válida para cliente", "Sólo validada con UISP").

## [1.3.0] - 2025-11-26

### ✨ Añadido
- **Carga Progresiva**: Los resultados de la búsqueda aparecen inmediatamente y la verificación por ping se realiza en segundo plano, actualizando el estado en tiempo real.
- **Feedback Visual Mejorado**: Nuevos iconos de estado (⏳ Verificando, ✅ Disponible, ⚠️ En uso) en la tabla de resultados.
- **Filtro de IPs Administrativas**: Nuevo checkbox para ocultar/mostrar IPs de administración (1-30, 254) al instante.

### 🔄 Mejorado
- **Rendimiento**: La interfaz ya no se bloquea durante la verificación por ping.
- **Experiencia de Usuario**: Se puede ver el progreso de la verificación IP por IP.

---

## [1.2.1] - 2025-11-26

### ✨ Añadido
- **Límite de IPs para verificación**: Nuevo selector para limitar la cantidad de IPs a verificar con ping (5, 10, 20 o Todas)
  - Evita timeouts en segmentos grandes
  - Prioriza IPs de cliente (las administrativas se muestran sin verificar cuando hay límite)
- **Defaults mejorados**: Checkbox de verificación activado por defecto (si está habilitado en config)

### 🔄 Mejorado
- **Optimización de verificación**: Al usar un límite, las IPs administrativas se excluyen del ping para acelerar el proceso
- **Interfaz de usuario**: Feedback visual más claro sobre el límite aplicado

---

## [1.2.0] - 2025-11-26

### ✨ Añadido

#### Verificación por Ping
- **Clase `PingService.php`**: Servicio de verificación de IPs mediante ping
  - Ping paralelo a múltiples IPs simultáneamente (hasta 30 IPs por lote)
  - Timeout configurable (default: 1 segundo)
  - Detección automática de disponibilidad del comando ping
  - Procesamiento en lotes para evitar sobrecarga de red
  - Fallback graceful si ping no está disponible
- **Parámetro de configuración `enablePingVerification`**: Control global de verificación por ping
  - Modo opcional: usuario decide en cada búsqueda
  - Checkbox condicional en frontend (solo visible si está habilitado)
  - Parámetro `verify_ping` en API REST
- **Detección de dispositivos no registrados**: Identifica IPs que responden a ping pero no están en UISP
  - Filtra automáticamente IPs que responden
  - Advertencias en logs para IPs no registradas
  - Estadísticas de ping en respuestas

#### Integración
- **Frontend**: Checkbox "Verificar con ping" (condicional según configuración)
  - Solo visible si `enablePingVerification` está habilitado
  - Integrado en formulario de búsqueda
  - Indicador de progreso durante verificación
- **API REST**: Soporte para parámetro `verify_ping` en ambos endpoints
  - `event.ip_request`: Incluye estadísticas de ping en respuesta
  - `event.ip_check`: Indica si IP específica responde a ping
  - Campo `ping_verified` en todas las respuestas
  - Campo `ping_stats` con métricas detalladas

### 🔄 Mejorado

- **`IpSearchService::buscarIpsDisponibles()`**: Ahora acepta parámetro `$verifyPing`
  - Integración transparente con `PingService`
  - Filtrado automático de IPs que responden
  - Logging detallado de resultados de ping
- **Respuestas de API**: Información enriquecida con datos de ping
  - Estadísticas: total verificado, respondiendo, no respondiendo
  - Tiempo de ejecución de verificación
  - Lista de IPs que responden (posibles conflictos)

### 🔧 Técnico

- **Ping paralelo**: Implementación usando procesos en background
  - Archivos temporales para capturar resultados
  - Espera asíncrona con timeout
  - Limpieza automática de archivos temporales
- **Performance**: Optimizado para grandes rangos de IPs
  - Procesamiento en lotes de 30 IPs
  - Timeout total controlado
  - Mínimo impacto en tiempo de respuesta

---

## [1.1.0] - 2025-11-26

### ✨ Añadido

#### API REST Completa
- **Endpoint `event.ip_request`**: Búsqueda de IPs disponibles en un segmento de red
  - Acepta parámetro `segment` para especificar el tercer octeto (0-255)
  - Retorna lista de IPs disponibles y en uso
  - Filtra automáticamente IPs administrativas (1-30, 254)
  - Incluye contadores de IPs disponibles, en uso y filtradas
- **Endpoint `event.ip_check`**: Verificación de estado de una IP específica
  - Acepta parámetro `ip` con dirección completa (172.16.X.X)
  - Retorna estado: disponible, en uso o desconocido
  - Incluye información del tipo de IP (administrativa vs. cliente)
  - Proporciona recomendaciones de uso
- **Soporte para webhooks**: Habilitado `supportsWebhookEvents: true` en manifest
- **Manejo de peticiones JSON**: Detección automática de Content-Type para API vs Frontend

#### Arquitectura y Código
- **Clase `ApiHandlers.php`**: Manejadores dedicados para eventos de API REST
  - `handleApiRequest()`: Router principal de eventos
  - `handleIpRequest()`: Procesamiento de búsqueda de IPs
  - `handleIpCheck()`: Procesamiento de verificación de IPs
- **Clase `IpSearchService.php`**: Servicio de búsqueda de IPs con lógica de negocio
  - `buscarIpsDisponibles()`: Búsqueda de IPs en segmento específico
  - `obtenerIpsEnUso()`: Obtención de IPs desde API UNMS
  - `isAdminIp()`: Método estático para detectar IPs administrativas
  - `getIpType()`: Método estático para obtener información del tipo de IP
- **Sistema de filtrado de IPs**: Clasificación automática de IPs administrativas vs. cliente
  - Rango administrativo: .1-.30 y .254
  - Rango cliente: .31-.253
  - Etiquetas visuales en frontend
  - Filtrado automático en API REST

#### Documentación
- **README.md completo**: Documentación profesional del plugin
  - Guía de instalación y configuración
  - Documentación completa de API REST
  - Ejemplos de uso en múltiples lenguajes (cURL, PHP, JavaScript, Python)
  - Tabla de códigos de error
  - Troubleshooting y soporte
- **CHANGELOG.md**: Archivo dedicado para control de versiones

### 🔄 Mejorado

- **Separación de responsabilidades**: Lógica de negocio separada en clases dedicadas
- **Manejo de errores mejorado**: Respuestas JSON estructuradas con códigos de error descriptivos
- **Sistema de logging**: Logs más detallados y organizados para debugging
  - Registro de tipo de petición (HTML vs JSON)
  - Logging de eventos API procesados
  - Información de errores con stack traces
- **Compatibilidad dual**: Frontend HTML y API REST funcionan simultáneamente
  - Detección automática del tipo de petición
  - Sin interferencia entre modos
- **Validación de datos**: Validación robusta de parámetros en API
  - Validación de formato de IP
  - Validación de rangos de segmento
  - Mensajes de error descriptivos

### 🔧 Técnico

- **Namespace PHP**: `SiipAvailableIps` para evitar conflictos
- **Manejo global de errores**: Error handler para convertir errores PHP en respuestas JSON
- **Configuración SSL**: Soporte para certificados autofirmados en desarrollo
- **Timeouts configurados**: Timeouts de conexión y ejecución para API UNMS

---

## [1.0.1] - 2025-11-25

### ✨ Añadido

- **Frontend web moderno**: Interfaz de usuario con diseño responsive y atractivo
  - Diseño con gradientes y glassmorphism
  - Tipografía Google Fonts (Inter)
  - Animaciones suaves y micro-interacciones
  - Modo oscuro integrado
- **Búsqueda de IPs por segmento**: Campo de entrada para tercer octeto
- **Función copiar al portapapeles**: Botón de copia rápida para cada IP
  - Feedback visual al copiar
  - Compatible con navegadores modernos
- **Estadísticas en tiempo real**: Contadores de IPs disponibles y en uso
  - Tarjetas de estadísticas visuales
  - Actualización dinámica tras búsqueda
- **Integración con API UNMS**: Conexión directa con UISP Network
  - Obtención de IPs en uso desde dispositivos
  - Soporte para HTTPS
  - Manejo de errores de conexión

### 🔄 Mejorado

- **Conexión con API UNMS**: Optimización de peticiones HTTP
  - Timeouts configurables
  - Mejor manejo de errores de red
  - Logging de respuestas
- **Búsqueda de IPs**: Algoritmo optimizado para comparación de rangos
  - Ordenamiento de IPs por último octeto
  - Cálculo eficiente de IPs disponibles
  - Validación de segmentos (0-255)

### 🐛 Corregido

- Mejoras en la estabilidad de conexión con API UNMS
- Corrección de validación de segmentos fuera de rango
- Fix en ordenamiento de IPs en tabla de resultados

---

## [1.0.0] - 2025-11-25

### ✨ Lanzamiento Inicial

#### Funcionalidades Core
- **Búsqueda básica de IPs**: Funcionalidad principal del plugin
  - Búsqueda en rangos 172.16.X.x
  - Detección de IPs en uso
  - Cálculo de IPs disponibles
- **Integración con UISP CRM**: Plugin nativo para UCRM
  - Instalación vía interfaz de plugins
  - Configuración desde panel de administración
  - Acceso desde menú de reportes
- **Interfaz web básica**: Primera versión del frontend
  - Formulario de búsqueda simple
  - Tabla de resultados
  - Diseño básico responsive

#### Configuración
- **Parámetros de configuración**:
  - Dirección IP/dominio del servidor
  - Token de API UCRM
  - Token de API UNMS (opcional)
  - Modo debug
  - Nivel de logging

#### Integración
- **API UNMS**: Conexión con UISP Network para obtener IPs
- **Sistema de logs**: Archivo `plugin.log` para debugging
- **Compatibilidad**: UCRM 1.0.0+ y UNMS 1.0.0+

---

## Tipos de Cambios

- **✨ Añadido**: Para nuevas funcionalidades
- **🔄 Mejorado**: Para cambios en funcionalidades existentes
- **🐛 Corregido**: Para corrección de bugs
- **🔧 Técnico**: Para cambios técnicos internos
- **🗑️ Eliminado**: Para funcionalidades removidas
- **⚠️ Deprecado**: Para funcionalidades que serán removidas
- **🔒 Seguridad**: Para parches de seguridad

---

## Versionamiento

Este proyecto sigue [Semantic Versioning](https://semver.org/lang/es/):

- **MAJOR** (X.0.0): Cambios incompatibles con versiones anteriores
- **MINOR** (0.X.0): Nueva funcionalidad compatible con versiones anteriores
- **PATCH** (0.0.X): Correcciones de bugs compatibles con versiones anteriores

---

**Última actualización**: 26 de noviembre de 2025