Pular para o conteúdo principal

C4 - Componentes (L3)

Introdução ao documento​

Este documento descreve a arquitetura de componentes do serviço no nível C4 L3.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Escopo​

  • Serviço/app: dhedalos-app-dashboard-laravel

Responsabilidade​

Sistema de dashboard administrativo que fornece:

  • Interface administrativa via Backpack for Laravel
  • API REST para consumo de dados
  • Processamento assíncrono de cache
  • Integração com serviços externos (Gemini, AoVivo, WordPress)
  • Análise de sentimento de textos

Dependências​

  • Banco: MySQL (principal), Redshift/PostgreSQL (analítico)
  • Cache: Laravel Cache (Redis/Memcached/File)
  • Fila: Laravel Queue (Redis/Sync)
  • Storage: Laravel Filesystem (local/S3)
  • Externos: Google Gemini API, AoVivo API, WordPress API

Detalhes de integrações: docs/overview.md

Componentes internos​

Controllers API​

12 controllers responsáveis por endpoints REST:

  • SentimentController: Análise de sentimento via Google Gemini API
  • InscricoesController: Dados de inscrições do Redshift
  • AgendamentoController: Dados de agendamentos
  • NPS Controllers: 4 controllers para NPS por produto (UP Marketing, UP Finanças, Decola MEI, Mulheres em Foco)
  • AoVivoController: Estatísticas de cursos ao vivo via WordPress API
  • AoVivoIntegracaoController: Integração direta com AoVivo API
  • AdminLogsController: Logs administrativos
  • ColunasController: Configuração de colunas visíveis
  • CacheController: Gerenciamento de cache (endpoints autenticados)

Controllers Admin​

24 controllers para painel administrativo Backpack, organizados por funcionalidade:

Relatórios e Dashboards:

  • GeneralController: Dashboard principal
  • AgendaController, FacilitadoresController, NPSController, ProgressoCursoController
  • AquisicaoTrafegoController, EngajamentoController
  • CursoController, TurmaController: Detalhes de curso/turma
  • NewAoVivoController: Cursos ao vivo
  • HistoricoController: Perfil de inscritos

Administração:

  • CacheController, ConfigController, ColunasController: Configurações
  • MaintenanceModeController: Modo de manutenção
  • AccessTokenController: Tokens de acesso
  • AdminLogsController, LogsController: Visualização de logs
  • PermissaoController: Gerenciamento de permissões
  • RoleCrudController, UsuariosController: CRUD de roles e usuários (via Backpack PermissionManager)

Utilitários:

  • ExportFileController: Exportação de dados
  • ALIsController: Parceiros

Services​

2 services para lógica de negócio e integrações:

  • EnrollmentStatsService: Integração com WordPress API para estatísticas de inscrições

    • Métodos: getEnrollmentStats(), getEnrollmentStatsWithShift(), getCycles(), getAvailableCourses(), getAvailableCyclesByCourse()
    • Autenticação via Svc token
    • Cache com TTL variável (1 minuto a 4 horas)

  • AdminLogsService: Processamento de logs administrativos

Jobs​

8 jobs para processamento assíncrono via Laravel Queue:

  • RefreshData: Atualização de cache de inscrições, cursos e agendamentos

    • Conecta ao Redshift (conexão pgsql) para buscar dados
    • Comprime dados com gzip antes de armazenar no cache
    • Métodos: refreshInscricoes(), refreshCursos(), refreshAgendamento()

  • Cache Jobs específicos: 7 jobs dedicados para atualização de cache por domínio

    • InscricoesCacheJob, AgendamentoCacheJob, CursosCacheJob
    • NPSUpMarketingCacheJob, NPSUpFinancasCacheJob, NPSDecolaMeiCacheJob, NPSMulheresEmFocoCacheJob

Models​

4 models Eloquent:

  • User: Usuários do sistema com roles e permissões (Spatie Permissions)

    • Traits: HasRoles, HasApiTokens (Sanctum), CrudTrait (Backpack)

  • MaintenanceMode: Controle de modo de manutenção

  • PlainTextToken: Tokens de acesso simples

  • VisibleColumnsConfig: Configuração de colunas visíveis por usuário

Middlewares​

7 middlewares customizados:

  • ForceJsonResponse: Força resposta JSON em APIs
  • GzipMiddleware: Compressão GZIP de respostas HTTP
  • RedirectIfMaintenanceModeActive: Redireciona se modo manutenção ativo
  • HydrateCacheView: Hidrata cache para views do Backpack
  • RedirectApenasAoVivo: Redirecionamento específico para funcionalidade AoVivo
  • CheckIfAdmin: Verificação de permissão admin
  • ViewLogs: Controle de acesso para visualização de logs

Frontend React​

Frontend React/TypeScript organizado em:

  • Pages: 22 páginas principais correspondentes às rotas do admin
  • Components: Componentes reutilizáveis (ButtonGroup, Calendar, ChartCard, SentimentAnalysis, etc.)
  • Charts: 114 arquivos de componentes de gráficos (Highcharts)
  • Tables: 33 arquivos de componentes de tabelas
  • Contexts: 11 contextos React para gerenciamento de estado (InscricoesContext, NPSContexts, LiveContexts, etc.)
  • Hooks: 25 hooks customizados
  • Types: Definições TypeScript para tipos de dados

Fluxos críticos​

1. Análise de Sentimento​

Frontend → POST /api/v1/sentiment → SentimentController → Gemini API → Cache → Response

O SentimentController recebe texto, verifica cache, e se não existir ou for solicitado refresh, chama a Google Gemini API com prompt estruturado. Resultado é cacheado e retornado ao frontend.

2. Busca de Dados AoVivo via WordPress​

Frontend → GET /api/v1/ao-vivo/* → AoVivoController → EnrollmentStatsService → WordPress API → Cache → Response

O AoVivoController utiliza o EnrollmentStatsService que faz requisições autenticadas ao WordPress API. Dados são cacheados com TTL variável (1 minuto a 4 horas) dependendo do tipo de informação.

3. Integração AoVivo API Direta​

API → GET /api/v1/dhedalos/v1/live/* → AoVivoIntegracaoController → AoVivo API → Cache → Response

O AoVivoIntegracaoController faz requisições diretas à AoVivo API com autenticação Bearer token. Cache com TTL de 30 segundos para dados frequentemente atualizados.

4. Atualização de Cache via Jobs​

Laravel Queue → RefreshData Job → Redshift (pgsql) → Processamento → Compressão GZIP → Laravel Cache

Jobs processam dados do Redshift, comprimem com gzip e armazenam no cache Laravel. Otimiza performance ao evitar consultas diretas ao data warehouse em cada requisição.

5. Autenticação API​

Request → Middleware (auth:sanctum) → User (HasApiTokens) → Controller

Autenticação baseada em Laravel Sanctum. Middleware auth:sanctum verifica token, modelo User utiliza trait HasApiTokens. Decisão arquitetural: docs/adr/0001-architecture-overview.md

Diagrama Mermaid​