# 🔄 Análise Real do Fluxo de Negócio - SIGEFP

**Data:** 2025-01-XX  
**Objetivo:** Analisar o fluxo REAL de negócio e identificar problemas na lógica e integrações

---

## ✅ Funcionalidades Existentes (Confirmadas)

### Módulo Orçamento

1. **Exercícios Fiscais** (`/budget/fiscal-years`)
   - ✅ Criar, abrir, fechar exercícios
   - ✅ Status: DRAFT → OPEN → CLOSED

2. **Linhas Orçamentárias** (`/budget/lines`)
   - ✅ Criar, editar linhas
   - ✅ **Dotações:** Botão Wallet (💼) abre modal `BudgetLineEntriesModal`
   - ✅ Modal permite criar, visualizar todas as dotações da linha
   - ✅ Tipos: INITIAL_ALLOCATION, SUPPLEMENTARY_CREDIT, etc.

3. **Execução** (`/budget/execution`)
   - ✅ Visualizar COMMITMENT, LIQUIDATION, PAYMENT
   - ✅ Filtros por tipo, período, linha orçamentária

### Módulo Tesouro

1. **Contas de Caixa** (`/treasury/cash-accounts`)
2. **Autorizações** (`/treasury/authorizations`)
3. **Lotes de Pagamento** (`/treasury/batches`)
4. **Ordens de Pagamento** (`/treasury/orders`)
5. **Conciliação** (`/treasury/reconciliation`)
6. **Confirmações** (`/treasury/confirmations`)

---

## 🔍 Análise do Fluxo Real de Negócio

### Fluxo 1: Elaboração do Orçamento (Como Funciona)

```
1. Orçamento → Exercícios Fiscais
   └─> Criar exercício (DRAFT)
   
2. Orçamento → Linhas Orçamentais
   └─> Criar rubricas
   
3. Orçamento → Linhas Orçamentais → Botão Wallet (💼)
   └─> Modal: BudgetLineEntriesModal
   └─> Criar dotação (INITIAL_ALLOCATION)
   └─> Referência: "Lei nº X/2024"
   └─> ✅ Atualiza BudgetLine.totalAllocated
   
4. Orçamento → Exercícios Fiscais
   └─> Abrir exercício (OPEN)
```

**✅ Status:** Funcional e correto

---

### Fluxo 2: Execução Orçamentária (Como Funciona)

#### 2.1 Empenho (COMMITMENT)

**Origem:** Módulo RH (folha de pagamento)

```
PayrollRun processado
    ↓
PaymentOrder criado (com budgetLineId)
    ↓
BudgetIntegrationService.createCommitmentFromPayroll()
    ↓
BudgetExecution (COMMITMENT) criado
    ↓
BudgetLine.totalCommitted atualizado
    ↓
BudgetLine.availableBalance reduzido
```

**Onde visualizar:** `Orçamento → Execução` (filtro: COMMITMENT)

**✅ Status:** Implementado e funcionando

---

#### 2.2 Liquidação (LIQUIDATION)

**Origem:** Módulo RH (no encerramento da folha)

```
PayrollRun encerrado
    ↓
BudgetIntegrationService.createLiquidationFromPayrollItem()
    ↓
BudgetExecution (LIQUIDATION) criado
    ↓
Validação: Deve ter COMMITMENT correspondente
    ↓
BudgetLine atualizado
```

**Onde visualizar:** `Orçamento → Execução` (filtro: LIQUIDATION)

**✅ Status:** Implementado e funcionando

---

#### 2.3 Pagamento (PAYMENT)

**Origem:** Módulo Tesouro (após confirmação)

```
TreasuryPayment confirmado (status: PAID)
    ↓
TreasuryPaymentService.confirmPayment()
    ↓
BudgetIntegrationService.createPaymentFromTreasury()
    ↓
BudgetExecution (PAYMENT) criado
    ↓
Validação: Deve ter LIQUIDATION correspondente
    ↓
BudgetLine atualizado
```

**Onde visualizar:** `Orçamento → Execução` (filtro: PAYMENT)

**✅ Status:** Implementado e funcionando

---

### Fluxo 3: Processo de Pagamento (Tesouro)

```
1. Tesouro → Ordens de Pagamento
   └─> Criar ordem (origem: PayrollRun ou Manual)
   └─> Validação: Verifica saldo orçamentário (se budgetLineId presente)
   
2. Tesouro → Autorizações
   └─> Criar autorização para ordem
   └─> Workflow: Aprovação hierárquica (níveis 1, 2, 3)
   └─> Validação: Verifica disponibilidade de caixa
   
3. Tesouro → Lotes de Pagamento
   └─> Criar lote
   └─> Adicionar ordens ao lote
   └─> Compromete: CashAccount.availableBalance
   
4. Tesouro → Confirmações
   └─> Confirmar pagamento
   └─> Atualiza: CashAccount.currentBalance
   └─> ✅ Cria BudgetExecution (PAYMENT) automaticamente
   └─> Registra: CashFlow (OUTFLOW)
```

**✅ Status:** Implementado e funcionando

---

## 🔗 Integrações Entre Módulos

### RH → Orçamento

**Fluxo:**
```
PayrollRun (status: COMPLETED)
    ↓
PaymentOrderService.createFromPayrollRun()
    ↓
BudgetIntegrationService.createCommitmentFromPayroll()
    ↓
BudgetExecution (COMMITMENT) criado
```

**Validações:**
- ✅ Verifica se há saldo disponível (availableBalance)
- ✅ Cria COMMITMENT com referenceId = PayrollRun.id

**Status:** ✅ Funcionando

---

### RH → Tesouro

**Fluxo:**
```
PayrollRun (status: COMPLETED)
    ↓
PaymentOrderService.createFromPayrollRun()
    ↓
PaymentOrder criado (com budgetLineId)
    ↓
PaymentOrder.status = CREATED
```

**Validações:**
- ✅ Verifica se há saldo orçamentário (se budgetLineId presente)
- ✅ Cria ordem com referência ao PayrollRun

**Status:** ✅ Funcionando

---

### Tesouro → Orçamento

**Fluxo:**
```
TreasuryPayment (status: PAID)
    ↓
TreasuryPaymentService.confirmPayment()
    ↓
BudgetIntegrationService.createPaymentFromTreasury()
    ↓
BudgetExecution (PAYMENT) criado
```

**Validações:**
- ✅ Verifica se há LIQUIDATION correspondente
- ✅ Valida que PAYMENT <= LIQUIDATION disponível
- ✅ Cria PAYMENT com referenceId = TreasuryPayment.id

**Status:** ✅ Funcionando

---

## ❓ Questões para Investigar

### 1. Como iniciar o processo de elaboração?

**Resposta:**
1. Criar Exercício Fiscal (DRAFT)
2. Criar Linhas Orçamentárias
3. **Clicar no botão Wallet (💼) em cada linha** → Criar dotações
4. Abrir Exercício Fiscal (OPEN)

**Problema Potencial:**
- ⚠️ O botão Wallet pode não ser intuitivo para novos usuários
- ⚠️ Não há indicação clara de que é necessário criar dotações antes de abrir o exercício

---

### 2. Como a execução se conecta com o Tesouro?

**Resposta:**
- RH cria PaymentOrder → Cria COMMITMENT automaticamente
- Tesouro confirma pagamento → Cria PAYMENT automaticamente
- A conexão é automática via `BudgetIntegrationService`

**Problema Potencial:**
- ⚠️ Pode não estar claro que a integração é automática
- ⚠️ Falta visibilidade do link entre PaymentOrder e BudgetExecution

---

### 3. Como visualizar o fluxo completo?

**Resposta:**
- `Orçamento → Execução`: Mostra todos os movimentos (COMMITMENT, LIQUIDATION, PAYMENT)
- `Orçamento → Linhas Orçamentais`: Mostra saldos (Alocado, Comprometido, Disponível)

**Problema Potencial:**
- ⚠️ Falta visão consolidada do fluxo end-to-end
- ⚠️ Não há rastreamento visual do link entre PaymentOrder e BudgetExecution

---

## 🎯 Recomendações

### 1. Melhorar UX do Botão de Dotações

**Problema:** Botão Wallet pode não ser intuitivo

**Solução:**
- Adicionar tooltip mais descritivo: "Gerir Dotações"
- Adicionar badge com número de dotações (se houver)
- Adicionar indicador visual se linha não tem dotações

---

### 2. Adicionar Validação ao Abrir Exercício

**Problema:** Pode abrir exercício sem dotações

**Solução:**
- Validar se há pelo menos uma dotação antes de abrir
- Mostrar aviso se linhas não têm dotações
- Opção: Bloquear abertura se não houver dotações

---

### 3. Melhorar Rastreabilidade

**Problema:** Difícil rastrear link entre PaymentOrder e BudgetExecution

**Solução:**
- Adicionar coluna "Referência" em BudgetExecution mostrando PaymentOrder.id
- Adicionar link para PaymentOrder na página de Execução
- Adicionar link para BudgetExecution na página de Ordens de Pagamento

---

### 4. Criar Dashboard de Fluxo

**Problema:** Falta visão consolidada

**Solução:**
- Dashboard mostrando:
  - Exercício Fiscal atual
  - Total alocado vs comprometido vs pago
  - Gráfico de execução (COMMITMENT → LIQUIDATION → PAYMENT)
  - Status de integrações (RH, Tesouro)

---

## 📋 Checklist de Melhorias

### UX/UI
- [ ] Melhorar tooltip do botão Wallet
- [ ] Adicionar badge com número de dotações
- [ ] Adicionar indicador se linha não tem dotações
- [ ] Adicionar validação ao abrir exercício

### Rastreabilidade
- [ ] Adicionar coluna "Referência" em BudgetExecution
- [ ] Adicionar links entre PaymentOrder e BudgetExecution
- [ ] Adicionar breadcrumbs nas páginas

### Documentação
- [ ] Criar guia visual do fluxo end-to-end
- [ ] Documentar integrações automáticas
- [ ] Criar diagrama de sequência

### Dashboard
- [ ] Criar dashboard consolidado
- [ ] Adicionar gráficos de execução
- [ ] Mostrar status de integrações

---

**Documento gerado em:** 2025-01-XX  
**Versão:** 1.0