--- id: agencias/relatorio-recorrente-automatizado industria: Agências de marketing uso: muito usado esforco: médio grao: Cliente x período (semana ISO ou mês fechado) --- # Relatório recorrente automatizado O relatório semanal ou mensal de cada cliente sai sozinho, no mesmo padrão, com os números calculados no warehouse e a leitura escrita por IA. ## Resumo executivo **Para quem:** Agências que entregam relatório semanal ou mensal para cada cliente. **O que resolve** - O relatório sai no dia e na hora, sem montagem manual. - Todos os clientes recebem o mesmo padrão, comparável entre si. - A leitura do período vem escrita, sem número inventado. **Por que importa:** O relatório é a parte do trabalho que o cliente vê. Automatizado, ele libera dias da equipe todo mês e tira a variação de qualidade entre analistas. Com a regra certa, a IA escreve a leitura sem o risco de inventar número na frente do cliente. **Perguntas de negócio que responde** - Como foi a semana do cliente X contra a anterior e contra a média do mês? - Gere o relatório mensal de setembro do cliente Y. - Qual a leitura executiva do LinkedIn do cliente Z no mês fechado? - Quais clientes tiveram a maior queda de resultado na última semana? - Monte a apresentação de renovação com a jornada do ciclo do cliente X. **O que você precisa** - Tabelas finais de mídia e funil por cliente - A estrutura de relatório aprovada com cada cliente - Uma chave de API de LLM guardada como secret na Nekt **O que você recebe** - Um placar por cliente e período, com anterior, média e variação - Uma leitura executiva escrita por IA - Envio automático no canal de cada cliente - Log de envio por cliente e período ## Detalhado ### O problema Montar o relatório de cada cliente à mão consome dias da equipe todo começo de mês, e cada analista faz de um jeito. Quando a IA entra para escrever, ela inventa número, compara mês parcial com mês cheio ou preenche com zero um canal que o cliente nem contratou. ### Regras de negócio 1. **O número vem do SQL, a IA só redige.** Placar, variações, ranking e prioridade são calculados numa tabela antes do modelo. O LLM recebe o placar pronto do cliente e do período e escreve síntese, destaques, alertas e recomendações. A prioridade é calculada na transformação, não pelo modelo. (Evite: Mandar as tabelas cruas para o LLM calcular e escrever.) 2. **Período fechado e explícito.** Semana de segunda a domingo (ISO) ou mês calendário fechado, no fuso do cliente. O relatório roda depois que os dados estabilizam: na segunda de manhã para a semana, alguns dias após a virada para o mês (ex.: dia 4). Mês corrente só aparece rotulado como parcial. (Evite: Relatório do mês rodando no dia 1 com conversões ainda chegando.) 3. **Placar pronto para ler.** Uma linha por cliente, período e plataforma. Para cada métrica: valor atual, período anterior (_ant), média das 4 últimas semanas incluindo a atual (_med4) e variação contra o anterior (_var). O mesmo placar alimenta o dashboard e a mensagem: o consumidor só filtra o período. (Evite: Cada destino recalcula a variação do seu jeito.) 4. **Compare janelas do mesmo tamanho.** Semana contra a semana anterior, mês contra o mês anterior. Em janelas móveis, últimos 30, 90, 180 e 365 dias contra a janela imediatamente anterior de mesmo tamanho. Custo por resultado do período é soma do investimento sobre soma do resultado, nunca média de custos diários. (Evite: Mês parcial contra mês cheio.) 5. **Escopo sem conector sai do relatório.** Se o cliente não tem a fonte conectada (SEO, CRM, orgânico), a seção sai do relatório; não entra com zero. Se o pipeline não rodou no período, o relatório diz isso, não preenche. Dado manual (ex.: LinkedIn de perfil pessoal) vem marcado como manual. (Evite: Seção de SEO com zero cliques num cliente sem Search Console.) 6. **Estrutura fixa aprovada pelo cliente.** Ordem das seções, quadros, cores e tipografia ficam num documento de contexto do cliente, a partir de um relatório de referência aprovado. Todo relatório segue essa estrutura. Para apresentações, use elementos nativos e editáveis, nunca texto queimado em imagem. (Evite: Cada envio com um layout diferente.) 7. **Nunca estimar, perguntar.** Faltou meta do próximo mês, entregas do período ou premissas do cliente: o agente pergunta antes de montar. Print ou valor informado pelo time só entra quando a tabela não existe; nunca para completar um número que o warehouse tem. (Evite: Preencher a meta com a média dos últimos meses.) 8. **Dado atrasado é avisado.** Antes de enviar, confira se a tabela de origem é do dia. Se não for, espere uma janela curta (ex.: 25 minutos) e, se não chegar, envie avisando que os dados são do dia anterior. (Evite: Enviar no horário com o dado de dois dias atrás, sem aviso.) 9. **Um envio por cliente e período.** Log persistente por cliente e período: reexecutar não reenvia. A falha de um cliente não interrompe os demais. Mensagens longas são partidas no limite do canal (ex.: 1.900 caracteres no Discord). Cliente que saiu da carteira não recebe relatório; churn é sinalizado. (Evite: Loop único que para no primeiro erro e reenvia tudo na nova tentativa.) ### Definições | Métrica | Definição | |---|---| | Semana do relatório | segunda a domingo fechados, no fuso America/Sao_Paulo, terminando no domingo anterior ao envio | | Mês do relatório | mês calendário fechado, gerado depois que as fontes de conversão estabilizam | | _ant | valor da métrica no período anterior de mesmo tamanho | | _med4 | média das 4 últimas semanas, incluindo a semana do relatório | | _var | atual / anterior - 1; vazio quando o anterior é zero | | Custo por resultado do período | soma do investimento / soma do resultado no período, dividindo uma vez só | | Leitura | texto do LLM sobre o placar: síntese, destaques, alertas e recomendações, sem número que não esteja no placar | ### Armadilhas - **Número inventado pela IA.** Com dado cru, o modelo calculou errado e completou lacunas com valores plausíveis. Como evitar: Entregar o placar fechado e conferir cada número do texto contra ele. - **Queda que era mês parcial.** Mês corrente comparado com mês cheio mostrou queda forte que não existia. Como evitar: Comparar períodos fechados ou rotular o parcial. - **Canal com zero que o cliente não tem.** Seções sem conector entraram zeradas e o cliente achou que o canal tinha morrido. Como evitar: Escopo por cliente: sem conector, sem seção. - **Leitura genérica.** Campos de anotação cortados em 600 caracteres decepavam a frase literal do cliente, e o texto saía genérico. Como evitar: Não truncar o contexto que dá o tom; limites altos e só os campos necessários. - **Relatório com dado velho.** A cadeia atrasou e a mensagem saiu no horário com o dado de dois dias antes, sem ninguém notar. Como evitar: Checar a data da tabela antes de enviar e avisar quando estiver velha. - **Envio duplicado ou faltando.** Um erro num cliente interrompia todos os outros, e a nova tentativa reenviava quem já tinha recebido. Como evitar: Log por cliente e período e isolamento de falha. ### Teste de aceitação - [ ] Para um cliente e uma semana fechada, cada número do placar bate com a consulta direta na tabela de origem (diferença zero). - [ ] Todo número citado na leitura escrita pela IA existe no placar daquele cliente e período. - [ ] Um cliente sem conector de SEO não tem seção de SEO no relatório, nem com zero. - [ ] Reexecutar o envio do mesmo período não gera mensagem duplicada, e um cliente com erro não impede o envio dos outros. - [ ] O mês corrente, quando aparece, vem rotulado como parcial. ### Context document ```text Relatório recorrente ao cliente - O relatório cobre um cliente e um período fechado: semana de segunda a domingo ou mês calendário, no fuso do cliente. Mês corrente só como parcial, com rótulo. - Todo número sai do placar calculado no warehouse. A leitura escrita não traz número que não esteja no placar. - Comparações: período anterior de mesmo tamanho (_ant), média das 4 últimas semanas (_med4) e variação (_var). Nunca parcial contra cheio. - Custo por resultado = soma do investimento / soma do resultado do período. - Seção sem conector ligado no cliente sai do relatório; não entra com zero. Se o pipeline não rodou, diga isso. - Siga a estrutura aprovada do cliente: ordem das seções, quadros e cores do documento de modelo dele. - Se faltar meta, premissa ou entrega do período, pergunte antes de montar. Nunca estime. - Print ou valor informado só quando a tabela não existe; nunca para completar número que o warehouse tem. - Cliente com status de churn não recebe relatório; apenas sinalize. Exceções por cliente: - : relatório semanal, seções na ordem , modelo aprovado em . - : é dado manual, informado pelo time até o dia . - : resultado do relatório = , custo com imposto de %. ``` ### Variações - **Resumo diário:** Ontem por cliente, curto, para o time de mídia, com Meta e Google lado a lado. - **Renovação:** Jornada do ciclo inteiro e proposta de continuidade, em vez de mês contra mês. - **Janelas móveis:** Últimos 30, 90, 180 e 365 dias contra a janela anterior de mesmo tamanho.