--- id: casos/relatorios-dashboards area: BI uso: muito usado esforco: médio grao: Um grão por tabela, escrito no nome e na descrição (ex.: unidade x dia, anúncio x dia, vendedor x mês) --- # Relatórios e dashboards automáticos Uma tabela gold por painel, com grão declarado e regras fechadas, que o BI só lê: o número do dashboard bate com a fonte, se atualiza sozinho e mostra quando foi a última carga. ## Resumo executivo **Para quem:** Empresas que montam relatório exportando planilha toda semana e querem um dashboard que se atualiza sozinho e bate com a fonte. **O que resolve** - O dashboard se atualiza depois de cada carga, sem ninguém exportar CSV. - O número do painel bate com o sistema de origem e com o relatório que ele substitui. - Todo mundo vê a data da última atualização e sabe se o número está velho. **Por que importa:** Quando o cálculo mora no BI, cada painel faz a conta de um jeito: um tira média de taxa, outro soma o total junto com as linhas, outro soma seguidores por dia. A reunião vira debate sobre qual número está certo. Com a regra na gold, o BI só desenha, o agente de IA lê a mesma tabela e o número só muda quando o dado muda. **Perguntas de negócio que responde** - Quanto vendemos neste mês por vendedor e qual a taxa de conversão de cada um? - Qual o custo por resultado de cada canal nas últimas quatro semanas? - O pipeline criado neste trimestre está acima ou abaixo do anterior? - Qual unidade está mais longe da meta do mês? - O painel de hoje já inclui os números de ontem? **O que você precisa** - As fontes conectadas na Nekt (CRM, faturamento, mídia, ERP) - A lista de perguntas que o painel responde e o relatório atual de referência - A ferramenta de BI ou o destino do portal **O que você recebe** - Uma tabela gold por painel, com grão no nome e regras aplicadas - Colunas aditivas para o BI recalcular taxas no recorte escolhido - Um cartão de frescor com a data da última carga de cada fonte - Um teste de paridade com o relatório antigo ou o sistema de origem ## Detalhado ### O problema O relatório é exportado do CRM para uma planilha toda segunda e o cálculo vive em fórmulas e campos calculados do BI. Quando alguém muda o filtro, o total não fecha. Quando a ingestão para, o painel continua mostrando o número velho sem aviso. Quando o relatório muda de ferramenta, o número muda junto e ninguém sabe qual está certo. ### Regras de negócio 1. **Uma gold por painel, com o grão no nome.** Cada painel lê uma tabela gold com grão único, escrito no nome e numa frase da descrição ('uma linha por anúncio por dia'). Tabela com nome mensal não recebe dado diário. A chave de atualização é o próprio grão: chave diferente do grão duplica linhas em silêncio. (Evite: Uma tabela genérica que mistura dia, mês e linhas de total.) 2. **Taxa se recalcula, não se soma.** CTR, CPC, CPM, ticket médio, taxa de conversão e custo por resultado guardados por linha são médias e não somam. A gold entrega as colunas aditivas (investimento, cliques, impressões, receita, quantidade) e o BI recalcula a taxa como soma sobre soma no recorte filtrado. Taxa sem denominador é nula, não zero. (Evite: Média da coluna CTR no Looker Studio.) 3. **Linha de total não convive com o detalhe.** Se a gold traz uma linha de total (todas as regiões, todos os canais), ela vem marcada e nunca é somada às linhas de detalhe. Na dúvida, deixe o total para o BI. (Evite: Total e detalhe na mesma coluna, sem marcação.) 4. **Retrato não é métrica diária.** Seguidores, alcance deduplicado de vida inteira, saldo e estoque são retratos. Quando aparecem repetidos em todas as linhas de data, não somam: o painel usa o último valor do período. Recortes em formato longo (idade, gênero, posicionamento, dispositivo) são filtrados um tipo de recorte por vez, ou o total sai multiplicado. (Evite: Somar seguidores por dia ou somar todos os recortes juntos.) 5. **Uma data oficial por métrica.** Cada métrica tem a sua data de referência escrita: lead pela data de criação, venda pela data de ganho, receita pela data de pagamento ou de competência. O período é fechado e no fuso local, e o mês corrente aparece rotulado como parcial. (Evite: Filtrar todas as métricas pela data de criação do registro.) 6. **Paridade antes de desligar o relatório antigo.** Ao migrar de planilha, Power BI, Qlik ou outro BI, reproduza os nomes e os números do relatório atual. Medida que o BI calculava com média ponderada por linhas de histórico precisa vir com o peso na gold. Compare mês fechado contra mês fechado e só depois desligue o antigo. A partir daí, a gold é a fonte canônica e outras fontes são conferência. (Evite: Trocar o painel e explicar a diferença depois.) 7. **Frescor visível no painel.** Ingestão que para não gera erro, só números parados. A gold carrega a data da última carga de cada fonte (a partir de _nekt_sync_at, convertida para o fuso local) e o painel mostra esse cartão. Para fontes de volume diário, um alerta de completude compara o dia com o pico recente, por exemplo menos de 70% das lojas com venda. (Evite: Painel sem data de atualização.) 8. **Atualização por evento, não por relógio.** A gold roda depois que a fonte termina, por gatilho de evento. Agendar num horário fixo cria painel com metade do dado em dia de atraso, e gatilho manual é esquecido. (Evite: Agendamento fixo às 8h, independente da carga.) 9. **Parametrize em vez de copiar.** Um painel por unidade, serviço ou cliente não justifica uma transformação por botão. Uma gold com a dimensão (unidade, serviço, cliente) e o filtro no BI substitui dezenas de cópias quase iguais, que divergem com o tempo. (Evite: Uma transformação por botão do dashboard.) 10. **Tipos que o BI e o destino entendem.** Alguns conectores de BI quebram com timestamp: entregue data como data e, se preciso, timestamp como texto. Destinos Postgres podem reinterpretar meia-noite UTC no fuso local e jogar a venda para o dia anterior: grave a data comercial como data, já na gold. (Evite: Mandar timestamp UTC e deixar o BI converter.) ### Como o BI agrega cada tipo de coluna A gold entrega o tipo certo; o painel só aplica a agregação. - **Investimento, receita, quantidade, cliques** → Aditiva (`soma`) - **CTR, CPC, CPM, ticket, conversão** → Taxa (`soma do numerador / soma do denominador`) - **Seguidores, saldo, estoque, alcance de vida inteira** → Retrato (`último valor do período`) - **Clientes, pedidos, notas** → Contagem distinta (`contar distinto no período, não somar dias`) - **Idade, gênero, posicionamento** → Recorte longo (`um tipo de recorte por vez`) - **Todas as regiões, todos os canais** → Linha de total (`nunca somar ao detalhe`) ### Definições | Métrica | Definição | |---|---| | Grão | o que uma linha representa, escrito em uma frase; igual à chave de atualização da tabela | | Coluna aditiva | valor que soma em qualquer dimensão e período: investimento, receita, quantidade, cliques, impressões | | Taxa do recorte | soma do numerador / soma do denominador no recorte filtrado; nula quando o denominador é zero | | Retrato | valor medido num instante (seguidores, saldo, estoque); no período, vale o último valor | | Última carga | maior _nekt_sync_at da tabela de origem, convertido para o fuso local | | Paridade | diferença entre o número da gold e o do relatório de referência, no mesmo período fechado, por métrica | | Mês parcial | mês corrente até o último dia fechado, sempre rotulado no painel | ### Armadilhas - **Média de taxas.** O painel mostrava a média do CTR diário por anúncio e o número não batia com o gerenciador da plataforma. Como evitar: Entregue cliques e impressões e recalcule no BI. - **Ingestão parada por mais de um mês.** Uma fonte parou sem erro. O mês aparecia com cerca de um quarto dos lançamentos reais e o relatório de cliente herdou o número velho. Como evitar: Cartão de frescor no painel e alerta de completude. - **Dezenas de cópias da mesma consulta.** Cada botão do dashboard tinha a sua transformação quase igual. Uma correção de regra precisou ser repetida em todas e algumas ficaram para trás. Como evitar: Uma gold parametrizada pela dimensão. - **Venda no dia errado.** O destino Postgres reinterpretou meia-noite UTC no fuso local e as vendas de cada dia caíram no dia anterior. Como evitar: Grave a data comercial como data na gold. - **Seguidores multiplicados.** O painel somava o número de seguidores repetido em todas as linhas de data, e o total do mês saía multiplicado pelos dias. Como evitar: Retrato usa o último valor do período. - **Número diferente do BI antigo.** O BI antigo calculava médias ponderadas por linhas de histórico e a nova tabela fazia média simples por registro. Os dois números circularam juntos. Como evitar: Traga o peso para a gold e documente qual versão é a oficial. ### Teste de aceitação - [ ] Para um mês fechado, cada métrica do painel bate com o relatório de referência (diferença abaixo de 1%). - [ ] A tabela gold tem exatamente uma linha por valor do grão declarado, sem chave duplicada. - [ ] Trocar o recorte do painel (período, unidade, canal) mantém cada taxa igual à soma sobre soma das colunas aditivas. - [ ] O cartão de frescor mostra a mesma data da última carga da fonte, e com a fonte parada o alerta dispara no dia seguinte. ### Context document ```text Painéis e tabelas gold de métricas - O número oficial de cada painel vem da tabela gold dele: = . Silver, raw e o próprio BI são conferência, não fonte. - Grão de cada tabela: : uma linha por . - Taxas (CTR, CPC, CPM, ticket médio, conversão, custo por resultado) não se somam nem se tira média: soma do numerador / soma do denominador no recorte. Denominador zero = nulo. - Retratos (seguidores, saldo, estoque, alcance de vida inteira) usam o último valor do período, nunca a soma. - Linhas marcadas como total nunca se somam às linhas de detalhe. - Data oficial: lead = ; venda = ; receita = . - Mês corrente é parcial e vem rotulado. Comparações usam períodos fechados de mesmo tamanho. - Toda resposta traz a data da última carga da fonte. Se a carga tiver mais de horas, avise que o número pode estar desatualizado. Exceções por cliente: - : o painel reproduz o relatório ; a medida é média ponderada por . - : a unidade é matriz sem venda direta; ausência de linhas não é erro. ``` ### Variações - **Migração de BI legado:** Reproduzir nomes e números do Qlik, Power BI ou planilha antes do corte, com teste de paridade por mês fechado. - **Portal do cliente:** Filtro por cliente ou uma tabela por cliente, sem dado pessoal, enviada para o app do cliente. - **Planilha como painel:** Abas automáticas escritas só pela rotina, com as abas manuais preservadas.