📑 Controladoria — Gestão de Outliers de Faturamento¶

1. O que é este módulo?¶

O módulo de Controladoria é a ferramenta central para auditoria e saneamento de dados de faturamento. Ele permite que as equipes de Controladoria, Comercial e Administradores identifiquem, justifiquem e alterem o status de transações identificadas como outliers — ou seja, lançamentos que fogem do padrão esperado e precisam de revisão antes de entrar nos relatórios oficiais.

O módulo trabalha com um conceito de versionamento: cada alteração em um registro gera uma nova versão (V1, V2, V3...), preservando todo o histórico de mudanças. Isso garante rastreabilidade total e permite que auditores reconstruam a linha do tempo de qualquer decisão.

Exemplo prático: Uma venda de R$ 500.000 é marcada automaticamente como "Em análise" porque excede o ticket médio da loja. O analista de controladoria revisa, conclui que foi uma venda legítima para um grande produtor rural e altera o status para "Aprovado", registrando a justificativa. Essa ação fica gravada permanentemente no sistema.

2. Telas Disponíveis¶

O módulo é dividido em três abas, acessíveis pela barra lateral:

Aba	Finalidade
📤 Upload	Envio de planilhas com novos outliers ou ajustes em lote
✏️ Editar	Edição individual ou em massa de outliers já carregados
🔍 Consultar	Consulta de histórico, auditoria de versões e painel analítico (BI)

3. Como Usar — Passo a Passo¶

📤 Aba Upload — Enviando uma planilha de outliers¶

Esta aba permite carregar uma planilha Excel com dados de faturamento que precisam de revisão. O sistema valida, enriquece e carrega os dados automaticamente.

Passo a passo:

Acesse o módulo Controladoria no Dashboard
Selecione a aba "Upload" na barra lateral
Faça o upload do arquivo Excel (.xlsx) ou CSV
Aguarde a validação automática — o sistema verificará:
Se todas as colunas obrigatórias estão presentes
Se os status informados são válidos
Se as lojas e produtos existem na base de dados
Se o arquivo já foi enviado anteriormente (duplicidade)
Se existem outliers com chaves duplicadas
Revise o Resumo Executivo — antes de processar, o portal exibe:
Métricas de impacto: Soma de Receita Líquida, CMV e Lucro Bruto
Distribuição por status: Quantos registros estão como Aprovados, Reprovados, Em Análise
Agrupamento por segmento: Distribuição por categoria de produto (Defensivos, Fertilizantes, etc.)
Se houver duplicatas, o sistema informará quais chaves já existem e perguntará se deseja gerar novas versões (sobrescrever) ou cancelar
Clique em "Processar" para enviar os dados ao BigQuery
O sistema executa automaticamente o SQL de transformação para atualizar a tabela Gold

Dica: O sistema detecta e remove automaticamente linhas de "Total" e rodapés de filtros comuns em exportações do Power BI, evitando sujeira nos dados.

✏️ Aba Editar — Ajustando outliers existentes¶

Esta aba permite alterar a justificativa e o status de outliers que já estão no sistema, tanto individualmente quanto em lote.

Passo a passo — Edição Individual:

Aplique filtros para localizar os outliers desejados:
Período (data início / data fim)
Loja (seleção por nome, busca dinâmica)
Status atual (Em análise, Aprovado, Reprovado, Outlier Manual)
Material/SKU (busca por código ou nome do produto)
Cliente (busca por código ou nome)
Justificativa (filtro por texto)
Arquivo de origem ou Enviado por
Clique em "Buscar" para carregar os registros
Para cada registro, altere a justificativa e/ou o status nos campos disponíveis
Clique em "Salvar" — o sistema cria uma nova versão (V+1) do registro na camada Silver

Passo a passo — Edição em Lote:

Selecione múltiplos registros usando os checkboxes
Defina a nova justificativa e o novo status que serão aplicados a todos
Clique em "Salvar em Lote" — todos os registros selecionados serão atualizados em uma transação única (ou salva tudo, ou nada)
Após o salvamento, o sistema executa automaticamente o SQL para reconstruir a tabela Gold

Importante: A edição nunca sobrescreve dados. Cada alteração gera uma nova linha com versao + 1, preservando o histórico completo.

Exportação: A qualquer momento, você pode exportar os resultados da busca para um arquivo Excel (.xlsx).

🔍 Aba Consultar — Auditoria e Analytics¶

A tela de consulta oferece três sub-abas para análise completa:

Sub-aba 1: 📥 Meus Uploads¶

Permite rastrear todos os arquivos que você enviou ao sistema.

Histórico pessoal: Lista de arquivos, datas de upload e quantidade de linhas processadas
Recuperação: Botão de download que gera um Excel com a versão mais atual de cada registro daquele upload

Sub-aba 2: 📜 Histórico de Versões¶

O coração da rastreabilidade. Permite investigar o histórico completo de qualquer lançamento.

Busca granular: Filtros por período, loja, produto e cliente
Linha do tempo: Exibe cada alteração como uma versão (V1, V2, V3...)
Detecção de mudanças: O sistema destaca o que mudou entre versões (ex: "Status: EM ANÁLISE → APROVADO"), facilitando auditorias de compliance

Sub-aba 3: 📊 Painel de Analytics (BI)¶

Dashboard analítico que transforma dados brutos em visão estratégica:

Evolução Temporal: Gráficos de barras empilhadas mostrando a vazão de análise mês a mês
Performance por Usuário: Ranking de produtividade e percentuais de aprovação por analista
Visão Geográfica e de Mix: Identificação de lojas e produtos que mais geram inconsistências (Top Offenders)
Análise Financeira: Consolidação de Receita, CMV e Margem afetados pelos outliers

4. Validações¶

O sistema executa uma "malha fina" de validações antes de permitir qualquer inserção:

Validações de Estrutura¶

Regra	Descrição
Colunas obrigatórias	O arquivo deve conter: data, conta, loja, produto, cliente, justificativa e status
Domínio de Status	Apenas quatro valores são aceitos: `Em análise`, `Aprovado`, `Reprovado`, `Outlier Manual`
Preservação de códigos	Colunas como `cod_loja`, `cod_produto` e `doc_referencia` são sempre lidas como texto, preservando zeros à esquerda (ex: `03105` não se torna `3105`)

Validações de Negócio¶

Regra	Descrição
Existência de Loja	O `cod_loja` informado deve existir na `dim_estrutura_comercial` do Datalake
Existência de Produto	O `cod_produto` é validado contra a tabela de produtos cadastrados
Duplicidade de Arquivo	Se um arquivo com o mesmo nome já foi enviado, o sistema informa quem o enviou e quando
Duplicidade de Registro	Uma chave composta (`outlier_key` = Data + Conta + Loja + Produto + Cliente + Doc) é verificada. Se a chave já existir, o usuário pode escolher entre gerar nova versão ou cancelar

Validações de Formato¶

Regra	Descrição
Moeda brasileira	Valores como `R$ 1.000,50` são convertidos automaticamente para formato numérico
Datas flexíveis	Aceita tanto `DD/MM/AAAA` quanto `AAAA-MM-DD`
Limpeza de lixo do BI	Remove automaticamente linhas de "Total" e rodapés de filtros do Power BI
Enriquecimento de Loja	O sistema consulta a `dim_estrutura_comercial` para adicionar o nome amigável da loja ao lado do código

5. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Finalidade
Silver	`lavoro_portal_outliers_faturamento`	Armazena todas as versões de cada outlier (histórico bruto). Usado nas consultas de auditoria e histórico.
Gold	`fato_faturamento_outlier`	Tabela processada contendo apenas a última versão de cada outlier. Alimenta dashboards e KPIs.
Dimensional	`dim_estrutura_comercial`	Proporciona nomes de lojas, hierarquia comercial e códigos para enriquecimento de dados.

Fluxo de Dados¶

graph LR
    A[📄 Planilha Excel] --> B[Portal Upload]
    B --> C{Validação}
    C -->|✅ OK| D[Silver - BigQuery]
    C -->|❌ Erro| E[Relatório de Erros]
    D --> F[SQL Transformação]
    F --> G[Gold - BigQuery]
    G --> H[📊 Dashboards BI]

Campos de Auditoria¶

Cada registro gravado contém:

uploaded_by — E-mail do usuário que fez o upload/edição
uploaded_at — Data e hora UTC exata da operação
arquivo_origem — Nome do arquivo de origem
versao — Número da versão (1, 2, 3...)
outlier_key — Chave única composta que identifica o lançamento

6. Controle de Acesso¶

Role	Permissões
admin	Acesso completo — Upload, Edição e Consulta
controladoria	Acesso completo — Upload, Edição e Consulta
comercial	Acesso restrito conforme configuração

7. Tratamento de Erros¶

Cenário	Como o sistema reage
Coluna ausente no arquivo	Erro detalhado listando quais colunas estão faltando
Valor em formato inválido	Tabela mostrando a linha exata do Excel, a coluna e o motivo do erro
Falha de conexão com BigQuery	Captura via `try/except` com mensagem de erro amigável e log técnico expansível
Bloqueio durante processamento	A interface fica bloqueada enquanto o SQL de transformação está rodando, evitando envios duplicados
Edição em lote	Processamento em transação única — se uma linha falhar, nenhuma é salva (atomicidade)

📅 Documentação atualizada em Março 2026.