--- id: casos/kpis-historicos area: BI uso: comum esforco: médio grao: KPI x período (dia ou mês fechado) x lote de carga --- # KPIs históricos numa planilha viva Uma foto de cada indicador por período, gravada quando o período fecha e nunca reescrita, numa planilha que se atualiza sozinha e guarda a tendência que o sistema de origem esquece. ## Resumo executivo **Para quem:** Empresas que acompanham indicadores mês a mês e hoje dependem de print, planilha copiada ou de um sistema que só mostra o valor de agora. **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. **Por que importa:** Muitas fontes só mostram o estado de hoje ou uma janela curta: o CRM reescreve a etapa, a API de redes sociais começa há poucos meses, a ferramenta de atendimento guarda poucas semanas. Recalcular o histórico a cada execução reescreve o passado, e o número da reunião de agosto muda em setembro. Sem a foto guardada no dia, não existe tendência confiável. **Perguntas de negócio que responde** - Como evoluíram receita, clientes ativos e churn nos últimos 12 meses? - O número de agosto que apresentamos é o mesmo que está na planilha hoje? - Quais indicadores estão abaixo da meta há três meses seguidos? - Quantos seguidores tínhamos no fim de cada mês do ano passado? - Quem é o dono de cada indicador e quando foi o último lançamento? **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 ## Detalhado ### O problema 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. ### Regras de negócio 1. **A foto é gravada no fechamento, não recalculada.** 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. (Evite: Recalcular todos os meses a partir do estado atual das fontes.) 2. **Transformação SQL não guarda histórico.** 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. (Evite: Snapshot em SQL que sobrescreve a tabela inteira.) 3. **Fonte de janela curta precisa de acumulador.** 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. (Evite: Confiar que a API devolve o histórico quando precisar.) 4. **Catálogo de KPIs com id estável.** 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. (Evite: Colunas da planilha renomeadas a cada trimestre.) 5. **Cada carga é um lote, e o último válido vence.** 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. (Evite: Apagar e regravar o valor do mês quando alguém corrige.) 6. **Mês fechado congela em duas rodadas.** 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. (Evite: Deixar o mês aberto para sempre.) 7. **Status do dado em cada valor.** 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. (Evite: Gravar zero quando a fonte não carregou.) 8. **Estoque, fluxo e taxa se guardam diferente.** 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. (Evite: Somar os clientes ativos de cada mês para ter o ano.) 9. **A planilha só lê.** 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. (Evite: O time editando o número na mesma aba que a rotina sobrescreve.) ### 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. - **Identificador estável do catálogo** → KPI (`kpi_id`) - **Dia ou mês de referência, fechado** → Período (`data`) - **Valor, e numerador e denominador quando é taxa** → Valor (`valor`) - **ok, parcial ou ausente** → Status do dado (`status_dado`) - **Identificador e sequência da carga** → Lote (`batch_id, carga_seq`) - **Rotina ou pessoa, e quando** → Origem (`preenchido_por, preenchido_em`) - **Provisório, final ou ajuste** → Fechamento (`versao`) ### Definições | Métrica | Definição | |---|---| | Valor do KPI | valor do indicador para um kpi_id e um período, gravado por um lote; a leitura usa o lote válido de maior sequência | | KPI de estoque | valor no último dia do período: clientes ativos, seguidores, saldo, MRR | | KPI de fluxo | soma dos eventos do período: vendas, leads, cancelamentos | | Taxa | numerador do período / denominador do período, gravados separados; trimestre e ano recalculados a partir das somas | | Período fechado | dia anterior no fuso local ou mês calendário encerrado; o período corrente é parcial | | Mês congelado | mês com versão final gravada; só muda por ajuste registrado | | Cobertura da série | períodos com status ok / períodos desde o início do KPI | ### Armadilhas - **O mês encolheu depois da reunião.** 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. Como evitar: Carimbe o veredito no dia do evento e não reescreva. - **Uma gravação apagou semanas.** Uma execução sobrescreveu a tabela de fotos e cerca de três semanas tiveram de ser reconstruídas. Como evitar: Modo de acréscimo e trava contra gravação vazia. - **A API só devolvia semanas.** 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. Como evitar: Acumulador por id desde a primeira carga. - **Rede social sem passado.** A API de uma rede social só cobria os meses recentes; anos de série diária existiam apenas numa planilha exportada antes. Como evitar: Suba o histórico uma vez como fonte congelada e una com a série nova num corte seco por data. - **Recarga que apagou meses.** Uma recarga completa de eventos falhou no meio e apagou meses da tabela de origem. Como evitar: Tire uma cópia congelada antes de qualquer recarga completa. - **Zero que era falta de carga.** Um dia útil sem nenhum registro de nenhuma conta apareceu como zero na série; era falha de carga da fonte. Como evitar: Status ausente, não zero, e alerta de lacuna. ### Teste de aceitação - [ ] 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. ### Context document ```text KPIs históricos - A série oficial está em ; leia pela visão , 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 . 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: - : o KPI mudou de definição em ; antes disso a série usa . - : o histórico de antes de vem de . - : câmbio de reporte = média do mês de , congelado no fechamento. ``` ### Variações - **Lançamento manual:** Lideranças lançam os KPIs que não têm fonte automática por uma rotina que valida contra o catálogo. - **Meta x realizado:** A meta entra como outro valor do mesmo kpi_id, com a versão do plano congelada. - **Foto semanal de entidades:** Para campos que o CRM não versiona, uma foto semanal do negócio ao lado da série de KPI.