Pular para o conteúdo principal

Feature: Análise de Sentimento

Introdução ao documento​

Este documento descreve a funcionalidade de análise de sentimento de textos utilizando Google Gemini API.

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 análise de sentimento permite processar textos (geralmente comentários de NPS) e extrair automaticamente um resumo estruturado com pontos positivos e negativos. Utiliza Google Gemini API para processamento de linguagem natural e cache para otimizar performance e custos.

Atores envolvidos​

  • Administrador: Usuário que visualiza análises de sentimento no dashboard
  • Sistema: Processa textos via API Gemini e armazena resultados em cache
  • Frontend React: Consome API e exibe resultados formatados

Pré-condições​

  • Google Gemini API configurada com GEMINI_API_KEY válida
  • Cache Laravel configurado e operacional
  • Aplicação com acesso à internet para chamadas à API Gemini

Fluxo principal​

  1. Frontend envia texto para análise

    • Usuário visualiza comentários de NPS no dashboard
    • Frontend coleta textos e envia para /api/v1/sentiment
    • Request inclui: text (texto a analisar), key (chave única para cache), refresh (opcional)

  2. Sistema verifica cache

    • Controller verifica se existe cache para a chave fornecida
    • Se cache existe e refresh = false, retorna resultado cacheado
    • Se cache não existe ou refresh = true, prossegue para análise

  3. Análise via Gemini API

    • Sistema constrói prompt estruturado solicitando resumo com pontos positivos e negativos
    • Chama Google Gemini API com modelo gemini-2.5-pro
    • Recebe resposta formatada do modelo

  4. Armazenamento em cache

    • Resultado é armazenado no cache usando a chave fornecida
    • Cache inclui texto original e resultado da análise
    • Permite reutilização sem nova chamada à API

  5. Retorno ao frontend

    • Sistema retorna resultado formatado em JSON
    • Frontend exibe resumo, pontos positivos e negativos
    • Componente React formata e apresenta dados visualmente

Fluxos alternativos​

Cache hit (dados já existem)​

  • Sistema encontra cache válido para chave e texto
  • Retorna resultado imediatamente sem chamar Gemini API
  • Reduz latência e custos de API

Forçar atualização​

  • Usuário solicita refresh explícito (refresh: true)
  • Sistema ignora cache e sempre chama Gemini API
  • Útil quando texto foi atualizado ou análise precisa ser refeita

Erro na API Gemini​

  • Se Gemini API falhar, erro é retornado ao frontend
  • Frontend exibe mensagem de erro ao usuário
  • Cache não é atualizado em caso de erro

Texto muito longo​

  • Gemini API tem limites de tokens
  • Sistema não valida tamanho máximo antes de enviar
  • API pode retornar erro se texto exceder limites

Regras de negócio​

  1. Cache por chave única: Cada combinação de texto e chave gera cache independente
  2. Validação de entrada: Texto e chave são obrigatórios, refresh é opcional (default: false)
  3. Formato de saída: Resposta sempre segue template estruturado (RESUMO, PONTOS POSITIVOS, PONTOS NEGATIVOS)
  4. Limite de caracteres: Resumo limitado a 2000 caracteres conforme prompt
  5. Idempotência: Mesma chave e texto sempre retornam mesmo resultado (a menos que refresh seja solicitado)

Estados possíveis​

  • Pendente: Análise solicitada, aguardando processamento
  • Processando: Chamada à Gemini API em andamento
  • Concluído: Análise finalizada e cacheada
  • Erro: Falha na chamada à API ou processamento

Endpoints envolvidos​

  • POST /api/v1/sentiment - Endpoint principal para análise de sentimento
    • Request body: { text: string, key: string, refresh?: boolean }
    • Response: { sentiment: string }
    • Integração: Google Gemini API via Gemini::generativeModel()

Dados afetados​

  • Cache Laravel: Armazena resultados de análise por chave
  • Nenhuma tabela de banco: Feature é stateless, dados apenas em cache

Integrações externas​

  • Google Gemini API: Processamento de linguagem natural
    • Modelo: gemini-2.5-pro
    • Autenticação: API Key via GEMINI_API_KEY