Golds de métricas, fontes de janela curta e lançamentos manuais
Foto no fechamento, só acréscimo, catálogo validado
Série de KPI por período, com status e lote
Planilha viva, painel de tendência e agente de IA
O que resolve
- O número de um mês fechado não muda depois de apresentado.
- Fontes que só guardam as últimas semanas deixam de apagar o passado.
- Indicadores automáticos e manuais ficam numa série só, com dono e definição.
Perguntas de negócio que responde
Faça estas perguntas ao seu agente quando o caso estiver pronto.
O que você precisa
- As métricas de origem em tabelas gold ou fontes conectadas
- Um catálogo dos indicadores: nome, definição, unidade, dono e periodicidade
- A planilha de destino ou o painel de tendência
O que você recebe
- Uma tabela de valores de KPI só de acréscimo, com lote de carga e status do dado
- Uma visão de leitura com o último valor válido de cada KPI e período
- Meses fechados congelados, com correção registrada como ajuste
- A planilha viva com a série, atualizada depois de cada carga
Onde ativar
Reverse ETL para o Google Sheets em abas automáticas, com a série e o último valor por KPI.
Série de 12 ou 24 meses lida da tabela congelada.
Responde sobre a evolução com o número que foi apresentado, não com um recálculo.
O cálculo de cada KPI costuma existir. O trabalho é montar o catálogo, gravar a foto no momento certo e começar já: o passado que a fonte apagou não volta. O detalhado traz as regras de negócio, as armadilhas e o teste de aceitação. Ou mande tudo direto para o seu agente com o MCP da Nekt.
A planilha de KPIs é preenchida à mão ou recalculada do zero a cada execução. Quando o CRM muda a etapa de um negócio ou uma regra de classificação é ajustada, os meses passados mudam junto. Quando a API só devolve as últimas semanas, o histórico some. E a transformação que deveria guardar as fotos recria a tabela inteira a cada execução. No fim, ninguém confia na série e cada reunião começa conferindo número.
Como costuma ser feito, e a regra
Cada linha é um erro que já aconteceu na prática.
Para cada KPI e período, grave o valor quando o período fecha (dia anterior fechado, mês fechado) numa tabela só de acréscimo. Recalcular a série inteira a cada execução reescreve o passado: num caso real, uma regra de qualificação ajustada no meio do mês passou a valer para cadastros antigos e o número de um mês já apresentado encolheu sozinho.
A transformação SQL na Nekt recria a tabela a cada execução e apagaria as fotos anteriores. Para acumular, use notebook gravando em modo de acréscimo ou merge, ou uma consulta que lê a própria tabela de saída e substitui só o período corrente. Recuse gravar quando o resultado vier vazio: uma gravação vazia apaga a série.
Analytics, gráficos de produto, redes sociais e ferramentas de atendimento costumam devolver só uma janela que anda, de dias ou semanas. Acumule numa tabela própria, um registro por dia ou por id, sem apagar, com a primeira e a última extração. A janela rolante não repovoa o passado: o que não foi guardado se perdeu. Por isso o acumulador começa hoje.
Cada indicador tem um kpi_id que nunca muda, nome, definição, unidade, tipo de valor, dono, área e periodicidade. Lançamento de KPI fora do catálogo é rejeitado. Mudar a definição de um KPI que já tem histórico exige decisão explícita e revisão da série, ou um KPI novo.
Cada execução grava um lote com identificador, número de sequência, quem preencheu (rotina ou pessoa) e quando. O lote é tudo ou nada: uma linha inválida rejeita o lote inteiro. A leitura usa, por KPI e período, o valor do lote de maior sequência. Reexecutar o mesmo lote não grava de novo.
No fechamento, grave uma versão provisória e permita uma correção, que vira final. Correção posterior entra como ajuste, com o período de referência registrado, sem reescrever o número final. Reabrir um mês congelado é ação manual, com motivo e responsável.
Grave se o valor é ok, parcial ou ausente. Dia sem carga da fonte não vira zero: fica ausente, e uma lacuna gera alerta. O mês corrente entra como parcial e não se compara com mês fechado.
KPIs de estoque (clientes ativos, seguidores, saldo, MRR) são o valor no último dia do período. KPIs de fluxo (vendas, leads, cancelamentos) são a soma do período. Taxas se gravam com numerador e denominador, para recalcular trimestre e ano. Valor convertido de moeda guarda a taxa usada no mês e congela junto.
A série chega à planilha por reverse ETL, em abas automáticas que só a rotina escreve. Abas manuais (comentários, metas) ficam separadas e nunca são sobrescritas. Lançamento manual de KPI entra pela tabela de lançamentos, validado contra o catálogo, e não digitado na aba automática.
O que cada linha da série guarda
Uma linha por KPI, período e lote. A leitura fica com o último lote válido.
Definições
Armadilhas que já aconteceram
Uma regra de qualificação recalculada a cada execução passou a valer para cadastros antigos, e o número de um mês caiu depois de apresentado.
Carimbe o veredito no dia do evento e não reescreva.
Uma execução sobrescreveu a tabela de fotos e cerca de três semanas tiveram de ser reconstruídas.
Modo de acréscimo e trava contra gravação vazia.
A ferramenta de atendimento entregava só as últimas semanas de tickets, e o mês anterior tinha menos da metade dos tickets reais na tabela.
Acumulador por id desde a primeira carga.
A API de uma rede social só cobria os meses recentes; anos de série diária existiam apenas numa planilha exportada antes.
Suba o histórico uma vez como fonte congelada e una com a série nova num corte seco por data.
Uma recarga completa de eventos falhou no meio e apagou meses da tabela de origem.
Tire uma cópia congelada antes de qualquer recarga completa.
Um dia útil sem nenhum registro de nenhuma conta apareceu como zero na série; era falha de carga da fonte.
Status ausente, não zero, e alerta de lacuna.
Teste de aceitação
O caso está pronto quando todos os itens passam.
- Rodar a rotina de novo para um mês com versão final não altera nenhum valor desse mês.
- Para cada KPI e período existe exatamente um valor na visão de leitura, e ele é o do lote de maior sequência.
- O valor de um mês fechado na planilha é igual ao da tabela de valores e ao apresentado no fechamento.
- Um lote com um kpi_id fora do catálogo é rejeitado inteiro e nenhuma linha dele aparece na série.
- A série de uma fonte de janela curta tem um registro por dia desde a primeira carga, sem buracos além dos marcados como ausente.
Pacote para o agente
Cole no Claude, ChatGPT ou outro cliente com o MCP da Nekt conectado.
KPIs históricos - A série oficial está em <tabela de valores>; leia pela visão <visão de leitura>, que traz o último lote válido por KPI e período. - Cada KPI tem kpi_id, definição, unidade, dono e periodicidade no catálogo <tabela de catálogo>. Use a definição do catálogo. - Meses com versão final não mudam. Correções posteriores aparecem como ajuste, com o mês de referência. - O mês corrente é parcial: não compare com mês fechado. - KPIs de estoque (clientes ativos, seguidores, saldo, MRR) = valor no último dia do período; nunca some meses. - KPIs de fluxo = soma do período. Taxas: recalcule trimestre e ano a partir de numerador e denominador. - Status ausente não é zero: diga que não há dado para aquele período. - Nunca recalcule um período fechado a partir das tabelas de origem para responder; use a série. Exceções por cliente: - <cliente>: o KPI <kpi_id> mudou de definição em <data>; antes disso a série usa <regra antiga>. - <cliente>: o histórico de <fonte> antes de <data> vem de <planilha congelada>. - <cliente>: câmbio de reporte = média do mês de <fonte da taxa>, congelado no fechamento.
Construa no meu workspace Nekt o caso "KPIs históricos numa planilha viva" seguindo as regras em https://academy.nekt.com/casos/kpis-historicos.md. 1) Encontre as tabelas de origem e confirme as colunas usadas pelas regras. 2) Crie uma transformação no grão indicado aplicando todas as regras. 3) Rode o teste de aceitação e me mostre o resultado de cada item. 4) Crie o context document do caso no workspace, com as exceções dos meus clientes em aberto para eu preencher.
Variações
Lideranças lançam os KPIs que não têm fonte automática por uma rotina que valida contra o catálogo.
A meta entra como outro valor do mesmo kpi_id, com a versão do plano congelada.
Para campos que o CRM não versiona, uma foto semanal do negócio ao lado da série de KPI.