Relatório agendado em `/relatorios/novo`

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

Objetivo#

Ao final desta aula você vai criar relatório semanal com narrativa — e saber por que a execução do relatório nunca depende da IA.

Vídeo#

Identificador no manifesto: acd-420-01-relatorios-do-analista-de-ia · duração-alvo 9 min · tela do produto: /relatorios.

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

#	Minutagem-alvo	Capítulo	Tela do produto
1	0:00–0:45	Abertura: título + selo `Preview`. O que é um relatório agendado e por que ele não é um export manual nem um painel.	`/relatorios`
2	0:45–2:30	Etapa 1 Conteúdo: nome, descrição e de 1 a 8 consultas (query salva · prompt de IA · SQL digitado). O SQL fica materializado.	`/relatorios/novo`
3	2:30–4:15	Etapa 2 Analista de IA: ligar a narrativa, tom executivo/técnico, contexto do negócio, alertas inteligentes (Business+).	`/relatorios/novo`
4	4:15–6:00	Etapas 3 e 4: Agenda (diário/semanal/mensal/manual, horário de Brasília) e Destinatários com o contador do plano.	`/relatorios/novo`
5	6:00–7:45	Etapa 5 Revisão, criar, e o detalhe: Consultas, Destinatários, Histórico de execuções, `Executar agora`, `Enviar teste pra mim`, `/r/<slug>`.	`/relatorios/[id]`
6	7:45–9:00	Erros comuns, estado `Preview` e os gates de entrega. Encerramento com o "faça você mesmo".	`/relatorios/[id]`

Conteúdo#

O que é um relatório agendado

Um relatório agendado é um analista que roda no horário: ele executa um conjunto de consultas, escreve a leitura dos números e entrega para quem você escolheu — sem ninguém abrir a plataforma. É diferente das duas coisas com que mais se confunde. Um painel é interativo e vive na tela; uma exportação depende de alguém lembrar de exportar. O relatório é a terceira forma: periódica, congelada e auditável.

"Congelada" é a palavra importante. As consultas do relatório são materializadas na criação (o SQL fica gravado no relatório, até 500 linhas por consulta). Isso tem duas consequências que você vai usar toda semana: a execução não depende de IA nenhuma — nem para gerar SQL, nem para rodar; e se o seu modelo mudar depois, o relatório continua rodando o SQL de antes até você editá-lo.

A narrativa é um adendo, não o produto

O produto principal do relatório são os dados. A narrativa de IA é um texto que vem em cima deles. Se o teto de orçamento de IA estourar, o relatório não é abortado: os números saem normalmente e só a narrativa cai num resumo determinístico, dizendo por que não houve IA.

Como aparece no produto

Em IA → Relatórios (/relatorios) você vê a lista com os selos Ativo/Pausado e a marca Analista de IA nos relatórios com narrativa. O botão Novo relatório abre o wizard de 5 etapas em /relatorios/novo:

Etapa	O que você decide	O que o produto aplica
1 · Conteúdo	nome, descrição e de 1 a 8 consultas; origem de cada uma (query salva, prompt de IA ou SQL digitado); visual (KPI, Barras, Linha, Tabela); comparar com o período anterior	o SQL é materializado; o comparativo é o que dá base ao Δ% e à narrativa
2 · Analista de IA	ligar a Narrativa do Analista de IA, tom `Executivo` ou `Técnico`, contexto do negócio (≤ 1.500 caracteres), até 5 regras de alerta inteligente	narrativa exige o entitlement de IA do plano; alerta inteligente exige Business+
3 · Agenda	`Diário`, `Semanal`, `Mensal` ou `Manual (sem agenda)`; horário no fuso de Brasília; dias da semana	vira um cron com fuso; a execução é idempotente por agendamento (o mesmo horário nunca roda duas vezes)
4 · Destinatários	canal E-mail ou WhatsApp e o destino	o contador mostra "N de M no plano X" — e a action recusa acima do teto
5 · Revisão	PDF anexo (Business+) e criar	resumo do que vai ser gravado

No detalhe (/relatorios/[id]) ficam três blocos: Consultas, Destinatários e Histórico de execuções — uma tabela com Quando · Origem · Status · Custo · Entregas · Snapshot. Origem distingue Agendado, Manual e Alerta. Entregas resume os recibos ("2 ok · 1 falha(s)" — a Aula 3 abre esses estados). E as ações do topo são Executar agora, Enviar teste pra mim e Pausar/Ativar. Cada execução bem-sucedida publica um snapshot em /r/<slug>.

Quem pode. Criar, editar e apagar relatório é do dono do workspace; um membro só executa com concessão explícita. Executar e entregar é ação cara (BigQuery + IA + canal de envio): passa pelo gate de workspace ativo — em atraso, bloqueia — e por um gate de capacidade ortogonal (a chave de desligamento de report.run). Mesmo com a fatura em dia, capacidade desligada não gera, não executa e não entrega.

Exemplo Aurora

maria (dona do workspace Aurora Varejo) cria "Semanal Aurora" para segundas, 8h, com três consultas: Receita por filial (KPI, comparando com o período anterior), Receita por categoria (barras) e Receita diária (linha). Na etapa 2 ela liga a narrativa no tom Executivo e escreve no contexto do negócio: "rede de 3 filiais em MG; margem alvo 22%; dezembro é sazonal". Na etapa 4 entram maria@example.com e ana@example.com — "2 de 10 no plano Growth". Antes de esperar a segunda, ela clica em Enviar teste pra mim e confere o resultado; depois, Executar agora grava a primeira linha no histórico e o snapshot em /r/semanal-aurora-....

Erros comuns

Sintoma	Causa provável	O que fazer
"A IA falhou, então o relatório não saiu"	confundir narrativa com execução	os dados saem sempre; sem IA (teto, provedor, plano) a narrativa vira resumo determinístico
"Seu plano permite até 3 destinatários por relatório."	destinatários acima do entitlement	reduza a lista ou troque de plano (Aula 9)
"Agendei e o e-mail não chegou"	entrega real é gate humano	confira o recibo no histórico; em treino o envio é simulado (Aula 3)
Mudei a tabela e o relatório traz o número velho	consultas congeladas na criação	edite o relatório e regrave a consulta
Liguei um alerta inteligente e choveu aviso	regra sem backtest	rode o backtest antes de ligar (Aula 4)
Relatório agendado recusado na criação	teto de relatórios com agenda ativa	pause um relatório ou use `Manual (sem agenda)`

Estado e gates

O relatório agendado é Preview: o cron com fuso, o congelamento das consultas e a idempotência por agendamento são cobertos por testes determinísticos, mas toda entrega externa é NÃO MEDIDO. O recibo real de e-mail é gate humano (o domínio de envio transacional ainda está em verificação) e o envio real por WhatsApp é gate humano sob allowlist. O PDF anexo depende de infraestrutura paga (um job de impressão em nuvem) e do plano Business+. Nada aqui é "GA".

Faça você mesmo#

No workspace de treino Aurora Varejo, como dona do workspace (abra /relatorios no console):

Clique em Novo relatório e, na etapa Conteúdo, chame-o de "Semanal Aurora".
Adicione a consulta Receita por filial (de uma query salva ou do SQL digitado), visual KPI, e marque comparar com o período anterior.
Adicione uma segunda consulta, Receita por categoria, visual Barras.
Na etapa Analista de IA, ligue a narrativa no tom Executivo e escreva duas linhas de contexto do negócio. Atenção: gerar a narrativa consome orçamento de IA do workspace.
Na etapa Agenda, escolha Semanal, segunda-feira, 08:00 (Brasília), e confirme a frase de resumo da agenda.
Na etapa Destinatários, adicione maria@example.com e observe o contador "N de M no plano".
Revise, crie, e no detalhe use Enviar teste pra mim e depois Executar agora.
Abra a linha nova do Histórico de execuções e identifique Origem, Status, Custo e Entregas.

Você terminou quando existir uma linha no histórico com snapshot em /r/<slug> e você conseguir explicar por que o relatório sairia mesmo sem nenhuma narrativa de IA.

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#

Capacidades ensinadas#

(conceitual — sem capacidade específica da matriz) — o selo exibido na aula é sempre o estado mais conservador entre as capacidades citadas; nada aqui é "GA".