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 30 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 30 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).
17. Comentários do próprio usuário são filtrados. Comentários, respostas ou postagens publicados pelo próprio usuário (a conta logada, ou administradores/perfis da mesma página conectada) nos canais integrados não devem ser apresentados como feedbacks de clientes. Isso inclui: respostas do usuário a comentários de terceiros, publicações da própria página e mensagens enviadas pelo próprio usuário em canais de conversa. A regra vale para a varredura, o deck (Recentes), Todos os Feedbacks e o detalhe — a fonte de verdade é a identidade do autor retornada pela API de cada canal, não o teor do texto.

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 30 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 30 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 Alertas para monitorar pós-lançamento

Janela de sincronização (30 dias) é hipótese inicial. O número de 30 dias foi definido como ponto de partida, sem base empírica de uso real. Nas primeiras semanas após o lançamento, acompanhar de perto o volume de feedbacks devolvidos por varredura e a demanda dos usuários por histórico mais longo ou mais curto (via suporte, entrevistas ou telemetria da seção 12). Se o volume estourar a leitura confortável do deck, considerar reduzir para 14 ou 7 dias; se os usuários pedirem contexto mais antigo, considerar ampliar para 60 ou 90 dias. Ajuste deve ser dirigido por dado, não por intuição.

Tratamento de spam ainda não implementado. O MVP entrega no painel todo comentário que o canal devolver, sem filtragem prévia. Nas primeiras semanas pós-lançamento, avaliar se aparecem no deck comentários que atrapalham a leitura — emojis soltos, mensagens repetidas, promoções de terceiros, links suspeitos, respostas automatizadas ou conteúdo claramente automatizado. Se o volume desses casos for relevante, será necessário projetar uma camada de filtragem antes da apresentação (heurísticas por comprimento mínimo, blacklist de padrões, classificação pela MIA ou combinação). Escopo, gatilho e critério de sucesso dessa camada dependem do que os dados mostrarem — não modelar preventivamente.

10.2 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.