Pular para o conteúdo principal

Feature: Gestão de Inscrições

Introdução ao documento​

Este documento descreve a funcionalidade de gestão e visualização de inscrições de cursos.

Versionamento​

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

Referencial teórico​

Visão geral​

A feature de gestão de inscrições permite visualizar e exportar dados de inscrições de cursos. Dados são provenientes do Redshift (data warehouse), processados e cacheados para otimizar performance. Sistema suporta visualização no dashboard administrativo e exportação de dados.

Atores envolvidos​

  • Administrador: Visualiza e exporta dados de inscrições
  • Facilitador Limitado: Visualiza inscrições com colunas restritas (conforme configuração)
  • Sistema: Processa dados do Redshift e mantém cache atualizado

Pré-condições​

  • Conexão com Redshift configurada e operacional
  • Cache Laravel configurado
  • Jobs de atualização de cache executados periodicamente
  • Permissões adequadas para visualização (roles Spatie)

Fluxo principal​

  1. Atualização de cache (background)

    • Job RefreshData ou InscricoesCacheJob é executado
    • Conecta ao Redshift e busca dados da tabela inscricoes
    • Comprime dados com gzip para otimizar armazenamento
    • Armazena no cache Laravel com chave inscricoes55

  2. Visualização no dashboard

    • Administrador acessa página de inscrições no admin panel
    • Frontend React consome /api/v1/inscricoes
    • API retorna dados comprimidos do cache
    • Frontend descomprime e exibe dados em tabela

  3. Exportação de dados

    • Administrador solicita exportação via ExportFileController
    • Sistema gera arquivo com dados de inscrições
    • Arquivo é disponibilizado para download

Fluxos alternativos​

Cache vazio​

  • Se cache não existe, API retorna 204 No Content
  • Frontend exibe mensagem informando ausência de dados
  • Administrador pode disparar atualização manual de cache

Dados desatualizados​

  • Cache pode estar desatualizado se jobs não executaram recentemente
  • Administrador pode forçar atualização via endpoint /api/v1/cache/inscricoes (requer autenticação)
  • Job é disparado assincronamente para atualizar cache

Permissões limitadas​

  • Usuário com role Facilitador_Limitado vê apenas colunas configuradas
  • Configuração de colunas visíveis em VisibleColumnsConfig
  • Por padrão, email é oculto para facilitadores limitados

Regras de negócio​

  1. Dados somente leitura: Inscrições são consultadas do Redshift, não editadas no dashboard
  2. Cache comprimido: Dados são sempre comprimidos com gzip antes de armazenar
  3. Atualização assíncrona: Cache é atualizado via jobs, não bloqueia requisições
  4. Controle de colunas: Facilitadores limitados veem apenas colunas permitidas
  5. Filtro por ano: Jobs podem processar dados de ano específico via parâmetro year

Estados possíveis​

  • Cache atualizado: Dados disponíveis e atualizados
  • Cache vazio: Nenhum dado disponível
  • Cache desatualizado: Dados existem mas podem estar antigos
  • Processando: Job de atualização em andamento

Endpoints envolvidos​

  • GET /api/v1/inscricoes - Retorna dados de inscrições comprimidos

    • Response: Dados gzip (Content-Encoding: gzip)
    • Status: 200 (com dados) ou 204 (cache vazio)

  • GET /api/v1/cache/inscricoes - Dispara atualização de cache (autenticado)

    • Query params: year (opcional)
    • Response: Confirmação de início do job

  • GET /admin/exportar/inscritos - Exporta dados de inscrições (admin panel)

Dados afetados​

  • Cache Laravel: Chave inscricoes55 armazena dados comprimidos
  • Redshift: Tabela inscricoes (somente leitura)
  • Nenhuma tabela MySQL: Dados não são persistidos localmente

Integrações externas​

  • Redshift (PostgreSQL): Data warehouse para consultas analíticas
    • Tabela: inscricoes
    • Acesso: Via jobs assíncronos

Jobs relacionados​

  • RefreshData::refreshInscricoes(): Atualiza cache de inscrições
  • InscricoesCacheJob: Job dedicado para atualização de cache
    • Suporta parâmetro year para filtrar por ano