--- id: casos/relatorios-por-email area: Operação uso: comum esforco: baixo grao: Público x período (dia útil, semana ou mês fechado) --- # Relatórios diários por email Cada público recebe por email ou no chat, no horário combinado, só os números que precisa ler, de um período fechado, sem envio duplicado e com aviso quando o dado atrasou. ## Resumo executivo **Para quem:** Gestores que começam o dia abrindo várias ferramentas para montar o mesmo resumo, e times que precisam que a informação chegue até eles. **O que resolve** - O resumo chega pronto, no horário, para cada público, sem ninguém montar. - Cada pessoa recebe só o que é dela: a diretoria o consolidado, o gerente a sua unidade. - Quando o dado atrasa, a mensagem avisa em vez de mandar número velho. **Por que importa:** A rotina muda o comportamento: a informação vai até as pessoas e o desvio aparece antes da reunião. Mas um email com número errado, duplicado ou de dois dias atrás perde a confiança mais rápido que um painel, porque chega na caixa de todo mundo ao mesmo tempo. Regra de período, checagem de frescor e log de envio são o que faz a rotina durar. **Perguntas de negócio que responde** - Quanto faturamos ontem e como está o acumulado do mês contra a meta? - Quantas negociações novas entraram ontem em cada funil? - Quais contratos já consumiram mais de 80% do que foi vendido? - O que mudou nesta semana em relação à semana anterior? - Quem do time ficou sem registrar atividade no último dia útil? **O que você precisa** - As métricas do resumo em tabelas gold, com regra fechada - A lista de públicos, o que cada um recebe, por qual canal e em que horário - A credencial do canal de envio guardada como segredo na Nekt **O que você recebe** - Um placar por público e período, calculado no warehouse - A mensagem montada a partir do placar, com comparação e destaques - Um log de envio que impede reenvio e mostra falhas - Aviso automático quando a fonte não carregou ## Detalhado ### O problema O resumo diário é uma consulta agendada no relógio que manda o que estiver na tabela. Na segunda-feira compara com domingo; no dia em que a carga atrasou, manda o número de anteontem como se fosse de ontem; no reprocessamento, manda duas vezes; quando um destinatário falha, os outros não recebem. Meses depois, a rotina continua rodando e gastando crédito para um canal que ninguém lê. ### Regras de negócio 1. **O número vem do placar; a mensagem só redige.** Calcule numa tabela, por público e período, cada métrica com o valor atual, o período anterior e a variação. A rotina de envio só formata. Se houver texto escrito por IA, ela recebe o placar pronto e não traz número que não esteja nele; a prioridade dos destaques também é calculada na tabela, não pelo modelo. (Evite: Calcular dentro do script de envio ou deixar a IA somar.) 2. **Dia útil fechado, no fuso local.** O resumo diário cobre o dia anterior no fuso do negócio. Em rotina de dias úteis, a segunda-feira analisa a sexta e feriados nacionais são pulados. A semana é definida uma vez (segunda a domingo ou domingo a sábado) e escrita. O mês corrente vem como acumulado parcial, nunca comparado com mês cheio. (Evite: Data atual menos um, em UTC, todos os dias, inclusive na segunda.) 3. **Compare janelas do mesmo tamanho.** Dia contra o mesmo dia da semana anterior, semana contra semana, acumulado do mês contra os mesmos dias do mês anterior. Variação de taxa sai em pontos percentuais; base muito pequena vira variação em reais. (Evite: Segunda contra domingo, mês parcial contra mês cheio.) 4. **Cada público recebe o seu recorte.** A lista de destinatários vive numa tabela (público, canal, destino, recorte, horário), não no código. Diretoria recebe o consolidado; gerente, a sua unidade; vendedor ou assessor, a sua carteira. Linha de outra unidade nunca vai para quem não deveria ver. Cliente que saiu da carteira deixa de receber. (Evite: Um email igual para todos, com tudo.) 5. **Frescor antes de enviar.** Antes do envio, confira se a tabela de origem tem o dia de referência. Se não tiver, espere uma janela curta e, se não chegar, envie avisando de quando é o dado, ou não envie. Um bloco de sinal de vida (quantos registros entraram nas últimas 24 horas) denuncia ingestão parada. (Evite: Enviar no horário com o que estiver na tabela.) 6. **Um envio por público e período.** Grave cada envio num log (público, período, canal, status, horário). Reexecutar não reenvia o que já foi. A falha de um destinatário não interrompe os outros, e falha de envio faz a execução falhar de forma visível. Mensagens longas são partidas no limite do canal. (Evite: Reprocessar e mandar de novo para todos.) 7. **Modo seco, piloto, depois a lista.** Toda rotina nova roda primeiro sem enviar (modo seco), depois para um destinatário interno e só então para a lista real. Mensagem para cliente pode nascer como rascunho, revisado por alguém antes do envio. (Evite: Ligar o envio direto na lista inteira.) 8. **Pouco número, ordem fixa.** Abra com uma leitura de até cinco linhas antes de qualquer tabela. Mostre o que pede ação: o que saiu da faixa, o que estourou, o que está em risco. A ordem dos blocos é fixa (mês atual antes do anterior, consolidado antes do detalhe), para o leitor achar o mesmo lugar todo dia. Valores em padrão brasileiro, com rodapé de fonte e data da carga. (Evite: Colar a tabela inteira no corpo do email.) 9. **Desligue o que ninguém lê.** Destino desligado, canal sem leitura ou relatório substituído continuam consumindo crédito. Revise as rotinas periodicamente e pause as que não têm leitor, registrando o motivo e a data. (Evite: Deixar a consulta rodando depois que o canal morreu.) ### Ritmo e recorte por público Um ponto de partida comum nos workspaces. Ajuste o horário à rotina de cada time. - **Diretoria** → Consolidado do dia e acumulado do mês contra a meta (`dia útil, cedo`) - **Gerente de unidade** → Só a própria unidade, com ranking interno (`dia útil, cedo`) - **Time comercial ou operação** → Atividade por pessoa no dia útil anterior (`dia útil`) - **Gestão de contratos ou CS** → Estourados, zona de atenção e sem movimento (`semanal, sexta`) - **Cliente da agência ou consultoria** → Placar do período com estrutura aprovada (`segunda ou mês fechado`) ### Definições | Métrica | Definição | |---|---| | Dia de referência | dia útil anterior à execução no fuso local; na segunda-feira, a sexta; feriados nacionais pulados | | Semana | segunda a domingo (ISO) ou outra regra escrita, sempre fechada | | Acumulado do mês | do dia 1 até o dia de referência, comparado com os mesmos dias do mês anterior | | Variação | valor do período - valor do período anterior de mesmo tamanho; em taxas, em pontos percentuais | | Envio | uma linha no log por público, período e canal com status enviado; reexecução com o mesmo trio não envia | | Frescor da origem | maior data de negócio da tabela de origem comparada com o dia de referência | | Zona de atenção | item a partir do limite declarado de consumo ou desvio, por exemplo 80% do contratado | ### Armadilhas - **Número de dois dias atrás.** A cadeia de cargas atrasou e o resumo saiu no horário com o número de anteontem, sem aviso. Como evitar: Cheque a data da origem antes de enviar e avise. - **Ingestão parada por semanas.** Uma fonte ficou mais de um mês sem carregar e ninguém percebeu, porque nada avisava. O mês aparecia com uma fração dos lançamentos reais. Como evitar: Bloco de sinal de vida com o volume das últimas 24 horas. - **Envio duplicado ou faltando.** Um erro num destinatário interrompia todos, e a nova tentativa reenviava para quem já tinha recebido. Como evitar: Log por público e período e falha isolada por destinatário. - **Crédito gasto sem leitor.** O destino do chat foi desligado e a consulta seguiu rodando todos os dias por mais de um mês. Como evitar: Pause rotinas sem destino ativo e registre o motivo. - **Rotina pesada que parou.** Um resumo diário em Spark passou a falhar em sequência, sem mensagem de erro útil. Reescrito em Python simples, voltou a rodar. Como evitar: Rotina de envio é leve: notebook Python lendo o placar pronto. - **Segunda-feira sempre em queda.** Comparar ontem com anteontem fazia toda segunda parecer queda, porque o domingo não tem a mesma operação. Como evitar: Dia útil anterior e comparação com o mesmo dia da semana anterior. ### Teste de aceitação - [ ] Para um dia de referência, cada número da mensagem bate com a consulta à tabela gold no mesmo dia. - [ ] Rodar a rotina duas vezes no mesmo dia gera uma única linha de envio por público no log e uma única mensagem. - [ ] Com a tabela de origem sem o dia de referência, a rotina envia o aviso de atraso ou não envia, e nunca envia o número do dia anterior como se fosse o de referência. - [ ] Na segunda-feira, o resumo de dias úteis cobre a sexta; depois de um feriado nacional, cobre o último dia útil. - [ ] Um gerente recebe zero linhas de outra unidade. ### Context document ```text Resumo agendado por público - Cada resumo cobre um período fechado no fuso America/Sao_Paulo: diário = dia útil anterior (segunda cobre sexta, feriados nacionais pulados); semanal = ; mensal = mês calendário fechado. - Todo número vem do placar . A mensagem não traz número que não esteja no placar. - Comparações em janelas de mesmo tamanho: dia contra o mesmo dia da semana anterior, semana contra semana, acumulado do mês contra os mesmos dias do mês anterior. Taxas variam em pontos percentuais. - Antes de enviar, confira se a origem tem o dia de referência. Se não tiver, envie com o aviso 'dados até ' ou não envie. - Destinatários, canal, horário e recorte vêm da tabela . Ninguém recebe linhas fora do seu recorte. - Um envio por público e período: consulte o log antes de enviar. - Estrutura: leitura de até cinco linhas e depois os blocos na ordem . - Valores em padrão pt-BR, sem emoji, com rodapé de fonte e data da última carga. Exceções por cliente: - : resumo diário às para , recorte . - : mensagem criada como rascunho e revisada por antes do envio. - : semana de domingo a sábado. ``` ### Variações - **Leitura escrita por IA:** O modelo recebe o placar pronto e redige destaques e alertas, sem calcular nada. - **Alerta por exceção:** A mesma rotina só envia quando algo sai da faixa, como saldo de conta de anúncio para poucos dias úteis. - **Relatório para o cliente:** Um placar por cliente e período, com estrutura aprovada por ele e seções sem fonte retiradas.