Feedback de Clientes

1Visão geral da jornada

A funcionalidade tem três fases na rota raiz /feedback, controladas por um único estado (phase):

1. Conectar canais (phase: "connect"): onboarding. O usuário escolhe de quais canais quer ouvir os clientes.
2. Varredura (phase: "scanning"): a Plataforma sincroniza os feedbacks dos últimos 7 dias dos canais conectados.
3. Painel / Recentes (phase: "dashboard"): o usuário trabalha a fila de feedbacks em formato de baralho (deck) e navega para as telas satélite.

A partir do painel existem as telas satélite: Todos os Feedbacks, Feedbacks Ocultos, Detalhe do Feedback e Gerenciar canais.

1.1 Fluxograma da jornada

Dois recortes da mesma jornada: o caminho feliz (tudo sincroniza e a fila é zerada) e o caminho triste (varredura lenta, resultado parcial, falha total ou perda de conexão).

• Passo / tela
• Decisão
• Estado de sucesso
• Estado de erro / atrito

Caminho feliz

Caminho triste

2Modelo de dados e conceitos

2.1 Feedback (FeedbackItem)

2.2 Status do feedback (flags independentes)

Cada feedback carrega duas flags independentes:

• responded: respondido (true) ou não respondido (false).
• hidden: oculto (true) ou visível (false).

As combinações são todas válidas: um feedback pode estar respondido E oculto ao mesmo tempo. As flags ficam num mapa Record<feedbackId, { responded, hidden }>. Quando as duas voltam a false, a entrada é removida do mapa (estado limpo).

2.3 Seletores (onde cada feedback aparece)

2.4 Reputação (ReputationScore): fora do MVP

A reputação não faz parte do MVP e não é exibida em nenhuma tela. O redesign multi-tela removeu a UI de score (e o filtro "Temas da semana"). O tipo ReputationScore e o cálculo (computeReputation) permanecem na camada de dados apenas para não quebrar o reducer/serviço/testes, mas o valor é ignorado pela interface. Tratar como legado/futuro, não como funcionalidade do MVP.

Quando houver UI de reputação no futuro, o cálculo atual é: total, positivos, negativos, neutros e taxa de positividade; sem feedbacks polarizados, valor neutro (50); faixas crítico (<50), atenção (50 a 69), bom (70 a 84), excelente (>=85).

2.5 Canais suportados (mock atual)

Google Meu Negócio (avaliações com nota), Instagram, Facebook e WhatsApp Business. Apenas Google Meu Negócio usa nota em estrelas; os demais usam comentário ou mensagem.

3Regras de negócio

1. Ao conectar um canal, o sistema sincroniza os feedbacks dos últimos 7 dias.
2. Se o usuário desconectar um canal, todos os feedbacks dele são excluídos da análise (com confirmação por diálogo). As flags dos feedbacks daquele canal também são descartadas.
3. O usuário pode marcar um feedback como respondido ou oculto.
4. A tela inicial apresenta os feedbacks não respondidos e não ocultos, do mais recente para o mais antigo (ordem cronológica).
5. Se não houver feedback não respondido, a tela inicial mostra um empty state (ver tipos no item 6).
6. Os feedbacks ocultos podem ser vistos em Todos os Feedbacks > Feedbacks Ocultos.
7. O usuário pode tornar um feedback oculto visível novamente (no detalhe).
8. O usuário não pode excluir um feedback. O máximo que pode fazer é desconectar o canal de origem.
9. Um feedback tem status respondido ou não respondido e pode estar visível ou oculto (flags independentes, ver 2.2).
10. O usuário pode filtrar por Canal, por Status (respondido ou não respondido) e por Sentimento (positivo, negativo ou neutro) na tela Todos os Feedbacks.
11. Ordem cronológica. No deck (Recentes) a apresentação é sempre do mais recente para o mais antigo. Em Todos os Feedbacks o padrão é o mesmo, mas o usuário pode inverter a ordem por um controle na tela. (No mock, a ordem deriva do relativeTime; na integração real usar um postedAt/timestamp.)
12. No primeiro acesso, se existirem cards a apresentar, o usuário vê uma dica (tutorial) de como funciona o arrastar de cards. O tutorial só aparece na primeira vez em que houver cards. Se na primeira vez já for empty state, mostra o empty state direto e o tutorial fica para quando houver cards.
13. Ao conectar um canal, a conexão deve ser OAuth e ocorrer em aba separada (ver item 11).
14. Quando o usuário clicar em Atualizar (em Recentes ou em Todos), passa pela tela de varredura (loading azul, igual ao onboarding) e, ao voltar ao painel, vê o toast "Feedbacks atualizados.". Os estados atuais (respondido, oculto) persistem: a atualização sincroniza novos feedbacks sem apagar o que já foi tratado. Em Todos, o Atualizar leva o usuário de volta ao painel (Recentes) após a varredura.
15. Perda de conexão com um canal. Se o sistema perde a conexão com um canal conectado (token expirado, revogação de acesso, instabilidade da API), o canal entra em estado de erro (continua na lista de conectados, mas marcado). A plataforma não desconecta sozinha: ela sinaliza e pede reconexão.
    • Tela inicial (Recentes): um alerta no topo informa que a conexão com o(s) canal(is) foi perdida, com atalho para Gerenciar canais.
    • Gerenciar canais: o canal aparece com indicador de erro ("Conexão perdida") e a ação "Reconectar" no lugar de "Desconectar".
    • Os feedbacks já sincronizados desse canal continuam visíveis; só param de receber novidades até reconectar.
    • Reconectar limpa o erro (no produto real, refaz o OAuth do canal em aba separada). Desconectar também limpa o erro e remove os feedbacks do canal.
16. Varredura lenta e tolerância a APIs lentas. A varredura distingue "lento, mas vivo" de "falhou", e não trava a sincronização inteira por causa de um canal lento:
    • Limiar de espera. Até o limiar esperado (configurável, default sugerido ~8s), a varredura mostra o progresso normal (teto 92%) com mensagens rotativas.
    • "Ainda processando". Passado o limiar sem falha, exibe uma mensagem persistente de que ainda está processando, sem fingir 100% e sem tela de erro, mantendo "Voltar para canais" acessível.
    • Backoff automático. Cada canal lento ou instável é re-tentado automaticamente com backoff exponencial e jitter (default: base 1s, fator 2, teto ~10s, até 3 tentativas) antes de ser marcado com erro.
    • Resultado parcial. Se ao menos um canal retornar, o usuário entra no painel com os feedbacks disponíveis e um alerta não bloqueante para os canais que falharam. Só vira tela de erro cheia quando nenhum canal retorna após o backoff.
    • Limiar de espera, número de tentativas e tempo limite por canal são parâmetros configuráveis; os defaults são provisórios e devem ser calibrados com dados reais de latência (ver seção 14).

3.1 Ações sobre o card (deck)

• Arrastar para a direita (ou botão correspondente): marca como respondido.
• Arrastar para a esquerda (ou botão): oculta o feedback.
• Tocar no card: abre o Detalhe para visualizar e gerar resposta com a MIA.

4Mapa de telas e modais

4.1 Telas (com rota)

As três fases da raiz (connect, scanning, dashboard) compartilham a mesma URL /feedback/. A fase vem do estado persistido, não da URL. No desktop, as telas satélite aparecem com a navegação lateral; no mobile, comportam-se como modais com header fixo cobrindo a tela.

Conectar canais (onboarding)

/feedback/ phase=connectConnectChannelsScreen (onboarding)

Aparece sem canais conectados ou antes da 1a varredura. Cada canal é um chip clicável "Conectar"; com pelo menos 1 conectado, "Analisar agora" habilita e leva à varredura.

Varredura (scanning)

/feedback/ phase=scanningScanningScreen + FeedbackVarreduraTemplate?scanSlow=1

Durante a sincronização. Barra de progresso animada com mensagens rotativas, teto 92% até os dados chegarem; contador "X de Y canais".

Feedbacks Recentes (deck)

/feedback/ phase=dashboardRecentesScreen

Após a varredura concluir. Deck no estilo baralho: o card do topo é o ativo (arrastar à direita responde, à esquerda oculta, tocar abre o detalhe). Atalhos para "Todos os feedbacks" e "Gerenciar canais".

Detalhe do Feedback

/feedback/[id]/FeedbackDetailScreen

Ao tocar em um card. Ordem vertical: card do feedback, ações (Ocultar/Mostrar e Marcar como Respondido), resposta da MIA (com "Copiar resposta") e navegação Anterior/Próximo.

Todos os Feedbacks

/feedback/todos/AllFeedbacksScreen

Sempre acessível pelo painel. Lista os visíveis (não ocultos) em ordem cronológica, com filtros (Canal, Status, Sentimento), taxa de resposta e atalho para Feedbacks Ocultos.

Feedbacks Ocultos

/feedback/ocultos/HiddenFeedbacksScreen

A partir de Todos os Feedbacks. Lista os feedbacks com hidden = true; ao abrir o detalhe, o usuário pode torná-los visíveis de novo.

Gerenciar canais

/feedback/canais/ManageChannelsPage (mode manage)

A partir do painel. Reaproveita a tela de conexão em modo "manage": conectar/desconectar reflete na hora (resync ao vivo, preservando flags). Desconectar pede confirmação.

4.2 Modais, overlays e estados (sem URL própria)

Tutorial do deck (3 passos)

DeckTutorialOverlay

Aparece na primeira vez que houver cards no deck. Três passos (Responder, Ocultar, Gerar resposta) com botões "Próximo"/"Entendi" e "Pular tutorial".

Confirmar desconexão

DisconnectChannelDialog

Ao clicar em "Desconectar" um canal. Avisa que os comentários e respostas sugeridas do canal vão sair da análise até você conectar de novo.

Varredura "ainda processando"

tela de varredura (mensagem persistente)?scanSlow=1 (após ~8s)

Sync acima do limiar de espera, sem falha. Mensagem persistente, progresso preso em 92% (nunca finge 100%) e "Voltar para canais" disponível.

Erro de varredura

FeedbackStatePanel (tone danger)?scanError=1

Falha na sincronização (nenhum canal retornou). "Não foi possível concluir a varredura" com "Tentar de novo" e "Voltar para canais".

Empty: sem canais (Recentes)

FeedbackStatePanel (Link2)

Painel sem nenhum canal conectado. "Nenhum canal conectado" com CTA para conectar.

Empty: sem feedbacks no período

FeedbackStatePanel (Inbox)

Canais conectados, mas zero feedbacks em 7 dias. "Nenhum feedback no período".

Empty: tudo em dia

FeedbackStatePanel (PartyPopper)

Todos os feedbacks já tratados. "Tudo em dia por aqui!".

Empty: Todos sem feedbacks / sem filtros

FeedbackStatePanel

Conforme o caso na tela Todos (sem canais, sem visíveis ou sem resultado de filtro). Captura: sem feedbacks visíveis.

Empty: Ocultos vazio

FeedbackStatePanel (EyeOff)

Nenhum feedback oculto. "Nenhum feedback oculto".

Detalhe não encontrado

FeedbackStatePanel (SearchX)

Feedback removido por nova varredura/desconexão. "Feedback não encontrado" com ação de voltar.

Varredura parcial com alerta de canal

painel + alerta não bloqueante?scanPartial=instagram

Ao menos 1 canal ok, outros falharam após backoff. Entra no painel com alerta "Perdemos a conexão com um canal" e atalho Gerenciar canais.

Canal com conexão perdida

RecentesScreen (alerta)?channelError=instagram

Conexão perdida com um canal conectado. Alerta no topo de Recentes; os feedbacks já sincronizados continuam visíveis.

Toast

react-toastify

Notificações transitórias, ex.: "Feedbacks atualizados." após a atualização, e ao copiar resposta no detalhe.

Celebração (confetti)

fireDeckClearedConfetti

Dispara ao zerar a fila de feedbacks em aberto, sobre o estado "Tudo em dia por aqui!". Efeito canvas de chuva de confetes.

5Fluxos detalhados

5.1 Conectar canais (onboarding)

1. Tela com os canais disponíveis. Cada canal é um chip clicável.
2. Ao clicar em "Conectar", o chip mostra estado "Conectando..." e então fica conectado (no produto final, abre fluxo OAuth em aba separada).
3. Ao conectar, a Plataforma sincroniza os feedbacks dos últimos 7 dias do canal.
4. Com pelo menos 1 canal conectado, o botão "Analisar agora" fica habilitado e leva à varredura.

5.2 Varredura (scanning)

1. Barra de progresso animada com mensagens rotativas. O progresso sobe até um teto (92%) enquanto a sincronização não termina, e completa 100% quando os dados chegam.
2. Sincronização por canal. Cada canal conectado sincroniza de forma independente; a varredura acompanha quantos canais já retornaram (X de Y canais).
3. Espera longa ("ainda processando"). Se a sincronização ultrapassa o limiar de espera (~8s) sem ter falhado, a tela troca as mensagens rotativas por uma mensagem persistente e tranquilizadora e mantém o progresso no teto de 92%. "Voltar para canais" continua disponível.
4. Auto-retry com backoff. Lentidão ou falha transitória de um canal dispara novas tentativas automáticas com backoff exponencial e jitter (base 1s, fator 2, teto ~10s, até 3 tentativas) antes de declarar o canal com erro.
5. Conclusão:
   • Sucesso total (todos os canais retornaram): completa 100% e vai para o painel com os feedbacks.
   • Parcial (pelo menos 1 canal retornou e os demais esgotaram tentativas/tempo limite, default 60s): entra no painel mesmo assim, com um alerta não bloqueante para os canais que falharam, reaproveitando o padrão de canal em erro da regra 15.
   • Falha total (nenhum canal retornou após o backoff): mostra o estado de erro de varredura com "Tentar de novo" e "Voltar para canais".
6. Ver a regra de negócio 16 para os parâmetros e a política completa.

5.3 Painel / Feedbacks Recentes (deck)

1. Deck no estilo baralho. O card do topo é o ativo.
2. Ações: arrastar à direita (responder), à esquerda (ocultar), tocar (abrir detalhe).
3. Botão de atualizar no topo: sincroniza novos feedbacks preservando os estados já marcados.
4. Ao esvaziar a fila de feedbacks em aberto, dispara a celebração (confetti) e o estado "Tudo em dia".
5. Atalhos para "Todos os feedbacks" e "Gerenciar canais".

5.4 Detalhe do Feedback

Ordem vertical da tela: card do feedback, ações, resposta da MIA, navegação.

1. Mostra o card completo do feedback.
2. Ações: dois botões lado a lado, Ocultar/Mostrar à esquerda e Marcar como Respondido/Desmarcar à direita.
3. Resposta da MIA: a MIA "pensa" por um instante e revela a sugestão (avatar + badge, texto, "Copiar resposta" e "Ir para o feedback").
4. Navegação: botões Anterior e Próximo (ghost com setas) para percorrer os feedbacks sem voltar à lista, em ordem cronológica. "Anterior" desabilita no primeiro e "Próximo" no último.
5. Origem da navegação. O detalhe sabe de onde foi aberto (via ?from=): Voltar retorna à origem; Anterior/Próximo navega pelo conjunto de Todos (quando origem deck/todos) ou pelos ocultos (quando origem ocultos). A lista é congelada (snapshot) durante a navegação para permitir voltar e corrigir.
6. "Copiar resposta" usa a Clipboard API com fallback. "Ir para o feedback" aparece após copiar.
7. "Ir para o feedback" por canal: para Google, Instagram e Facebook abre a origem (postUrl) em nova aba. Para WhatsApp, leva o usuário para o chat dentro da plataforma já com a resposta gerada pela MIA no input, restando clicar em enviar.

5.5 Todos os Feedbacks

1. Lista os feedbacks visíveis (não ocultos), em ordem cronológica.
2. Filtros: Canal, Status (respondido/não respondido) e Sentimento.
3. Taxa de resposta: bloco com "X de Y respondidos" e barra de progresso, calculada sobre os visíveis.
4. Atalho "Feedbacks Ocultos".

5.6 Feedbacks Ocultos

1. Lista os feedbacks com hidden = true.
2. Ao abrir o detalhe, o usuário pode torná-los visíveis de novo ("Mostrar").

5.7 Gerenciar canais

1. Reaproveita a tela de conexão em modo "manage".
2. Conectar/desconectar reflete na hora (resync ao vivo, preservando flags dos canais que continuam conectados).
3. Botão "Analisar agora" confirma as ações e volta ao painel. O "X" do header fecha a gestão de canais. Desconectar pede confirmação no DisconnectChannelDialog.

6Estados vazios e de erro (catálogo)

Catálogo dos estados de vazio e erro, com a condição que os dispara e a mensagem exibida. As capturas reaproveitam as imagens da galeria 4.2.

Recentes, sem canais

connectedChannelIds = 0

Mensagem: "Nenhum canal conectado" + CTA conectar.

Recentes, sem dados

canais conectados, feedbacks = 0

Mensagem: "Nenhum feedback no período".

Recentes, tudo tratado

feedbacks > 0, fila em aberto = 0

Mensagem: "Tudo em dia por aqui!".

Todos, sem visíveis / sem canais / sem filtro

visible = 0 / filtered = 0

Mensagens: "Nenhum feedback ainda", "Nenhum canal conectado" + CTA, ou "Nenhum feedback para os filtros" + limpar.

Ocultos vazio

hidden = 0

Mensagem: "Nenhum feedback oculto".

Detalhe inexistente

id não está em feedbacks

Mensagem: "Feedback não encontrado" + voltar.

Varredura lenta (ainda processando)

sync acima do limiar, sem falha

Mensagem: "Ainda estamos processando. Alguns canais demoram um pouco mais." (teto 92%).

Varredura parcial

ao menos 1 canal ok, outros falharam

Painel + alerta não bloqueante "Não foi possível sincronizar o canal X" + reconectar.

Varredura falhou

erro na sincronização (nenhum canal)

Mensagem: "Não foi possível concluir a varredura" + tentar / voltar.

7Persistência e sincronização

• Sessão persistida em localStorage na chave biud:feedback-session:v1 (fase, canais, feedbacks, score, último scan, flags).
• Tutorial persistido em biud:feedback-deck-tutorial:v1 ("seen").
• Refresh/atualização preserva o estado: o botão de atualizar re-sincroniza os feedbacks e mantém as flags, descartando apenas as flags de feedbacks que sumiram. Já a primeira varredura do onboarding começa com flags zeradas.
• localStorage indisponível (modo privado/cota): a leitura/escrita falha em silêncio e a sessão volta ao padrão; sem efeito funcional além de não lembrar entre recargas.
• Copiar resposta: usa navigator.clipboard quando disponível (HTTPS ou localhost) e cai num fallback com textarea + execCommand quando o contexto não é seguro.

8Tutorial do deck

Overlay com 3 passos, exibido na primeira vez que houver cards no deck:

1. Responder: "Puxe o card para a direita para marcar um card como respondido."
2. Ocultar: "Não quer mais ver um feedback? É só puxar para a esquerda. Ele sai da listagem de feedbacks. Você ainda poderá encontrá-lo nos Feedbacks Ocultos."
3. Gerar resposta: "Se quiser gerar uma resposta, toque no card para visualizá-lo. A MIA cria uma sugestão pronta para você ajustar e enviar."

Botões "Próximo" / "Entendi" e "Pular tutorial". Respeita prefers-reduced-motion.

9Conexão de canais: comportamento de produto vs. mock

• Produto (esperado): a conexão de cada canal é via OAuth, aberta em aba separada. O usuário autoriza na plataforma de origem (Google, Meta, etc.) e retorna. Os níveis de atrito e os gates de aprovação por canal estão na seção 14.
• Sandbox (atual): o "Conectar" é simulado (delay curto, sem OAuth real) e os feedbacks vêm de um dataset mockado. A camada de serviço (services/) já abstrai a origem: cada integração real vira um adapter que produz FeedbackItem[] sem mexer na UI.

10Edge cases

Status possíveis: Tratado Intencional Conhecido (não tratado) Fora de escopo

10.1 Gatilhos de teste úteis (dev)

• Forçar erro de varredura: /feedback/?scanError=1 (com canal conectado e fase de varredura).
• Forçar varredura lenta ("ainda processando"): /feedback/?scanSlow=1 para atrasar a sincronização além do limiar (~8s).
• Backoff que recupera: /feedback/?scanFlaky=<id> (ex.: instagram). O canal falha nas primeiras tentativas e retorna numa seguinte; conclui em 100% sem marcar erro.
• Resultado parcial: /feedback/?scanPartial=<id>. O(s) canal(is) falham permanentemente; os demais retornam e o usuário entra no painel com alerta de canal em erro.
• Conferir o contador "X de Y canais": conectar 2+ canais e iniciar a análise (scan normal).
• Simular perda de conexão: /feedback/?channelError=<id> com o canal já conectado.
• Rever o tutorial: localStorage.removeItem("biud:feedback-deck-tutorial:v1") e recarregar.
• Resetar a sessão: localStorage.removeItem("biud:feedback-session:v1") e recarregar.
• Ver empty states: desconectar todos os canais (sem canais) ou tratar todos os feedbacks (tudo em dia).

11Status de implementação (mock vs. real)

12Dados a monitorar (para o Analista de Dados)

Hoje a feature não está instrumentada; o que segue é a especificação do que deve ser enviado quando a telemetria for ligada. Toda métrica deve ser cortável pelas dimensões de negócio (porte, segmento, localização).

12.1 Dimensões (cortes de análise)

12.2 Eventos (taxonomia proposta)

12.3 Métricas e KPIs sugeridos

• Adoção: % de empresas que conectaram >=1 canal; média de canais por empresa.
• Ativação: funil conectar canal > concluir varredura > primeira resposta.
• Taxa de resposta: respondidos / total de feedbacks recebidos.
• Tempo até a primeira resposta (quando houver timestamp real).
• Taxa de ocultação: ocultos / total.
• Uso da MIA: % de respostas copiadas após gerar sugestão.
• Recorrência: frequência de "atualizar"; sessões por semana (alimenta WAU).
• Reputação: distribuição de sentimento e evolução do score por segmento e região.
• Saúde da conexão: taxa de sucesso de OAuth por canal; churn de canal.

12.4 Observações de captura

• Eventos de marcar respondido/ocultar devem registrar via (swipe vs. botão).
• feedback_scan_completed deve quebrar a contagem por canal.
• Sentimento e tema (themeId) são dimensões ricas para cruzar com porte e segmento.
• Recomenda-se um identificador de sessão da feature para medir duração e número de feedbacks tratados por sessão.

13Pendências e melhorias conhecidas

• Adicionar postedAt (timestamp) para ordenação cronológica real e tempo relativo vivo.
• Versionar o payload persistido para tolerar mudanças de shape.
• Escopar a sessão por empresa e mover a persistência para o backend.
• Implementar o OAuth real por canal em aba separada.
• Instrumentar a telemetria da varredura tolerante a APIs lentas (feedback_scan_slow, feedback_scan_channel_retried, feedback_scan_partial), que entra junto com a instrumentação geral (seção 12).

14Panorama de integração real por canal

Estimativa de esforço para trocar o mock por integrações reais. Baseado em conhecimento público até início de 2026. Políticas e endpoints mudam com frequência: sempre confirme na documentação oficial antes de planejar a engenharia.

14.1 Resumo (do mais simples ao mais complexo)

14.2 Notas por canal

• Google Play: Reply to Reviews API; reviews.list só traz avaliações recentes (~7 dias); histórico completo via export do Play Console.
• App Store: App Store Connect API (customerReviews + customerReviewResponses), JWT local, histórico amplo, sem App Review.
• Google Meu Negócio: Business Profile APIs; OAuth escopo business.manage; gate principal é a aprovação/quota do Google.
• Mercado Livre: API de dev aberta; mensagens pós-venda e perguntas/respostas com boa cobertura; reviews de produto instáveis.
• iFood: Merchant API com reviews (leitura + resposta); exige homologação de parceiro.
• Facebook / Instagram: Graph API; gate alto (App Review da Meta + Business Verification). Instagram responde comentários e DMs (janela de 24h).
• WhatsApp Business: Cloud API via Meta, recebe por webhook a partir da configuração (sem histórico retroativo); fora da janela de 24h só templates aprovados. O app WhatsApp Business do SMB não tem API oficial de leitura.
• Reclame Aqui: sem API pública aberta; só via acordo comercial. Planejar como trilha B2B à parte.

14.3 Rollout faseado sugerido

1. Fase 1 (alto valor): Google Meu Negócio + Facebook + Instagram + WhatsApp.
2. Fase 2 (alto valor): iFood (dependem de programa/homologação).
3. Fase 3 (médio valor): Google Play + App Store + Mercado Livre.
4. Fase 4 (médio valor): Reclame Aqui (só com parceria comercial).

A classificação de sentimento e a geração de respostas (hoje pré-definidas no seed) são os próximos blocos a trocar por um serviço real (NLP/LLM).

15Classificação de sentimento pela MIA (treinamento inicial)

Recomendações de como a MIA deve julgar cada feedback como positivo, negativo ou neutro. No mock o sentimento já vem no seed; quando entrar um modelo real (NLP/LLM), usar estas diretrizes como base do prompt/treinamento. O sentimento define a cor do card e a separação "elogios vs oportunidades de melhoria".

15.1 Definições

• Positivo: o cliente expressa satisfação, elogio, gratidão, recomendação ou intenção de voltar a comprar. Ex.: "Atendimento impecável", "virei cliente fiel".
• Negativo: o cliente expressa insatisfação, reclamação, frustração, problema não resolvido ou arrependimento. Ex.: "demorou demais", "veio com defeito".
• Neutro: dúvida, pedido de informação, comentário factual sem carga emocional, ou elogio e crítica que se equilibram. Ex.: "Qual o horário de funcionamento?".

15.2 Sinais a observar

• Léxico de polaridade: adjetivos/verbos positivos (ótimo, amei, rápido) vs negativos (péssimo, demorou, quebrado).
• Emojis e pontuação: emojis positivos reforçam positivo; emojis de raiva e excesso de "?!" reforçam negativo.
• Nota (quando houver, ex.: Google): sinal forte. 4 a 5 = positivo, 1 a 2 = negativo, 3 = neutro/atenção.
• Resolução: problema resolvido com elogio tende a positivo; problema em aberto tende a negativo.

15.3 Regras de desempate e casos difíceis

• Sentimento misto: classificar pela dor/ação predominante. Problema não resolvido pesa para negativo.
• Nota x texto divergentes: priorizar o texto quando ele for claro. A nota sozinha, sem texto, vale como o sinal.
• Sarcasmo/ironia: classificar pelo sentido real (negativo), não pelo literal.
• Pergunta pura sem reclamação = neutro.
• Dúvida com tom de reclamação = negativo.
• Na incerteza genuína, preferir neutro a errar a polaridade.

15.4 Por que importa

Erros de classificação têm custo assimétrico: marcar um negativo como positivo faz uma reclamação parecer elogio e atrasa a resposta ao cliente insatisfeito. Na dúvida entre positivo e negativo, prefira sinalizar como negativo/atenção para não perder uma oportunidade de recuperação. O tema (themeId) é classificação complementar e não altera o sentimento.

16Automações e notificações (proposta)

Proposta de como avisar o lojista sobre novos feedbacks fora do app. Ainda não implementado (o MVP é só a tela). O princípio para o público (MPEs/SMBs) é avisar o que exige ação, sem virar ruído: o negativo chega na hora; o resto vira resumo.

16.1 Canais de notificação

• Push (app): canal primário, baixo custo, bom para tempo real.
• E-mail: ideal para resumos (digest) e para quem não tem o app aberto.
• WhatsApp (utility template): alto impacto, mas com custo por conversa e regras da Meta. Usar com parcimônia e opt-in explícito.

16.2 Gatilhos e cadência (recomendado)

Por que assim: o negativo tem custo de não responder rápido, então vai instantâneo. O positivo não precisa interromper, então é agrupado. O digest semanal dá a visão geral sem pressão diária.

16.3 Conteúdo das mensagens

• Push/WhatsApp instantâneo (negativo): quem, canal, trecho do feedback e deep link direto para o Detalhe (com a sugestão da MIA pronta).
• Digest (e-mail): novos no período, divididos por sentimento; quantos em aberto; taxa de resposta; CTA "Responder agora".
• Conexão perdida: qual canal, desde quando, CTA "Reconectar".

16.4 Anti-ruído e preferências

• Agrupamento/throttle: nunca mais de 5 pushes por dia (regra não se aplica a negativos); positivos sempre agrupados.

16.5 Defaults recomendados para o MVP de automação

1. Push instantâneo apenas para feedback negativo e nota 1 a 2.
2. E-mail digest semanal (resumo + taxa de resposta + destaques).
3. WhatsApp para negativos e nota 1 a 2.
4. Push de fila (no máximo 1x/dia) quando houver feedbacks em aberto acumulando.

Métricas para acompanhar (ligam à seção 12): notificações enviadas/abertas por canal e tipo, tempo até a primeira resposta após a notificação, opt-out por tipo, e impacto na taxa de resposta. Cortar por porte, segmento e localização.