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, y este proyecto adhiere a Semantic Versioning.

---

[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:

• 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