Conceitos Fundamentais

​

Visão Geral da Arquitetura

​

Stack Tecnológica

​

Backend

• Java 17 com Spring Boot 3.x
• Spring Security para autenticação
• Spring Data JPA para persistência
• Spring Actuator para monitoramento
• Lombok para redução de boilerplate
• Jackson para serialização JSON

​

Frontend

• React 18 com TypeScript
• Vite como build tool
• Tailwind CSS para estilização
• React Query para gerenciamento de estado
• React Router para navegação
• React Hot Toast para notificações

​

Infraestrutura

• Docker para containerização
• Kubernetes ready
• GitHub Actions para CI/CD
• Evolution API para WhatsApp

​

Evolution API

​

Funcionalidades Principais

​

Configuração por Empresa

interface EvolutionConfig {
  id: number;
  name: string;
  url: string;          // URL da Evolution API
  apiKey: string;       // Chave de autenticação
  instanceName: string; // Nome da instância
  isActive: boolean;    // Status de ativação
  isConnected: boolean; // Status de conexão
}

​

Sistema de Campanhas

​

Tipos de Campanha

{
  "name": "Promoção Flash",
  "message": "Olá {PrimeiroNome}! Aproveite 50% OFF hoje!",
  "contacts": [...],
  "evolutionUrl": "https://api.evolution.com",
  "evolutionApiKey": "sua-chave",
  "evolutionInstance": "vendas"
}

​

Estados da Campanha

​

Sistema de Filas

​

Arquitetura de Processamento

​

Benefícios

1. Escalabilidade: Múltiplos workers podem processar em paralelo
2. Resiliência: Falhas são tratadas com retry automático
3. Performance: Processamento assíncrono não bloqueia API
4. Controle: Intervalos configuráveis entre mensagens

​

Autenticação e Segurança

​

Sistema de Tokens

interface AuthResponse {
  accessToken: string;
  tokenType: "Bearer";
  companyId: number;
  companyName: string;
  companyEmail: string;
  blockedContactsEnabled: boolean;
  pollCampaignsEnabled: boolean;
  expiresAt: null; // Tokens não expiram
}

​

Níveis de Acesso

​

Contatos Bloqueados

​

Sistema de Bloqueio Inteligente

​

Funcionalidades

• Bloqueio Individual: Via API ou interface
• Importação em Massa: Até 10.000 números por vez
• Verificação Automática: Durante criação de campanhas
• Histórico: Registro de quem e quando bloqueou

​

Estrutura

interface BlockedContact {
  id: number;
  companyId: number;
  phoneNumber: string;
  reason?: string;
  blockedBy: string;
  blockedAt: Date;
  isActive: boolean;
}

​

Integração com Bancos de Dados

​

Fontes de Contatos Dinâmicas

​

Query Builder

1. Seleção de Tabelas: Interface intuitiva
2. Filtros Visuais: Arraste e solte condições
3. Preview: Visualize contatos antes de enviar
4. Variáveis: Mapeie colunas para personalização

​

Monitoramento e Métricas

​

Dashboard em Tempo Real

​

Métricas Principais

• Campanhas Ativas: Em execução no momento
• Campanhas Agendadas: Programadas para futuro
• Total de Mensagens: Contador acumulativo
• Taxa de Sucesso: Percentual de entrega

​

Health Checks

GET /actuator/health
GET /actuator/info

• Status da aplicação
• Conexão com banco de dados
• Disponibilidade do Redis
• Memória e CPU

​

Rate Limiting

​

Proteção contra Sobrecarga

​

Limites Padrão

• Requisições API: 100/minuto por empresa
• Criação de Campanhas: 10/hora
• Mensagens WhatsApp: Baseado na Evolution API
• Importação de Contatos: 10.000 por vez

​

Webhooks e Notificações

​

Sistema de Callbacks

{
  "event": "campaign.completed",
  "campaignId": 123,
  "companyId": 456,
  "stats": {
    "sent": 1000,
    "failed": 5,
    "duration": "00:15:32"
  }
}

​

Notificações WhatsApp

• Campanha concluída
• Erros críticos
• Instância desconectada

​

Boas Práticas

​

Próximos Passos

​

Automações por Segmentação

• Isolamento: filas Redis e workers dedicados (automation_message_queue, automation_scheduled_queue, automation_retry_queue).
• Entidades: Automation, AutomationRun, AutomationSentLog (deduplicação).
• Deduplicação:
  • NEVER: sem filtro de históricos.
  • ONCE: envia uma única vez por contato enquanto a automação existir.
  • COOLDOWN_DAYS: evita reenvios a um contato dentro de uma janela de X dias.
• Limite por execução: sendLimitPerRun para restringir o volume por run.
• Agendamento: DAILY, WEEKLY, MONTHLY, CRON com timeOfDay e timezone.
• Mensagens: suporte a TEXT, MEDIA, AUDIO e POLL (enquetes).
• Personalização: variáveis padrão e customizadas provenientes do resultado da query, através do mesmo mecanismo das campanhas.
• Teste unitário: endpoint específico para envio isolado, sem criação de run, útil para validação rápida da mensagem.