Files

T

Idrissa Banora 52a7c4f9cf feat: otimização de performance e ajustes finais

2026-05-19 11:41:28 +00:00

5.5 KiB

Raw Blame History

🏛️ Arquitetura Completa de Orçamento para GFP/SIGFIP

Data: 2025-12-22 Objetivo: Documentar a arquitetura técnica e funcional do Módulo de Orçamento, implementada e otimizada pelo Antigravity/Deepmind, garantindo conformidade com normas de Gestão Financeira Pública (PFM).

📋 Entendimento & Conformidade

Filosofia Arquitetural

O módulo foi desenhado para seguir o princípio de "Single Source of Truth" (Fonte Única de Verdade) para todas as autorizações de gastos do governo. Ele não apenas armazena números, mas rastreia a Autoridade Legal para gastar.

Pilares Fundamentais (Implementados)

Dotação baseada em Direito (Appropriation): O dinheiro não "aparece" no saldo. Ele entra via BudgetEntry (Lei, Decreto).
Estrutura vs. Financiamento: A Rubrica (BudgetLine) define onde se pode gastar, mas não quanto. O valor vem das Entradas.
Execução Rígida: Nenhum gasto ocorre sem saldo de Dotação (Allocation) e Saldo Financeiro (Treasury).
Imutabilidade Contábil: Transações passadas não são editadas, apenas estornadas ou corrigidas com novas transações.

🏗️ Estrutura de Componentes

1. BudgetEntry (O Coração da Dotação)

Entidade responsável por injetar "autoridade de gasto" no sistema.

Propósito: Registrar movimentos legais de crédito orçamentário. Fluxo: Lei do Orçamento -> BudgetEntry (INITIAL_ALLOCATION) -> BudgetLine.totalAllocated.

Campos:

id (UUID)
type (Enum: INITIAL_ALLOCATION, SUPPLEMENTARY_CREDIT, CANCELLATION, TRANSFER_IN, TRANSFER_OUT)
amount (BigDecimal) - Sempre positivo. O tipo define se soma ou subtrai.
transactionDate (LocalDate) - Data da Lei/Ato.
documentReference (String) - Ex: "Lei nº 12/2024".
budgetLine (ManyToOne) - A Rubrica afetada.

2. BudgetLine (A Estrutura de Despesa)

Representa a "conta" onde a despesa acontece (Ex: "Aquisição de Medicamentos").

Otimização de Performance (Antigravity): Implementado padrão Read-Model optimization usando @Formula do Hibernate para evitar N+1 e N+2 queries.

totalAllocated: Soma dinâmica SQL de todas as BudgetEntry relacionadas.
totalCommitted: Soma dinâmica SQL de todas as BudgetExecution relacionadas.
availableBalance: Calculado em memória (Allocated - Committed).

3. FiscalYear (Controle Temporal)

Gerencia o ciclo de vida do ano orçamentário.

Segurança de Memória (Anti-Crash): Utiliza queries de contagem (COUNT) otimizadas para validar o fechamento (close()).

Impede fechamento se houver COMMITMENT (Empenho) sem LIQUIDATION ou anulação.
Garante integridade referencial temporal.

4. BudgetExecution (O Consumo)

Registra o consumo do orçamento em estágios.

Estágios (MovementType):

COMMITMENT (Empenho): Reserva o saldo. O dinheiro ainda está lá, mas não pode ser usado por outro.
LIQUIDATION (Liquidação): Reconhece a dívida (bem entregue/serviço prestado).
PAYMENT (Pagamento): Saída financeira (Integração com Tesouro).

🔄 Workflow & Integrações

Fluxo 1: Criação do Orçamento (Aprovação)

[Legislativo] -> (Aprova Lei)
(Aprova Lei) -> [Sistema] : Cria BudgetEntry (INITIAL)
[Sistema] -> [BudgetLine] : Atualiza totalAllocated (automático)

Fluxo 2: Execução de Despesa (RH/Compras)

[Módulo RH] -> [IntegrationService] : Solicita Empenho (COMMITMENT)
[IntegrationService] -> [BudgetLine] : Verifica availableBalance
[IntegrationService] -> [BudgetExecution] : Cria Registro
[BudgetLine] -> [BudgetLine] : Reduz availableBalance (automático)

Fluxo 3: Pagamento (Tesouraria) e Reconciliação

[Tesouraria] -> [PaymentOrder] : Executa Pagamento
[PaymentOrder] -> [IntegrationService] : Notifica Pagamento
[IntegrationService] -> [BudgetExecution] : Cria Registro (PAYMENT)
[BudgetExecution] -> [BudgetLine] : Atualiza status de execução

📊 Serviços Principais (Implementados)

BudgetLineService

Responsável pela "Visão do Gestor".
DTOs enriquecidos com cálculos de saldo em tempo real.
Performance: Otimizado para listar milhares de rubricas sem derrubar o banco.

BudgetEntryService

Responsável pela "Visão do Contador/Legislador".
Garante que créditos suplementares tenham fonte de recursos.

BudgetIntegrationService

O "Gateway" seguro.
Protege o módulo de chamadas inválidas de RH e Tesouraria.
Exige ReferenceId (ID do Pedido, ID da Folha) para evitar lançamentos órfãos.

🔐 Regras de Negócio Rígidas (Strict PFM)

Bloqueio de Despesa: É impossível criar um COMMITMENT se amount > availableBalance. (Exceptions de negócio).
Imutabilidade de Histórico: Uma BudgetExecution não pode ser deletada se já tiver etapas posteriores (ex: não pode apagar Empenho se já tem Liquidação). Deve-se estornar a Liquidação primeiro.
Fechamento Seguro: Ano Fiscal só fecha se todas as contas baterem (Zero pendências).

🚀 Status Técnico Atual

Arquitetura: ✅ Completa e Validada.
Testes: ✅ Testes Unitários Críticos Implementados (BudgetLineServiceTest, FiscalYearServiceTest).
Performance: ✅ Otimização N+2 e OOM resolvidas.
Frontend: ✅ Telas de Gestão de Dotação e Execução operacionais.

Esta arquitetura garante que o sigefp-budget seja não apenas um "caderninho de anotações", mas um Motor de Controle Financeiro robusto e escalável.

5.5 KiB Raw Blame History