Servicio de Acortamiento de URL Full-Stack

## 🚀 Servicio de Acortamiento de URLs - Aplicación Full-Stack ### 📋 Resumen del Proyecto Construir un servicio de acortamiento de URLs full-stack, listo para producción, con un frontend moderno y accesible y una API backend RESTful robusta. La aplicación debe manejar el ciclo de vida completo de los enlaces acortados: creación, redirección, seguimiento, gestión y expiración. Priorizar rendimiento, seguridad y una experiencia de usuario excepcional en todos los dispositivos. --- ### 🛠️ Stack Tecnológico **Frontend:** - HTML5 semántico con atributos ARIA para accesibilidad (cumplimiento WCAG 2.1 AA) - CSS3 con Custom Properties de CSS (variables), Flexbox y CSS Grid - JavaScript vanilla (ES2022+) usando arquitectura modular (ES Modules) - Sin frameworks pesados - mantener el bundle ligero y rápido **API Backend:** - Diseño de API RESTful siguiendo la especificación OpenAPI 3.0 - Formato de solicitud/respuesta JSON con códigos de estado HTTP apropiados - Configuración CORS para solicitudes de origen cruzado - Limitación de tasa por IP y por clave de API **Librerías (CDN o empaquetadas):** - Generación de códigos QR (ej., `qrcode.js` o `qr-creator`) - Librería de gráficos para analíticas (ej., Chart.js o alternativa ligera) - Selector de fecha para expiración (ej., `flatpickr`) - Sistema de notificaciones toast (construido a medida, sin dependencias) --- ### 🎨 Frontend - Requisitos de UI/UX **Diseño y Layout:** - Diseño limpio y minimalista con una sección hero que presenta un **campo de entrada de URL grande y prominente** centrado en la página - Implementar un **interruptor de modo oscuro/claro** con detección de preferencia del sistema (`prefers-color-scheme`) y persistencia en `localStorage` - Usar un sistema de diseño consistente: escala tipográfica, tokens de espaciado, paleta de colores - Micro-animaciones y transiciones suaves (fundidos, deslizamientos hacia arriba, ondas en botones) para todos los elementos interactivos - Estados de carga esqueleto para contenido asíncrono (analíticas, tabla de historial) **Diseño Responsive:** - Enfoque mobile-first con breakpoints en 480px, 768px, 1024px y 1440px - Objetivos táctiles amigables (mínimo 44×44px) - Menú de navegación plegable en móvil (menú hamburguesa con animación) - Tipografía fluida usando `clamp()` **Accesibilidad:** - Soporte completo de navegación por teclado (orden de tabulación, captura de foco en modales) - Anuncios de lector de pantalla para contenido dinámico (regiones `aria-live`) - Indicadores de foco visibles en todos los elementos interactivos - Ratios de contraste de color suficientes (mínimo 4.5:1 para texto) - Soporte de movimiento reducido (`prefers-reduced-motion`) --- ### ⚙️ Funcionalidades Principales #### 1. Motor de Acortamiento de URLs - Campo de entrada prominente con texto de marcador de posición y retroalimentación de validación en tiempo real - **Validación de URL**: Verificar protocolo válido (`http://`, `https://`), estructura de dominio adecuada y rechazar URLs malformadas usando tanto regex como el constructor `URL` - **Saneamiento de URL**: Eliminar parámetros de seguimiento (UTM, fbclid, gclid), eliminar barras redundantes, normalizar protocolo y mayúsculas - Auto-insertar `https://` si no se proporciona protocolo - Mostrar la URL acortada inmediatamente después de la creación con una animación de éxito - **Acortamiento de URLs por lotes**: Permitir a los usuarios pegar múltiples URLs (una por línea) y acortarlas todas a la vez #### 2. Soporte de Alias Personalizados - Campo de alias personalizado opcional (ej., `short.ly/mi-marca`) - Verificación de disponibilidad en tiempo real mientras el usuario escribe (llamada API con debounce, 300ms) - Reglas de validación de alias: alfanumérico, guiones y guiones bajos solamente; 3–30 caracteres; lista negra de palabras reservadas (ej., `admin`, `api`, `login`, `static`) - Mensajes de error claros si el alias está ocupado o es inválido #### 3. Generación de Códigos QR - Generar automáticamente un código QR para cada URL acortada al momento de la creación - Modal/panel de código QR con opciones para: - Descargar como PNG (alta resolución, 1024×1024) - Descargar como SVG (vectorial, escalable) - Personalizar colores de primer plano/fondo - Añadir un pequeño logo superpuesto en el centro (opcional) - Asegurar que los códigos QR codifiquen la URL acortada completa y sean escaneables en tamaños pequeños #### 4. Seguimiento de Clics y Panel de Analíticas - Rastrear cada redirección con los siguientes puntos de datos: - Marca de tiempo (UTC) - País y ciudad (mediante API de geolocalización IP) - Tipo de dispositivo (móvil, tableta, escritorio) - Sistema operativo y navegador (mediante análisis de User-Agent) - URL de referencia - Visitante único vs. recurrente (mediante cookie/huella digital) - **Panel de Analíticas** por enlace incluyendo: - Contadores de clics totales y clics únicos - Gráfico de líneas de clics a lo largo del tiempo (filtrable: últimas 24h, 7d, 30d, 90d, todo el tiempo) - Mapa de distribución geográfica o gráfico de barras (top 10 países) - Desglose por dispositivo/SO/navegador (gráficos de dona o pastel) - Tabla de principales referidores - Mapa de calor de clics por día de la semana y hora del día - Resumen de analíticas agregadas en el panel principal (total de enlaces, total de clics, enlace más popular) #### 5. Expiración de Enlaces - Selector de fecha/hora de expiración opcional al crear un enlace - Soporte de ajustes preestablecidos: 1 hora, 24 horas, 7 días, 30 días, fecha personalizada - Mostrar una cuenta regresiva o insignia de "expira en X" en enlaces activos - Desactivar automáticamente enlaces expirados y mostrar una página amigable de "Este enlace ha expirado" en intentos de redirección - Permitir a los usuarios extender o eliminar la expiración en enlaces existentes #### 6. Protección con Contraseña - Interruptor de contraseña opcional al crear un enlace - Si está habilitado, mostrar una página de entrada de contraseña antes de redirigir a la URL de destino - Hash de contraseñas en el servidor usando bcrypt o Argon2 (nunca almacenar texto plano) - Limitar la tasa de intentos de contraseña (máximo 5 por minuto por IP) con mensajes de bloqueo - Indicador visual (icono de candado 🔒) en enlaces protegidos con contraseña en la vista de historial #### 7. Copiar al Portapapeles - Botón de copiar con un clic junto a cada URL acortada - Usar la API del Portapapeles (`navigator.clipboard.writeText()`) con respaldo a `document.execCommand('copy')` - Confirmación visual: el icono del botón cambia a una marca de verificación ✅ con un tooltip/toast de "¡Copiado!" que se descarta automáticamente después de 2 segundos - Soporte de atajos de teclado (ej., `Ctrl+Shift+C` para copiar el enlace creado más recientemente) #### 8. Historial y Gestión de URLs - Tabla/cuadrícula de historial persistente de todas las URLs acortadas (almacenadas en `localStorage` para invitados, base de datos para usuarios autenticados) - Cada entrada muestra: URL original (truncada con tooltip), URL corta, fecha de creación, contador de clics, estado (activo/expirado/protegido con contraseña) y botones de acción - **Búsqueda**: Búsqueda de texto completo en URLs originales, alias y etiquetas - **Filtrado**: Por estado (activo, expirado, protegido), rango de fechas, rango de contador de clics y etiquetas - **Ordenamiento**: Por fecha de creación, contador de clics, alfabéticamente (ascendente/descendente) - **Paginación o scroll infinito** para historiales grandes (25 elementos por página) - **Acciones masivas**: Seleccionar múltiples enlaces para eliminar, desactivar o exportar como CSV/JSON - **Etiquetas/Etiquetado**: Permitir a los usuarios añadir etiquetas personalizadas para organizar enlaces (ej., "marketing", "social", "campaña-q4") --- ### 🔒 Requisitos de Seguridad - Saneamiento de entradas tanto en cliente como en servidor para prevenir ataques XSS - Protección CSRF en todos los endpoints de API que cambian estado - Validar y sanear destinos de redirección para prevenir vulnerabilidades de redirección abierta (lista blanca de protocolos permitidos, bloquear esquemas `javascript:`, `data:`, `file:`) - Implementar cabeceras de Política de Seguridad de Contenido (CSP) - Limitación de tasa: máximo 20 creaciones de enlaces por minuto por IP; máximo 100 solicitudes de API por minuto - Cabeceras HTTP seguras: `X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security` - Nunca exponer IDs internos; usar nanoid o UUID para identificadores públicos de enlaces --- ### ⚡ Requisitos de Rendimiento - Objetivos de puntuación Lighthouse: Rendimiento >90, Accesibilidad >95, Buenas Prácticas >95, SEO >90 - Carga diferida de gráficos de analíticas y activos no críticos - Debounce en todas las entradas de búsqueda y validación - Usar `IntersectionObserver` para animaciones basadas en scroll y carga diferida - Minimizar reflows y repaints; usar `transform` y `opacity` de CSS para animaciones - Cachear respuestas de API donde sea apropiado (ej., datos de analíticas con TTL de 60s) - Las redirecciones deben resolverse en menos de 100ms en el servidor --- ### 🧪 Manejo de Errores y Casos Límite - Mensajes de error elegantes para: fallos de red, tiempos de espera de API, URLs inválidas, alias duplicados, errores de servidor (500), límite de tasa excedido (429) - Detección offline: mostrar un banner cuando el usuario pierde conectividad y poner en cola acciones para reintentar - Manejar URLs extremadamente largas (hasta 2048 caracteres) sin romper el layout - Manejar correctamente nombres de dominio internacionalizados (IDN) con Unicode - Ilustraciones de estado vacío para cuando el usuario no tiene enlaces o datos de analíticas --- ### 📦 Entregables 1. Código fuente completo y bien comentado con una estructura de carpetas clara 2. `README.md` con instrucciones de configuración, documentación de API y lista de funcionalidades 3. Tabla de referencia de endpoints de API (método, ruta, parámetros, formato de respuesta) 4. Un modo `demo` con datos de muestra precargados para vista previa inmediata 5. Responsive en Chrome, Firefox, Safari y Edge (últimas 2 versiones) --- > **Nota:** Construir esto de forma incremental - comenzar con el flujo principal de acortamiento (entrada → validar → acortar → mostrar → copiar), luego añadir códigos QR, analíticas, alias personalizados, expiración, protección con contraseña y el panel completo de historial. Asegurar que cada funcionalidad esté completamente operativa y probada antes de pasar a la siguiente.