Duas Planilhas, Duas Verdades: O Problema Não É Técnico

Introdução: A Meia Hora Que Ninguém Recupera

Você pede o faturamento do mês e recebe dois números.

Um vem do sistema. O outro vem da planilha que alguém mantém em paralelo. Eles não batem. E ninguém consegue explicar a diferença em menos de meia hora, porque cada pessoa tem uma resposta diferente para a mesma pergunta.

Quando isso acontece, o problema deixou de ser técnico faz tempo.

A Planilha Paralela É o Sintoma

Ela existe por um motivo simples: em algum momento, alguém não confiou no relatório e resolveu controlar por fora.

A partir desse dia, a empresa passa a ter duas versões da verdade. E a decisão passa a depender de qual delas a pessoa abriu primeiro.

O custo não aparece na conta de infraestrutura. Aparece em reunião que começa com "espera, qual número está certo?", em metas que ninguém mede do mesmo jeito e em gente nova que aprende as duas versões ao mesmo tempo.

As Causas São Banais

Quase sempre, a divergência vem de definições diferentes para a mesma palavra:

• O relatório conta o pedido pela data em que foi feito. A planilha conta pela data em que foi pago.
• Um inclui pedidos cancelados. O outro não.
• O frete entra em um e não entra no outro.
• O desconto aparece como valor negativo num lugar e como preço menor em outro.
• O fuso horário muda o dia: o pedido pago às 23h30 de 31 de outubro cai em novembro para um servidor que trabalha em UTC.

Nenhum desses é erro de cálculo. Cada versão está correta dentro da sua própria regra.

O problema é que essas regras nunca foram escritas em lugar nenhum.

A Solução Mais Barata: Escrever a Definição

Antes de pedir um painel novo, vale resolver o que custa menos e entrega mais: escrever a definição de cada número que importa.

Para cada indicador, responda em uma frase:

• O que conta? Pedido, pagamento, entrega?
• A partir de quando? Data de criação, de confirmação, de pagamento? Em qual fuso?
• Descontando o quê? Cancelamentos, devoluções, descontos, frete, impostos?

Enquanto essa frase não existir, cada relatório novo vai produzir um número novo. E mais uma planilha.

Como Isso Vira Código

Essa definição não deveria ficar só num documento. Ela deveria estar no código, num lugar por onde todos os relatórios passam.

// Uma única fonte de verdade para cada indicador
export const metricDefinitions = {
  revenue: {
    label: "Faturamento (pago)",
    definition:
      "Soma dos pedidos pagos, pela data do pagamento no horário de Brasília, sem cancelados nem devolvidos, sem frete, já descontados os cupons.",
    dateField: "paidAt",
    statuses: ["paid", "delivered"],
    includeShipping: false,
    subtractDiscounts: true,
  },
  ordersCreated: {
    label: "Pedidos criados",
    definition:
      "Quantidade de pedidos criados no período, independente do status de pagamento.",
    dateField: "createdAt",
    statuses: "all",
  },
} as const;

Repare no que isso resolve:

• Faturamento e pedidos criados são métricas diferentes, com nomes diferentes. Ninguém mais confunde uma com a outra.
• Cada decisão de regra fica explícita e versionada. Quando alguém perguntar "por que o frete não entra?", a resposta está no Git, com data e autor.
• Todos os relatórios usam a mesma definição. O painel, a exportação e o e-mail mensal leem a mesma configuração, desde que nenhum deles monte a própria consulta por fora.

Esse último ponto é o que costuma escapar. Por isso vale levar a mesma regra para o banco, como uma view, para que consultas avulsas também a respeitem:

CREATE VIEW revenue_by_payment_date AS
SELECT
  DATE_TRUNC('day', paid_at AT TIME ZONE 'America/Sao_Paulo') AS day,
  -- subtotal: soma dos itens, sem frete
  SUM(subtotal - discount_amount) AS revenue
FROM orders
WHERE status IN ('paid', 'delivered')
  AND paid_at IS NOT NULL
GROUP BY 1;

Agora existe uma coisa que pode ser consultada e auditada. Não depende de quem montou a planilha.

Trade-offs: Definição Única Não Significa Um Único Número

Vale um cuidado: ter uma definição oficial não impede que existam outras perguntas legítimas.

Quer saber quanto entrou por data de criação para analisar o funil? Ótimo. Só não chame esse número de faturamento.

O objetivo não é eliminar variações. É dar nome a cada uma. "Faturamento (pago)" e "Pedidos criados" podem coexistir. A confusão começa quando as duas aparecem com o mesmo rótulo.

Checklist: Seus Números Têm Dono?

• Cada indicador importante tem uma frase de definição escrita?
• Essa definição diz a data de referência, o fuso, os status incluídos e os descontos aplicados?
• O relatório do sistema e o da planilha usam a mesma regra?
• Existe um nome diferente para cada variação de cálculo?
• Cada indicador tem uma pessoa responsável pela definição?
• Quando a regra muda, alguém registra o motivo e a data?

Se a resposta for "não" para a maioria, o próximo painel vai nascer com o mesmo problema.

Conclusão: Antes do Painel, a Frase

Um painel bonito não resolve divergência. Ele só mostra um dos números com mais estilo.

Antes de investir em ferramenta de BI, escreva o que cada número significa. Uma frase por indicador. Depois, faça o código obedecer essa frase.

Quando a definição existe, a discussão deixa de ser "qual planilha está certa" e passa a ser "essa regra ainda faz sentido?". Essa é uma conversa muito mais útil.

Quer Organizar Seus Indicadores?

Se a sua empresa tem mais de uma versão da verdade e quer um sistema em que os números batem, posso ajudar com:

• Diagnóstico de métricas: mapear indicadores, divergências e definições conflitantes
• Camada de métricas no código: uma fonte única de verdade para relatórios e painéis
• Modelagem de dados para relatórios: views, agregações e rastreabilidade

Vamos alinhar os números da sua empresa →