Serviço de Encurtamento de URL Full-Stack

## 🚀 Serviço de Encurtamento de URL - Aplicação Full-Stack ### 📋 Visão Geral do Projeto Construa um serviço de encurtamento de URL full-stack, pronto para produção, com um frontend moderno e acessível e uma API backend RESTful robusta. A aplicação deve lidar com o ciclo de vida completo dos links encurtados: criação, redirecionamento, rastreamento, gerenciamento e expiração. Priorize desempenho, segurança e uma experiência de usuário excepcional em todos os dispositivos. --- ### 🛠️ Stack de Tecnologias **Frontend:** - HTML5 semântico com atributos ARIA para acessibilidade (conformidade WCAG 2.1 AA) - CSS3 com Custom Properties (variáveis), Flexbox e CSS Grid - JavaScript Vanilla (ES2022+) usando arquitetura modular (ES Modules) - Sem frameworks pesados - mantenha o bundle leve e rápido **Backend API:** - Design de API RESTful seguindo a especificação OpenAPI 3.0 - Formato de requisição/resposta JSON com códigos de status HTTP adequados - Configuração de CORS para requisições de origens cruzadas - Limitação de taxa por IP e por chave de API **Bibliotecas (CDN ou empacotadas):** - Geração de QR Code (ex.: `qrcode.js` ou `qr-creator`) - Biblioteca de gráficos para análises (ex.: Chart.js ou alternativa leve) - Seletor de data para expiração (ex.: `flatpickr`) - Sistema de notificações toast (construído sob medida, sem dependência) --- ### 🎨 Frontend - Requisitos de UI/UX **Layout e Design:** - Design limpo e minimalista com uma seção hero apresentando um **campo de entrada de URL grande e proeminente** centralizado na página - Implemente um **alternador de modo escuro/claro** com detecção de preferência do sistema (`prefers-color-scheme`) e persistência em `localStorage` - Use um sistema de design consistente: escala tipográfica, tokens de espaçamento, paleta de cores - Microanimações e transições suaves (fade-ins, slide-ups, ripples em botões) para todos os elementos interativos - Estados de carregamento skeleton para conteúdo assíncrono (análises, tabela de histórico) **Design Responsivo:** - Abordagem mobile-first com breakpoints em 480px, 768px, 1024px e 1440px - Alvos de toque amigáveis (mínimo 44×44px) - Menu de navegação recolhível no mobile (menu hambúrguer com animação) - Tipografia fluida usando `clamp()` **Acessibilidade:** - Suporte completo à navegação por teclado (ordem de tabulação, captura de foco em modais) - Anúncios de leitor de tela para conteúdo dinâmico (regiões `aria-live`) - Indicadores de foco visíveis em todos os elementos interativos - Índices de contraste de cores suficientes (mínimo 4.5:1 para texto) - Suporte a movimento reduzido (`prefers-reduced-motion`) --- ### ⚙️ Funcionalidades Principais #### 1. Motor de Encurtamento de URL - Campo de entrada proeminente com texto de placeholder e feedback de validação em tempo real - **Validação de URL**: Verifique protocolo válido (`http://`, `https://`), estrutura de domínio adequada e rejeite URLs malformadas usando tanto regex quanto a API do construtor `URL` - **Sanitização de URL**: Remova parâmetros de rastreamento (UTM, fbclid, gclid), remova barras redundantes, normalize protocolo e maiúsculas/minúsculas - Pré-insira automaticamente `https://` se nenhum protocolo for fornecido - Exiba a URL encurtada imediatamente após a criação com uma animação de sucesso - **Encurtamento em lote**: Permita que os usuários colem múltiplas URLs (uma por linha) e encurte todas de uma vez #### 2. Suporte a Alias Personalizado - Campo de alias personalizado opcional (ex.: `short.ly/minha-marca`) - Verificação de disponibilidade em tempo real enquanto o usuário digita (chamada de API com debounce, 300ms) - Regras de validação de alias: alfanumérico, hífens e sublinhados apenas; 3–30 caracteres; lista negra de palavras reservadas (ex.: `admin`, `api`, `login`, `static`) - Mensagens de erro claras se o alias estiver em uso ou for inválido #### 3. Geração de QR Code - Gere automaticamente um QR Code para cada URL encurtada após a criação - Modal/ painel de QR Code com opções para: - Baixar como PNG (alta resolução, 1024×1024) - Baixar como SVG (vetorial, escalável) - Personalizar cores de primeiro plano/fundo - Adicionar um pequeno logotipo sobreposto no centro (opcional) - Garanta que os QR Codes codifiquem a URL encurtada completa e sejam escaneáveis em tamanhos pequenos #### 4. Rastreamento de Cliques e Painel de Análises - Rastreie cada redirecionamento com os seguintes pontos de dados: - Carimbo de data/hora (UTC) - País e cidade (via API de geolocalização por IP) - Tipo de dispositivo (mobile, tablet, desktop) - Sistema operacional e navegador (via análise do User-Agent) - URL de referência - Visitante único vs. recorrente (via cookie/fingerprint) - **Painel de Análises** por link incluindo: - Contadores de cliques totais e cliques únicos - Gráfico de linhas de cliques ao longo do tempo (filtrável: últimas 24h, 7d, 30d, 90d, todo o período) - Mapa de distribuição geográfica ou gráfico de barras (top 10 países) - Detalhamento por dispositivo/SO/navegador (gráficos de rosca ou pizza) - Tabela de principais referências - Mapa de calor de cliques por dia da semana e hora do dia - Visão geral agregada de análises no painel principal (total de links, total de cliques, link mais popular) #### 5. Expiração de Link - Seletor opcional de data/hora de expiração ao criar um link - Suporte a predefinições: 1 hora, 24 horas, 7 dias, 30 dias, data personalizada - Exiba uma contagem regressiva ou um selo de "expira em X" nos links ativos - Desative automaticamente links expirados e mostre uma página amigável de "Este link expirou" em tentativas de redirecionamento - Permita que os usuários estendam ou removam a expiração de links existentes #### 6. Proteção por Senha - Alternância opcional de senha ao criar um link - Se ativada, mostre uma página de entrada de senha antes de redirecionar para a URL de destino - Faça hash das senhas no servidor usando bcrypt ou Argon2 (nunca armazene texto simples) - Limite a taxa de tentativas de senha (máx. 5 por minuto por IP) com mensagens de bloqueio - Indicador visual (ícone de cadeado 🔒) em links protegidos por senha na visualização de histórico #### 7. Copiar para a Área de Transferência - Botão de copiar com um clique ao lado de cada URL encurtada - Use a API de Área de Transferência (`navigator.clipboard.writeText()`) com fallback para `document.execCommand('copy')` - Confirmação visual: o ícone do botão muda para uma marca de verificação ✅ com uma dica/toast "Copiado!" que desaparece automaticamente após 2 segundos - Suporte a atalhos de teclado (ex.: `Ctrl+Shift+C` para copiar o link criado mais recentemente) #### 8. Histórico e Gerenciamento de URLs - Tabela/grid persistente de histórico de todas as URLs encurtadas (armazenadas em `localStorage` para visitantes, banco de dados para usuários autenticados) - Cada entrada exibe: URL original (truncada com dica), URL curta, data de criação, contagem de cliques, status (ativo/expirado/protegido por senha) e botões de ação - **Busca**: Busca em texto completo nas URLs originais, aliases e tags - **Filtragem**: Por status (ativo, expirado, protegido), intervalo de datas, intervalo de contagem de cliques e tags - **Ordenação**: Por data de criação, contagem de cliques, alfabeticamente (crescente/decrescente) - **Paginação ou rolagem infinita** para históricos grandes (25 itens por página) - **Ações em lote**: Selecione múltiplos links para excluir, desativar ou exportar como CSV/JSON - **Tags/Rótulos**: Permita que os usuários adicionem tags personalizadas para organizar links (ex.: "marketing", "social", "campanha-q4") --- ### 🔒 Requisitos de Segurança - Sanitização de entrada tanto no cliente quanto no servidor para prevenir ataques XSS - Proteção CSRF em todos os endpoints de API que alteram estado - Valide e sanitize destinos de redirecionamento para prevenir vulnerabilidades de redirecionamento aberto (lista branca de protocolos permitidos, bloqueie esquemas `javascript:`, `data:`, `file:`) - Implemente cabeçalhos de Política de Segurança de Conteúdo (CSP) - Limitação de taxa: máx. 20 criações de links por minuto por IP; máx. 100 requisições de API por minuto - Cabeçalhos HTTP seguros: `X-Content-Type-Options`, `X-Frame-Options`, `Strict-Transport-Security` - Nunca exponha IDs internos; use nanoid ou UUID para identificadores públicos de links --- ### ⚡ Requisitos de Desempenho - Metas de pontuação Lighthouse: Desempenho >90, Acessibilidade >95, Boas Práticas >95, SEO >90 - Carregamento preguiçoso de gráficos de análises e ativos não críticos - Debounce em todas as entradas de busca e validação - Use `IntersectionObserver` para animações baseadas em rolagem e carregamento preguiçoso - Minimize reflows e repaints; use `transform` e `opacity` do CSS para animações - Armazene em cache respostas de API quando apropriado (ex.: dados de análises com TTL de 60s) - Redirecionamentos devem resolver em menos de 100ms no servidor --- ### 🧪 Tratamento de Erros e Casos Extremos - Mensagens de erro elegantes para: falhas de rede, timeouts de API, URLs inválidas, aliases duplicados, erros de servidor (500), limite de taxa excedido (429) - Detecção offline: mostre um banner quando o usuário perder a conectividade e coloque ações na fila para nova tentativa - Lide com URLs extremamente longas (até 2048 caracteres) sem quebrar o layout - Lide corretamente com nomes de domínio internacionalizados (IDN) e Unicode - Ilustrações de estado vazio para quando o usuário não tiver links ou dados de análises --- ### 📦 Entregáveis 1. Código-fonte completo e bem comentado com uma estrutura de pastas clara 2. `README.md` com instruções de configuração, documentação da API e lista de funcionalidades 3. Tabela de referência de endpoints da API (método, caminho, parâmetros, formato de resposta) 4. Um modo `demo` com dados de exemplo pré-carregados para visualização imediata 5. Responsivo em Chrome, Firefox, Safari e Edge (últimas 2 versões) --- > **Nota:** Construa isso incrementalmente - comece com o fluxo principal de encurtamento (entrada → validar → encurtar → exibir → copiar), depois adicione QR Codes, análises, aliases personalizados, expiração, proteção por senha e o painel completo de histórico. Garanta que cada funcionalidade esteja totalmente funcional e testada antes de passar para a próxima.