1. O que é o Ativa

Um painel de exceções pra varejo: mostra só o que exige ação agora e quanto dinheiro está em jogo.

Contexto e problema

A operação tem dado intraday rico (POS, fluxo, conversão por hora) mas o time regional só consegue olhar de fato o relatório no fim do dia, quando a janela pra agir já fechou. O resultado é uma rotina onde quedas de conversão e fluxo passam o dia inteiro sem triagem, descobertas tarde demais ou apenas quando o supervisor de plantão personalmente se incomoda com o número. Cada dia sem ação vira perda em R$ que ninguém estima.

Objetivo

Transformar o dado intraday em ação no momento certo, com priorização explícita por perda em R$ pra que o regional saiba qual loja olhar primeiro. Sucesso é medido pela taxa de alertas críticos que recebem ação no mesmo dia, e por R$ recuperados em vez de R$ deixados na mesa.

Solução (mecanismo)

O Ativa compara o dia corrente contra a mediana histórica da loja (mesmo dia da semana, mesma hora, últimas 8 semanas) e sinaliza só quando fluxo, conversão ou ambos saem do esperado em magnitude financeiramente relevante. Operador não precisa ler relatório: entra, vê o card mais caro primeiro, clica, decide.

Existem 4 estados que classificam o diagnóstico:

• Problema externo externo fluxo caiu, conversão segue normal. Origem geralmente fora da loja (shopping, clima, evento).
• Problema interno interno fluxo normal, conversão despencou. Equipe, vitrine ou produto.
• Duplo duplo fluxo e conversão caíram juntos. Prioridade máxima, escala pra regional.
• Oportunidade oportunidade fluxo acima do típico mas conversão caiu. Pico não capturado.

2. Fluxo em 60 segundos

Rotina típica do operador ao abrir o painel. Se não couber em 60s, abri direto o card mais crítico.

3. Anatomia do painel Hoje

O painel tem 5 blocos, nessa ordem: header com KPIs, status-bar, health-bar, filtros, alertas.

KPIs no topo

Status-bar + chip de POS sem dados

Logo abaixo do header, uma barra fina mostra três informações operacionais: horário da última ingestão, total de transações perdidas no período, e um chip laranja que só aparece quando há lojas em estado "POS sem dados" hoje.

Health-bar + filtros

A barra de saúde do parque mostra quantas lojas estão operando normal vs em atenção vs sem dado confiável. Serve pra calibrar quanto peso dar aos alertas: se 90% do parque está verde e só 10% alerta, a lista tende a ser confiável. Se metade do parque está cinza (sem dado), vale investigar ingestão antes de agir.

Os chips de filtro abaixo filtram a lista de alertas por severidade, estado diagnóstico e marca. Seleção fica salva por 30 dias (localStorage), então supervisor que cuida só de uma marca mantém o filtro entre logins.

Quando o filtro esconde tudo

Se a combinação de filtros não casa com nenhum alerta aberto, o painel mostra um empty-state explícito com a contagem real e botão de escape, em vez de uma frase genérica. Reduz o risco do operador concluir que está tudo bem só porque a lista filtrada está vazia.

4. Como ler um alerta

Cada card concentra na densidade mínima a informação pra decidir sem abrir o modal: severidade, perda em R$, diagnóstico em uma frase, delta numérico e projeção de fechamento.

A fórmula da projeção: pace_factor = acumulado real até agora ÷ acumulado esperado até agora. Esse fator é aplicado ao baseline do dia inteiro (mediana histórica de visitantes, vendas e receita até o fechamento). Se o pace_factor é 0,55, projeta-se 55% do fechamento típico. Quanto mais cedo o alerta abre, mais janela útil sobra pra reverter.

5. O modal de drill-down

Clicar num card abre o modal com 6 seções. As 3 últimas iniciam colapsadas, expande só se precisar.

Acessibilidade do modal: abre com foco no botão Fechar, Tab cicla entre elementos sem escapar do modal, Esc fecha e devolve foco pro card que abriu. As 3 seções colapsáveis também participam do Tab.

6. Registrar uma ação

Sem registro, o alerta vira "sem ação" no fechamento do dia e entra pra métrica "Deixado na mesa no mês". Também não há outcome scoring.

Campos do formulário

Outcome scoring

2 horas após o registro (com janela de retry de até 12h se a loja fecha antes), o motor reavalia os números da loja e classifica o resultado em uma de 4 categorias:

O outcome fica atrelado ao registro de ação e vira input pra análise retrospectiva: quais tipos de ação funcionam em quais estados diagnósticos, quais responsáveis têm melhor taxa de recuperação, etc.

7. Descartar alerta

Descartar (X no canto do card, ou link "Ignorar este alerta" no modal) é legítimo pra falsos positivos conhecidos ou situações fora do controle do operador.

Todo descarte mostra um toast com botão Desfazer por 7 segundos. Depois disso, o alerta continua no histórico marcado como "Ignorado" mas some da lista Hoje.

8. Histórico

Todas as decisões passadas. Útil pra auditoria, revisão semanal com regional, ou investigação de padrão.

Filtros disponíveis

• Período: Últimos 7 dias, 30 dias, mês atual, mês anterior, ou range custom (date picker).
• Status da ação: Todos / Com ação / Ignorados / Sem ação.
• Estado: Todos / Externo / Interno / Duplo / Oportunidade.
• Marca: Todas ou marca específica.

Download CSV

Botão "Baixar CSV" exporta o conjunto filtrado: loja, marca, data, estado, severidade, perda, ação registrada, responsável, outcome e notas. Cabeçalho em pt-BR, separador vírgula, encoding UTF-8 com BOM pra abrir limpo no Excel.

Data com dia da semana

Linhas do histórico mostram a data com o dia da semana abreviado: "qui 23/04" em vez de só "23/04". Varejo lê padrão por dia da semana (segunda diferente de sábado), então o eyeballing fica mais rápido. Helper formatWeekdayShort() em utils.js.

Por hora-de-fechamento

O agrupador "Por hora-de-fechamento" no histórico ordena alertas pela hora em que o motor avaliou o alerta como crítico, ou seja, a hora de fechamento do alerta. Não é a hora em que a perda aconteceu, e sim a hora do snapshot do motor. Esse rótulo gerou confusão recorrente quando se chamava só "Por hora fechada".

Sinalizadores nos cards

Nos cards do histórico, além das 3 linhas do alerta padrão, aparecem:

• Badge de ação: "Com ação" (verde), "Sem ação" (cinza), "Ignorado" (itálico cinza).
• Badge de outcome quando houver registro: "Efetiva" (verde), "Parcial" (amarelo), "Sem recuperação" (vermelho), "Inconclusiva" (cinza).
• Crônico (roxo): alertas que voltam 3+ vezes no mês pra mesma loja/estado.
• Supervisão (vermelho): flag pra casos que o supervisor regional pediu pra acompanhar explicitamente.

9. Ações que funcionam pra sua rede

Ranking de efetividade das ações registradas. O que vira moat competitivo: quanto mais gente registra, melhor o ranking fica, e ninguém de fora consegue replicar sem a base de outcome.

Vive abaixo da lista do Histórico, num bloco com tabela e dois controles: ordenação (por taxa de efetiva, taxa de sucesso, R$ médio recuperado, ou amostra) e mínimo de amostra (quantas avaliações pra a combinação aparecer). Mostra as 15 melhores combinações de tipo de ação × estado diagnóstico no período do filtro.

O que cada coluna significa

• Avaliadas: quantas ações desse tipo, nesse estado, já passaram pelo outcome scoring (têm resultado classificado).
• Efetiva: % das avaliadas que foram classificadas como Efetiva (recuperação plena na janela de 2h).
• Sucesso: % das avaliadas com resultado positivo (Efetiva + Parcial). Mais permissivo.
• R$ médio recuperado: valor médio do delta positivo nas ações efetivas/parciais.
• R$ total: soma dos deltas positivos no período.

Como usar

Quando o operador abre o modal de um alerta novo, o estado diagnóstico já vem populado. Ele consulta o ranking pra ver quais ações funcionaram melhor pra esse estado na rede dele, e usa isso pra decidir o que fazer (ou pra justificar a escolha pro regional). Ao longo das semanas, o ranking fica mais confiável conforme mais ações são registradas.

Endpoint: /api/actions/effectiveness. Recálculo é feito a cada acesso do histórico, considerando o filtro de período e marca ativos.

10. Visão Diretor

Aba /diretor.html: visão de portfólio pro diretor regional. Não é pra agir intraday, é pra revisar onde o sangramento se concentra e quem está respondendo bem.

4 KPIs no topo

Heatmap marca × shopping

Top 15 combinações por R$ deixado na mesa, com barra colorida em 4 níveis (mais escura = pior). Click numa linha abre o histórico filtrado por aquela marca, com o período correspondente. Onde o sangramento se concentra fica imediatamente visível, sem precisar fazer pivot.

Ranking de supervisores

Quem registrou ações no período, quantas, quantas foram avaliadas pelo outcome, taxa de efetiva, e R$ recuperado. Ordenado por R$ recuperado real, depois taxa de efetiva, depois volume. Conversa de regional vira fácil: "supervisor X recuperou 2x o supervisor Y registrando metade das ações, vale revisar o que eles fazem diferente".

Lojas em deterioração

Lojas com perda líquida crescendo vs período anterior. Líquida = bruto menos o que foi recuperado via ações classificadas como Efetiva ou Parcial. Loja onde o supervisor agiu e recuperou não aparece como deteriorando (no nível em que foi recuperada).

Filtros que evitam ruído:

• Alertas dismissed (descartados) não contam: falsos positivos não inflam o R$ da loja.
• Loja só entra se tinha baseline real no período anterior (perda líquida prev > 0). Sem isso o delta % seria fictício e estreantes apareceriam como "deteriorando" só por terem o primeiro alerta.
• Tem que estar piorando hoje (delta > 0) e ter pelo menos 1 alerta no período corrente.

Sort: dois modos via pílula acima da tabela.

• Δ R$ absoluto (default): quem perdeu mais R$ a mais que no período anterior. Lojas grandes tendem a dominar o topo.
• Δ %: quem piorou mais proporcionalmente ao próprio baseline. Lojas pequenas que dobraram aparecem em cima.

Filtros

• Janela: 7 / 30 / 90 dias. Pílulas no topo do header.
• Marca: filtro client-side que afeta o heatmap, KPIs (recalculados pela soma das células filtradas) e a lista de lojas em deterioração. Não afeta o ranking de supervisores, porque um mesmo supervisor pode cuidar de várias marcas.

Endpoint: /api/director/summary?window_days=N. Refresh manual ao trocar a janela; client-side ao trocar marca.

11. Multi-canal de entrega

Painel é só uma das saídas. Alerta crítico precisa chegar onde o gerente já está olhando. O Ativa entrega por canais com prioridade configurável por tenant.

Hierarquia de canais

Resposta do gerente vira ação registrada

Independente do canal, a resposta do gerente é estruturada em 3 botões e cai automaticamente no Registro de ação do alerta. Sem precisar abrir o painel:

Configuração por tenant

Tabela tenant_notification_config no banco guarda, por cliente, qual canal é primário, secundário, e fallback. Mudar a hierarquia é ato de config, não de deploy. Inclui também os webhooks específicos do canal e regras de quiet hours.

Endpoints

• POST /api/notifications/respond: deep link via email; body traz alert_id + escolha do botão.
• POST /api/notifications/webhook/whatsapp: recebe respostas do WhatsApp Cloud API.
• POST /api/notifications/webhook/alia: recebe respostas do Alia.

As três rotas convergem no mesmo handler interno que cria o registro de ação, então o pipeline de outcome scoring é o mesmo independente da origem.

12. Dados guardados

Tudo que o operador faz alimenta uma base que o motor revisita pra melhorar diagnóstico e gerar relatórios. Nada do que segue é descartado entre sessões.

Como esses dados reforçam a análise

A soma desses registros permite responder perguntas que em dashboard tradicional exigiriam trabalho manual:

• Qual tipo de ação funciona em que estado? Cruzar action-type × estado diagnóstico × outcome = matriz de efetividade.
• Quais lojas são cronicamente problemáticas? Contagem de alertas sem ação por (loja × mês) com threshold de 3.
• Quanto o supervisor X recupera vs Y? Agrupar outcome por responsável.
• Clima realmente afeta fluxo aqui? Correlacionar enrichments.weather × loss do dia na mesma cidade.
• Essa loja está pior que seus pares ou é sazonal? Peer benchmark + calendário de ações passadas.

13. Sinais sonoros e atalhos

Sons

O Ativa toca um chime curto quando um alerta novo entra num ciclo de polling (não na primeira carga). Alertas novos também ganham entrada animada (fade + leve pulso). Ao descartar um alerta toca um glide descendente mais discreto. Som desliga no toggle no canto superior direito do header (estado salvo em localStorage).

A primeira carga nunca toca som, de outra forma tocaria pra cada alerta já existente.

Atalhos de teclado

• Esc fecha o modal e devolve foco pro card.
• Tab / Shift+Tab navega dentro do modal (focus trap).
• Enter ou Espaço ativa elementos focados (inclusive toggles de som e aparência).

Horário de operação

O motor roda em horário comercial BR (10h às 22h). Fora desse intervalo, o painel mostra banner cinza "Fora do horário de operação, próxima ingestão ~10:10 amanhã" em vez de alertar sobre ingestão stale.

14. Limitações e riscos

Pra que o Ativa se mantenha útil é importante estar explícito sobre onde ele não ajuda e quais riscos carrega.

O que o Ativa NÃO resolve

• Causa raiz estrutural: o painel diz que conversão caiu hoje, não diz que o produto X está fora há 3 semanas porque o comprador faltou. Análise de causa raiz de longo prazo continua sendo trabalho do regional + categoria.
• Loja sem baseline: loja recém-aberta (menos de 8 semanas de histórico) ou que mudou drasticamente de perfil não gera alertas confiáveis. O motor escolhe ficar silencioso a gerar ruído.
• Decisão estratégica: abrir/fechar loja, mudar mix, contratar ou cortar gente. Isso é trabalho de planejamento mensal, não de painel intraday.
• Comparativo entre lojas dissimilares: peer benchmarks rodam com fallback hierárquico de chave (marca+volume+local → marca+volume → marca+local → marca-only), e quando o cadastro de volume_bucket está null o motor deriva o tercil de visitantes/dia da própria marca. Mesmo assim, lojas únicas ou de perfil muito raro podem cair só em "marca-only" e gerar comparativo menos preciso. Se nem assim atingir os 5 peers mínimos, a seção desaparece do modal em vez de mostrar dado fraco.
• Enriquecimento externo completo: clima e feriado já entram, mas eventos no shopping, obras na rua e trânsito ainda dependem de fonte manual ou estão no roadmap.

Riscos operacionais

• Falso positivo: dia atípico (inventário, evento local não cadastrado, manutenção do shopping) pode disparar alerta legítimo do ponto de vista do dado mas inútil pro operador. Mitigação: descartar com Desfazer + revisar threshold se um padrão se repetir.
• Dependência da ingestão do POS: se a ingestão atrasa mais de 2 horas, os alertas viram retrato velho. Mitigação: banner "última ingestão" no header + alerta automático quando o lag passa de 90min.
• Operador refém do painel: o risco de só olhar o que o Ativa lista e perder visão estrutural. Mitigação: revisão semanal com regional usando histórico + relatório mensal de outcomes pra forçar análise além do dia.
• Normalização do "Sem ação": se ninguém acompanha, descarte vira default e o painel perde valor. Mitigação: taxa de ação por supervisor é métrica de gerência (capítulo 15).
• Hipótese vs fato em outcome scoring: o motor classifica "Efetiva" baseado em recuperação de conversão na janela de 2h, o que correlaciona com a ação mas não prova causalidade. Trate como sinal, não como prova.

15. Indicadores de acompanhamento

Métricas que liderança e regional revisam pra saber se o Ativa está cumprindo o objetivo. Outputs medem uso da ferramenta, outcomes medem impacto no negócio.

Outputs (uso da ferramenta)

• Taxa de ação em alertas críticos: % de alertas críticos que recebem registro de ação dentro de 2h da abertura. Meta inicial: ≥ 60%.
• Tempo médio até primeira ação: do momento em que o alerta abre até o primeiro registro. Meta inicial: ≤ 90 minutos em horário comercial.
• Cobertura de baseline: % de lojas com baseline válido (≥ 8 semanas + ≥ 20 dias úteis). Meta: ≥ 90% do parque ativo.
• Cobertura de ingestão: % do tempo em que a última ingestão está dentro de 60min do horário atual em janela comercial. Meta: ≥ 95%.
• Distribuição de descarte: % de alertas descartados sobre alertas abertos. Acima de 30% sugere threshold mal calibrado ou contexto operacional não capturado.

Outcomes (impacto no negócio)

• R$ recuperado por semana: soma do delta de transações nos alertas que receberam ação Efetiva. Comparar contra R$ deixado na mesa nos alertas Sem ação ou Sem recuperação.
• Taxa de outcome Efetiva: % de ações registradas que resultam em recuperação de conversão na janela de 2h. Meta inicial: ≥ 35%.
• Lojas crônicas reduzidas: lojas que abrem 3+ alertas no mês. A meta é que o número desça mês a mês conforme regional usa o histórico pra conversa estrutural.
• Aderência regional: % de regionais ativos no painel ao menos 1x/dia em horário comercial. Sem uso, não há valor.

Ritmo de revisão

Checkpoint semanal entre regional e gerência usando o Histórico (capítulo 8) filtrado pelos últimos 7 dias. Review mensal com C-level sobre R$ recuperado vs deixado na mesa, evolução de lojas crônicas e calibração de thresholds. Recalibração trimestral do baseline (rejanelar as 8 semanas, revisar peer groups).

Hipótese vs fato: as metas listadas acima são expectativas iniciais baseadas em conversa de discovery, não em resultado observado. Após o primeiro mês de uso, este capítulo deve ser atualizado com números reais e as metas recalibradas.

16. Próximos passos

O que está em desenvolvimento, o que está bloqueado, e o que está fora de escopo no momento.

Em desenvolvimento

Bloqueado ou pendente de decisão

Fora de escopo no momento

• Trânsito em tempo real pra lojas de rua: requer API paga + cobertura ainda pequena no nicho. Revisar se virar prioridade da gerência regional.
• Previsão de fluxo (em vez de detecção): o Ativa é detectivo, não preditivo. Forecast horário é projeto separado, não roadmap deste painel.
• Dashboard mobile-first: hoje o painel funciona em mobile mas foi pensado pra desktop. Investir em UX mobile dedicada só se taxa de acesso mobile passar de 30%.