# 🏛️ 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.