Idrissa Banora
124 lines
5.5 KiB
Markdown
124 lines
5.5 KiB
Markdown
# 🏛️ 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.
|