📑 Contabilidade — Fechamento Contábil¶

1. O que é este módulo?¶

O módulo de Contabilidade permite que o time de Controladoria comunique ao Datalake quais períodos contábeis estão fechados para apuração de resultados. Diferente dos outros módulos que trabalham com upload de planilhas, este módulo funciona como um editor direto — o usuário altera o status dos períodos (de "ABERTO" para "FECHADO") diretamente na interface, sem necessidade de preparar planilhas.

Quando um período é marcado como "FECHADO", os dashboards de BI passam a considerar aquelas empresas como tendo seus números consolidados, permitindo que análises financeiras utilizem dados definitivos em vez de provisórios.

Exemplo prático: No dia 15 de cada mês, a equipe de controladoria finaliza o fechamento de janeiro para todas as investidas. O analista entra no módulo, filtra o mês de janeiro, altera o status de cada empresa para "FECHADO" (com justificativa), e os dashboards passam a refletir que aquela investida tem dados consolidados para janeiro.

2. Telas Disponíveis¶

Aba	Finalidade
✏️ Editor	Interface de edição direta para alterar o status de fechamento dos períodos contábeis

Nota: Este módulo possui apenas a aba de Editor. Não há upload de planilhas — a gestão é feita diretamente na tela.

3. Como Usar — Passo a Passo¶

✏️ Gerenciando o fechamento contábil¶

Passo a passo:

Acesse o módulo "Contabilidade" no Dashboard
Selecione o ano e mês que deseja gerenciar nos filtros
Filtre por investida (opcional) — para focar em empresas específicas
Filtre por status (opcional) — para ver apenas períodos "ABERTO" ou "FECHADO"
Visualize os KPIs de progresso no topo da tela:
Percentual de empresas já fechadas para o mês selecionado
Total de empresas pendentes
Altere o status dos períodos desejados:
Utilize o editor em tabela (st.data_editor) para alterar múltiplos status de uma vez
Para cada alteração, selecione o novo status: ABERTO ou FECHADO
Escreva uma justificativa no campo de texto:
A justificativa é obrigatória — o botão de salvar permanece desabilitado até que você escreva o motivo da alteração
Exemplo: "Fechamento mensal concluído após validação com contabilidade da matriz"
Clique em "Salvar" para persistir as alterações:
O sistema compara o estado atual com o estado original e processa apenas as linhas efetivamente modificadas
Cada alteração gera uma nova versão (V+1) do registro, preservando o histórico completo
Após o salvamento, o sistema executa automaticamente o SQL dim_fechamento_contabil.sql para atualizar a tabela Gold, refletindo a mudança nos dashboards quase em tempo real

Dica: Você pode exportar a tabela completa para Excel usando o botão de download, facilitando análises offline ou compartilhamento com o time.

4. Funcionalidades Especiais¶

Inicialização Automática (Self-Healing)¶

Ao acessar o módulo, o sistema verifica automaticamente se os períodos do mês atual e do próximo mês já existem na tabela Silver. Se estiverem ausentes, ele utiliza uma instrução MERGE atômica para criar os registros, evitando lacunas no cronograma de fechamento.

Isso significa que você nunca encontrará um mês "faltando" — o sistema se auto-corrige a cada acesso.

Versionamento de Registros¶

O módulo não sobrescreve dados. Cada alteração gera uma nova linha com versao + 1, preservando: - Quem alterou (e-mail do usuário) - Quando alterou (data/hora UTC) - O que justificou (texto da justificativa) - Status anterior e novo

KPIs de Progresso em Tempo Real¶

No topo da tela, métricas dinâmicas calculam automaticamente: - Percentual de empresas com fechamento concluído - Quantidade de empresas pendentes - Progresso geral do mês selecionado

5. Validações¶

Regra	Descrição
Justificativa obrigatória	Nenhuma alteração é salva sem uma justificativa textual. O botão "Salvar" permanece desabilitado até que o campo seja preenchido.
Detecção de mudanças	O sistema compara o estado do editor com o DataFrame original para processar apenas as linhas efetivamente modificadas, evitando gravações desnecessárias.
Self-healing de períodos	Se o mês atual ou o próximo mês não existirem na tabela, são criados automaticamente via `MERGE` atômico.
Proteção contra duplicidade	O uso de `MERGE` no SQL garante que múltiplos usuários acessando a página simultaneamente não criem registros duplicados.
Sanitização de tipos	Antes da exportação para Excel ou do salvamento no BigQuery, informações de fuso horário são removidas para garantir compatibilidade.

6. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Finalidade
Silver	`lavoro_portal_dim_fechamento_contabil`	Histórico bruto de todas as versões — armazena cada alteração de status com metadados de controle
Gold	`dim_fechamento_contabil`	Tabela consolidada com a última versão de cada empresa/mês, consumida pelos dashboards de BI
Dimensional	`dim_estrutura_comercial`	Lista de empresas (investidas) com IDs e nomes amigáveis

Arquitetura Lakehouse (Medallion)¶

graph LR
    A[✏️ Editor do Portal] --> B[Silver: Histórico Completo]
    B --> C[SQL dim_fechamento_contabil]
    C --> D[Gold: Última Versão]
    D --> E[📊 Dashboards BI]

Multi-Ambiente¶

O módulo alterna automaticamente entre datasets com base na variável de ambiente: - DEV/QA: silver_operacoes_qa, gold_operacoes_qa - PROD: silver_operacoes_prod, gold_operacoes_prod

Campos de Auditoria¶

updated_by — E-mail do usuário que alterou
updated_at — Data e hora UTC da alteração
justificativa — Texto explicativo obrigatório
versao — Número da versão do registro

7. Controle de Acesso¶

Role	Permissões
admin	Acesso completo ao editor
contabilidade	Acesso ao editor de fechamento

8. Tratamento de Erros¶

Cenário	Como o sistema reage
Falha de conexão BQ	Captura via `try/except` com alerta amigável e log técnico expansível
Race condition	O `MERGE` no SQL garante que acessos simultâneos de múltiplos usuários não criem duplicatas
Estouro de memória	Uso de `st.cache_data` para metadados de empresas, reduzindo queries repetitivas
Processamento longo	Uso de `st.progress` e `st.spinner` para indicar o andamento de operações no banco, evitando múltiplos cliques acidentais

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