feat: otimização de performance e ajustes finais

2026-05-18 10:49:32 +00:00
commit 52a7c4f9cf
579 changed files with 156489 additions and 0 deletions
@@ -0,0 +1,123 @@
+# 🏛️ 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)
+1.  **Dotação baseada em Direito (Appropriation):** O dinheiro não "aparece" no saldo. Ele entra via `BudgetEntry` (Lei, Decreto).
+2.  **Estrutura vs. Financiamento:** A Rubrica (`BudgetLine`) define *onde* se pode gastar, mas não *quanto*. O valor vem das Entradas.
+3.  **Execução Rígida:** Nenhum gasto ocorre sem saldo de Dotação (Allocation) e Saldo Financeiro (Treasury).
+4.  **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):**
+1.  **COMMITMENT (Empenho):** Reserva o saldo. O dinheiro ainda está lá, mas não pode ser usado por outro.
+2.  **LIQUIDATION (Liquidação):** Reconhece a dívida (bem entregue/serviço prestado).
+3.  **PAYMENT (Pagamento):** Saída financeira (Integração com Tesouro).
+
+---
+
+## 🔄 Workflow & Integrações
+
+### Fluxo 1: Criação do Orçamento (Aprovação)
+```plantuml
+[Legislativo] -> (Aprova Lei)
+(Aprova Lei) -> [Sistema] : Cria BudgetEntry (INITIAL)
+[Sistema] -> [BudgetLine] : Atualiza totalAllocated (automático)
+```
+
+### Fluxo 2: Execução de Despesa (RH/Compras)
+```plantuml
+[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
+```plantuml
+[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)
+
+1.  **Bloqueio de Despesa:** É *impossível* criar um `COMMITMENT` se `amount > availableBalance`. (Exceptions de negócio).
+2.  **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.
+3.  **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.