Pular para o conteúdo principal

Feature: Net Promoter Score (NPS)

Introdução ao documento​

Este documento descreve a funcionalidade de visualização e análise de NPS (Net Promoter Score) por produto.

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 NPS permite visualizar dados de Net Promoter Score segmentados por produto (UP Marketing, UP Finanças, Decola MEI, Mulheres em Foco e etc.). Dados são cacheados e atualizados via jobs assíncronos, otimizados com compressão gzip. Sistema suporta análise de sentimento sobre comentários de NPS.

Atores envolvidos​

  • Administrador: Visualiza dados de NPS no dashboard administrativo
  • Sistema: Processa e cacheia dados de NPS
  • Frontend React: Consome APIs e exibe dados em gráficos e tabelas

Pré-condições​

  • Dados de NPS disponíveis e processados
  • Cache Laravel configurado e operacional
  • Jobs de atualização de cache executados periodicamente
  • Permissões adequadas para visualização

Fluxo principal​

  1. Atualização de cache (background)

    • Jobs específicos por produto são executados (NPSUpMarketingCacheJob, NPSUpFinancasCacheJob, etc.)
    • Dados são processados e comprimidos com gzip
    • Armazenados no cache com chaves específicas por produto

  2. Visualização no dashboard

    • Administrador acessa página de NPS no admin panel (/admin/nps)
    • Frontend React consome endpoints específicos por produto
    • Dados são descomprimidos e exibidos em gráficos e tabelas

  3. Análise de sentimento (opcional)

    • Administrador pode solicitar análise de sentimento dos comentários
    • Sistema utiliza feature de análise de sentimento para processar textos
    • Resultados são exibidos junto com dados de NPS

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 via endpoint de cache

Atualização manual​

  • Administrador pode forçar atualização via /api/v1/cache/nps-{produto} (requer autenticação)
  • Job é disparado assincronamente
  • Cache é atualizado sem bloquear requisições

Múltiplos produtos​

  • Cada produto tem endpoint e job dedicados
  • Dados são independentes entre produtos
  • Visualização pode comparar NPS entre produtos

Regras de negócio​

  1. Segmentação por produto: Cada produto tem dados e cache independentes
  2. Dados somente leitura: NPS é consultado, não editado no dashboard
  3. Cache comprimido: Dados sempre comprimidos com gzip
  4. Atualização assíncrona: Cache atualizado via jobs, não bloqueia requisições
  5. Produtos suportados: UP Marketing, UP Finanças, Decola MEI, Mulheres em Foco

Estados possíveis​

  • Disponível: Dados de NPS disponíveis no cache
  • Cache vazio: Nenhum dado disponível
  • Processando: Job de atualização em andamento
  • Desatualizado: Cache existe mas pode estar antigo

Endpoints envolvidos​

Endpoints de leitura (públicos)​

  • GET /api/v1/nps-up-marketing - Dados de NPS UP Marketing
  • GET /api/v1/nps-up-financas - Dados de NPS UP Finanças
  • GET /api/v1/nps-decola-mei - Dados de NPS Decola MEI
  • GET /api/v1/nps-mulheres-em-foco - Dados de NPS Mulheres em Foco

Todos retornam dados comprimidos em gzip (Content-Encoding: gzip) ou 204 se cache vazio.

Endpoints de atualização (autenticados)​

  • GET /api/v1/cache/nps-up-marketing - Atualiza cache UP Marketing
  • GET /api/v1/cache/nps-up-financas - Atualiza cache UP Finanças
  • GET /api/v1/cache/nps-decola-mei - Atualiza cache Decola MEI
  • GET /api/v1/cache/nps-mulheres-em-foco - Atualiza cache Mulheres em Foco

Admin Panel​

  • GET /admin/nps - Página de visualização de NPS no dashboard

Dados afetados​

  • Cache Laravel: Chaves específicas por produto

    • nps-up-marketing
    • nps-up-financas
    • nps-decola-mei
    • nps-mulheres-em-foco

  • Nenhuma tabela local: Dados não são persistidos, apenas cacheados

Jobs relacionados​

  • NPSUpMarketingCacheJob: Atualiza cache de NPS UP Marketing
  • NPSUpFinancasCacheJob: Atualiza cache de NPS UP Finanças
  • NPSDecolaMeiCacheJob: Atualiza cache de NPS Decola MEI
  • NPSMulheresEmFocoCacheJob: Atualiza cache de NPS Mulheres em Foco

Integração com análise de sentimento​

Dados de NPS podem ser utilizados como entrada para análise de sentimento:

  • Comentários de NPS são coletados
  • Enviados para endpoint /api/v1/sentiment
  • Resultado é exibido junto com métricas de NPS