Faturamento

O módulo Faturamento do SuperBusiness é o painel analítico de vendas — onde o gerente abre uma vez por dia (ou por semana) pra entender como o negócio está rodando.

O que aparece

A tela tem três blocos:

1. 8 KPI cards no topo (com animação de contagem)
2. Filtros expansíveis (por período, empresa, cidade)
3. 6 gráficos abaixo

Os 8 KPIs

KPI	O que mede
Total de Registros	Quantidade de vendas no período filtrado
Faturamento Bruto	Soma dos valores brutos das vendas (antes de descontos)
Faturamento Líquido	Soma dos valores depois de descontos
Ticket Médio	Líquido / quantidade de vendas
Valor à Vista	Soma das vendas pagas à vista
Valor a Prazo	Soma das vendas pagas a prazo
Descontos	Total de descontos concedidos no período
Empresas Únicas	Quantas empresas (clientes) compraram no período

Todos respeitam os filtros aplicados.

Filtros

Clique em Filtros para expandir o painel. Opções:

• Período: Hoje · Este mês · Este ano · Customizado (data inicial + data final)
• Empresa: dropdown com todas as empresas (clientes) ativas no período
• Cidade: dropdown com todas as cidades onde há cliente

Os filtros são aplicados em tempo real assim que você muda — tudo recarrega.

Gráficos

Gráfico	Tipo	Para que serve
Formas de pagamento	Barra + Pizza	Mostra distribuição (à vista vs cartão vs boleto etc)
Evolução mensal	Linha	Faturamento bruto e líquido mês a mês
Top 5 empresas	Barra horizontal	Ranking dos maiores clientes do período
À vista vs a prazo	Pizza	Composição do mix de pagamentos
Faturamento anual	Barra	Visão por ano — clicar abre drilldown mensal desse ano

O drilldown anual é útil pra entender o histórico: clica num ano, vê os 12 meses; clica de novo na barra do ano pra voltar.

De onde vêm os dados

O Faturamento puxa de funções RPC no Supabase (PostgreSQL):

• get_faturamento_stats — calcula os 8 KPIs
• get_faturamento_por_mes — série mensal/anual
• get_faturamento_por_empresa — ranking de empresas
• get_formas_pagamento_stats — composição de formas de pagamento
• get_empresas_list / get_cidades_list — popula os filtros

Essas funções leem de uma tabela busi_faturamento que é alimentada por job de ETL (cron na Supersys que extrai do SQL Server e consolida no Supabase). A consulta direta no SQL Server seria pesada para muitos registros — daí o pré-cálculo no Supabase.

Então o delay entre venda e aparecer aqui depende do ETL: hoje é tipicamente diário (atualização noturna). Em casos urgentes, pedir ao TI para rodar o ETL manualmente.

Restrições por role

Não há restrição visível no código — qualquer usuário logado consegue abrir Faturamento se tiver o item de menu visível. Quem controla o menu é o useMenuPermissions, que filtra módulos por role e tenant.

Na prática, vendedores típicos não veem este módulo (não está liberado pro role user). Gerentes (admin) e direção (superadmin) sim.

Triagem rápida — suporte

Sintoma	Causa provável	Ação
KPIs todos zerados mesmo com vendas no período	ETL não rodou; tabela busi_faturamento não atualizada	Pedir TI rodar get_faturamento_stats manualmente; verificar logs do cron
Filtro por empresa vazio	get_empresas_list falhou ou tenant sem vendas	Conferir se há registros em busi_faturamento para o tenant
Gráfico anual aparece com gap (anos faltando)	Anos sem dados não aparecem na série; comportamento intencional	OK
Drilldown anual não abre ao clicar	Versão antiga do front em cache	Atualizar app (notificação "Atualizar app agora")
Ticket médio aparece muito alto/baixo	Pode estar somando bruto e dividindo por contagem incorreta — depende da semântica do RPC	Investigar com TI; comparar com cálculo manual
"Vejo dados de outro tenant"	Bug grave de RLS — escalar imediatamente	Reportar segurança ao TI

Para o time técnico

• Cliente Supabase: db.rpc<any>(name, params) em src/services/faturamento-service.ts.
• Os RPCs aceitam parâmetros p_tenant_cod, p_data_inicio, p_data_fim, p_empresa, p_cidade. RLS no Supabase garante que cada usuário só veja seu tenant.
• Tabela alimentada via ETL — não é tempo real. Se precisar real-time, considerar ler direto do SQL Server via API .NET, mas com ressalvas de performance.
• Cards animados usam contagem progressiva com requestAnimationFrame (não é só CSS) — se houver freeze visível, é overhead na máquina do usuário, não no servidor.