Limiar, histórico, backtest

Selo de estado: Preview (teto atual do produto) · Curso ACD-420 — Analista de IA: relatórios, alertas, anomalias e previsões · Aula 4 de 9 · Atualizado em 2026-10-04.

Objetivo#

Ao final desta aula você vai configurar alerta e ler backtest — e nunca mais ligar uma regra sem saber quanto barulho ela faria.

Vídeo#

Identificador no manifesto: acd-420-04-alertas-de-limiar-e-historico · duração-alvo 7 min · tela do produto: /relatorios.

Roteiro de gravação (6 capítulos):

Conteúdo#

Determinístico, do começo ao fim

Alerta não tem LLM. A avaliação da condição, o texto do motivo em português, a idempotência, o histórico e o webhook (Aula 5) são código puro: para avaliar, nada sai do produto — a comparação acontece localmente, sobre o snapshot já materializado. Custo de IA: zero. Isso importa na prática, porque significa que o alerta funciona com a IA desligada, com o orçamento de IA zerado e em qualquer plano que tenha o recurso.

Duas superfícies, dois tipos de regra

No painel, por visual. Abra o painel, selecione o visual e use o botão Alerta. Os campos são:

Visuais de valor único (KPI, medidor, termômetro, progresso) não pedem "Medida" nem "Resumir por" — o alerta olha o único valor que existe. O recurso é do plano Business+.

No relatório, por consulta. Na etapa 2 do wizard (/relatorios/novo), o bloco Alertas inteligentes monitora uma coluna numérica e dispara o relatório fora da agenda. São até 5 regras, cada uma com operador drop_pct (queda ≥ X%), spike_pct (pico ≥ X%), below (< valor) ou above (> valor) e uma janela mínima entre disparos em horas. Também Business+ — fora do plano, a action responde "Alertas inteligentes estão disponíveis no plano Business."

Quando o alerta dispara (e quando não)

• A avaliação acontece no refresh do painel. Não há cron dedicado de alerta: sem dado novo, não há reavaliação.
• Rearme por transição. O alerta dispara na passagem para violado e só repete depois de normalizar. É isso que evita um aviso por hora enquanto o número continua ruim.
• Cooloff. Uma janela mínima entre disparos, quando configurada, aperta ainda mais.
• Idempotência à prova de corrida. A chave é um hash de (painel, visual, hash da regra, refreshedAt do snapshot), com UNIQUE no banco. O mesmo snapshot nunca dispara a mesma regra duas vezes — nem com refresh reprocessado, nem com corrida de crons, nem com retry. Mudou a regra ou chegou snapshot novo? Chave nova, pode disparar de novo.
• Regra percentual sem base não dispara. No primeiro refresh, sem snapshot anterior, drop_pct/spike_pct não têm com o que comparar — e o produto prefere o silêncio a um alarme inventado.

Cada disparo vira um evento de alerta escopado ao workspace, com o estado de entrega (fired/delivered/failed) — é o histórico que responde "quais alertas dispararam este mês" e que se conecta ao ledger de entrega da Aula 3.

Backtest: o teto de barulho

Antes de ligar a regra, backteste. O backtest conta em quantos pontos do seu histórico a condição valeria. Duas leituras honestas sobre ele:

1. Ele não simula rearme por transição nem cooloff. De propósito: esses dois mecanismos só reduzem os envios, então o número do backtest é o teto de barulho. Se o teto já é aceitável, o real será melhor.
2. Vale o aviso de sempre: passado não garante futuro.

A regra de bolso: se o backtest aponta dezenas de disparos no histórico, o limiar está frouxo e o alerta vai ser ignorado em duas semanas. Se aponta zero, o limiar está apertado e o alerta nunca vai avisar nada.

Exemplo Aurora: receita contra a meta

A meta semanal de receita da Aurora é R$ 50 mil. maria quer avisar quando a semana fechar abaixo de 80% da meta, ou seja, R$ 40 mil. No painel "Vendas por filial", ela seleciona o KPI de receita semanal e configura Avisar quando valor < 40000, canal E-mail, destinatário maria@example.com.

O detalhe que todo mundo erra: o alerta não conhece a meta. Alerta ligado a uma meta cadastrada do painel é Roadmap — então é você que traduz a meta em um limiar absoluto e reajusta o número quando a meta mudar. Antes de ligar, maria roda o backtest: 3 disparos nas últimas 26 semanas. Aceitável. Com limiar em R$ 48 mil (96% da meta) o backtest apontava 14 — barulho garantido.

Erros comuns

Estado e gates

A lógica de alerta é coberta por testes determinísticos (avaliação de limiar e percentual, disparo por transição, histórico, backtest fiel à avaliação ao vivo, webhook assinado) — mas o teto do produto é Preview e toda entrega externa é NÃO MEDIDO: o e-mail depende de domínio verificado (gate humano) e o WhatsApp de credencial e template aprovado sob allowlist (gate humano). Alerta ligado a meta cadastrada: Roadmap.

Faça você mesmo#

No workspace de treino Aurora Varejo (abra /dashboards e, depois, /relatorios no console):

1. Abra o painel "Vendas por filial" e selecione o visual de Receita (KPI ou linha).
2. No botão Alerta, configure Avisar quando valor < 40000 (80% da meta de R$ 50 mil), canal E-mail, destinatário maria@example.com.
3. Se o visual tiver série, escolha a Medida e o Resumir por (soma para a semana fechada; último ponto para o dia corrente) e explique a diferença.
4. Rode o backtest da regra e anote quantos disparos ela teria tido no histórico.
5. Aperte o limiar para R$ 48 mil, rode o backtest de novo e compare — escolha o limiar que você defenderia.
6. Atualize os dados do painel para que a regra seja avaliada; confira o histórico de disparos.
7. Atualize os dados de novo sem mudar nada e confirme que o mesmo snapshot não dispara um segundo alerta.
8. Em /relatorios/novo, etapa Analista de IA, adicione um alerta inteligente drop_pct ≥ 20% com janela mínima de 24 h (se o seu plano permitir) e observe a mensagem do plano quando não permitir.

Atenção: este exercício depende de gate — a entrega real do aviso é gate humano; o que você precisa provar é o disparo, o histórico e o backtest.

Você terminou quando você tiver dois números de backtest para o mesmo alerta (limiar frouxo × limiar apertado) e um disparo registrado no histórico que não se repetiu no refresh seguinte.

Checagem rápida#

Três perguntas no final da aula, corrigidas no servidor. A aula só conta como concluída depois da checagem.

Documentação relacionada#

• ai/alertas-e-webhooks

Capacidades ensinadas#

C08.5 — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".