sigrhapf/Documents/sigfip/sigefp/ARQUITETURA_COMPLETA_TESOURO_GFP.md

# 🏛️ Arquitetura Completa de Tesouro para GFP/SIGFIP

**Data:** 2025-01-XX  
**Objetivo:** Implementar arquitetura completa de Tesouro similar à arquitetura de Elaboração e Aprovação do Orçamento

---

## 📋 Entendimento do Problema

### Situação Atual

**Módulo Tesouro Atual (Básico):**
- ✅ `PaymentBatch` - Lotes de pagamento simples
- ✅ `PaymentOrder` - Ordens de pagamento básicas
- ✅ `TreasuryPayment` - Confirmações simples
- ✅ Integração básica com RH e Orçamento

**O que está faltando:**
- ❌ Workflow de aprovação/autorização hierárquica
- ❌ Controles de disponibilidade de caixa
- ❌ Gestão de disponibilidades (caixa, bancos)
- ❌ Conciliação bancária
- ❌ Fluxo de autorização por níveis
- ❌ Rastreamento completo do ciclo de vida
- ❌ Controles de fluxo de caixa
- ❌ Gestão de compromissos de pagamento
- ❌ Programação de pagamentos

---

## 🎯 Arquitetura Completa Proposta

### Comparação: Orçamento vs Tesouro

#### **Orçamento (Implementado pelo Antigravity):**

```
BudgetEntry (Entrada Orçamentária)
├── BudgetEntryType (Tipos: INITIAL_ALLOCATION, SUPPLEMENTARY_CREDIT, etc.)
├── BudgetEntryService (Gestão completa de entradas)
├── BudgetEntryController (API REST)
└── Workflow: Elaboração → Aprovação → Execução
```

**Funcionalidades:**
- ✅ Rastreamento de todas as entradas orçamentárias
- ✅ Tipos de entrada (dotação inicial, créditos, anulações, transferências)
- ✅ Histórico completo de alterações
- ✅ Integração com BudgetAllocation

#### **Tesouro (A Implementar - Arquitetura Completa):**

```
TreasuryEntry (Entrada de Tesouraria) - NOVO
├── TreasuryEntryType (Tipos: PAYMENT_AUTHORIZATION, CASH_AVAILABILITY, etc.)
├── TreasuryEntryService (Gestão completa de entradas)
├── TreasuryEntryController (API REST)
└── Workflow: Solicitação → Autorização → Programação → Execução → Conciliação
```

---

## 🏗️ Componentes da Arquitetura Completa

### 1. **TreasuryEntry** (Similar a BudgetEntry)

**Propósito:** Rastrear todas as entradas e movimentações de tesouraria com histórico completo.

**Campos:**
- `id` (UUID)
- `type` (TreasuryEntryType enum)
- `amount` (BigDecimal)
- `transactionDate` (LocalDate)
- `documentReference` (String) - Ex: "Decreto de Autorização", "Portaria de Pagamento"
- `description` (String)
- `status` (String) - DRAFT, PENDING_APPROVAL, APPROVED, REJECTED, EXECUTED
- `approvalLevel` (Integer) - Nível de aprovação necessário
- `approvedBy` (UUID) - Usuário que aprovou
- `approvedAt` (LocalDateTime)
- `cashAccountId` (UUID) - Conta de caixa/banco afetada
- `paymentOrderId` (UUID) - Referência à ordem de pagamento (se aplicável)
- `budgetLineId` (UUID) - Linha orçamentária relacionada

### 2. **TreasuryEntryType** (Enum)

```java
public enum TreasuryEntryType {
    // Autorizações
    PAYMENT_AUTHORIZATION,        // Autorização de Pagamento
    BATCH_AUTHORIZATION,          // Autorização de Lote
    
    // Disponibilidades
    CASH_AVAILABILITY,            // Disponibilidade de Caixa
    BANK_AVAILABILITY,            // Disponibilidade Bancária
    CASH_DEPOSIT,                 // Depósito em Caixa
    CASH_WITHDRAWAL,              // Saque de Caixa
    
    // Programação
    PAYMENT_SCHEDULING,           // Programação de Pagamento
    BATCH_SCHEDULING,             // Programação de Lote
    
    // Execução
    PAYMENT_EXECUTION,            // Execução de Pagamento
    BATCH_EXECUTION,              // Execução de Lote
    
    // Conciliação
    BANK_RECONCILIATION,          // Conciliação Bancária
    CASH_RECONCILIATION,          // Conciliação de Caixa
    
    // Ajustes
    PAYMENT_CANCELLATION,         // Cancelamento de Pagamento
    PAYMENT_ADJUSTMENT,           // Ajuste de Pagamento
    CASH_ADJUSTMENT               // Ajuste de Caixa
}
```

### 3. **CashAccount** (Nova Entidade)

**Propósito:** Gerenciar contas de caixa e bancárias do Tesouro.

**Campos:**
- `id` (UUID)
- `code` (String, único) - Ex: "CAIXA-001", "BANCO-BCEAO-001"
- `name` (String) - Ex: "Caixa Principal", "Conta BCEAO - Tesouro"
- `type` (String) - CASH, BANK_ACCOUNT
- `bankId` (UUID) - Se tipo = BANK_ACCOUNT
- `accountNumber` (String)
- `branchCode` (String)
- `currency` (String) - XOF
- `isActive` (Boolean)
- `currentBalance` (BigDecimal) - Saldo atual
- `availableBalance` (BigDecimal) - Saldo disponível (após compromissos)

### 4. **PaymentAuthorization** (Nova Entidade)

**Propósito:** Workflow de aprovação hierárquica de pagamentos.

**Campos:**
- `id` (UUID)
- `paymentOrderId` (UUID) ou `paymentBatchId` (UUID)
- `requestedBy` (UUID) - Usuário que solicitou
- `requestedAt` (LocalDateTime)
- `requiredApprovalLevel` (Integer) - Nível necessário (1, 2, 3...)
- `currentApprovalLevel` (Integer) - Nível atual
- `status` (String) - PENDING, PARTIALLY_APPROVED, APPROVED, REJECTED
- `approvals` (List<Approval>) - Histórico de aprovações
- `rejectionReason` (String)

### 5. **Approval** (Embeddable/Value Object)

**Campos:**
- `level` (Integer)
- `approvedBy` (UUID)
- `approvedAt` (LocalDateTime)
- `comments` (String)
- `signature` (String) - Hash da assinatura digital (futuro)

### 6. **CashFlow** (Nova Entidade)

**Propósito:** Rastrear fluxo de caixa (entradas e saídas).

**Campos:**
- `id` (UUID)
- `cashAccountId` (UUID)
- `transactionDate` (LocalDate)
- `type` (String) - INFLOW, OUTFLOW
- `amount` (BigDecimal)
- `description` (String)
- `referenceId` (UUID) - ID da entidade relacionada
- `referenceType` (String) - PAYMENT_ORDER, TREASURY_ENTRY, etc.
- `balanceAfter` (BigDecimal) - Saldo após a transação

### 7. **BankReconciliation** (Nova Entidade)

**Propósito:** Conciliação bancária.

**Campos:**
- `id` (UUID)
- `cashAccountId` (UUID)
- `reconciliationDate` (LocalDate)
- `statementBalance` (BigDecimal) - Saldo do extrato bancário
- `systemBalance` (BigDecimal) - Saldo do sistema
- `difference` (BigDecimal) - Diferença
- `status` (String) - PENDING, RECONCILED, DISCREPANCY
- `reconciledBy` (UUID)
- `reconciledAt` (LocalDateTime)
- `reconciliationItems` (List<ReconciliationItem>)

### 8. **ReconciliationItem** (Embeddable/Value Object)

**Campos:**
- `transactionDate` (LocalDate)
- `description` (String)
- `statementAmount` (BigDecimal)
- `systemAmount` (BigDecimal)
- `matchStatus` (String) - MATCHED, UNMATCHED, PENDING

---

## 🔄 Workflow Completo de Tesouraria

### Fluxo 1: Autorização de Pagamento

```
1. Solicitação de Pagamento
   └─> TreasuryEntry (PAYMENT_AUTHORIZATION, status: DRAFT)
   
2. Submissão para Aprovação
   └─> PaymentAuthorization criado
   └─> status: PENDING
   └─> currentApprovalLevel: 1
   
3. Aprovação Nível 1
   └─> Approval registrado
   └─> currentApprovalLevel: 2 (se necessário)
   
4. Aprovação Nível 2 (se necessário)
   └─> Approval registrado
   └─> status: APPROVED
   
5. Autorização Aprovada
   └─> TreasuryEntry atualizado (status: APPROVED)
   └─> PaymentOrder pode ser criado
```

### Fluxo 2: Programação de Pagamento

```
1. Ordem de Pagamento Criada
   └─> PaymentOrder (status: CREATED)
   
2. Verificação de Disponibilidade
   └─> CashAccount.availableBalance verificado
   └─> Se insuficiente: erro
   
3. Programação
   └─> TreasuryEntry (PAYMENT_SCHEDULING)
   └─> CashAccount.availableBalance reduzido (comprometido)
   └─> PaymentOrder (status: SCHEDULED)
   
4. Agendamento
   └─> PaymentOrder.scheduledDate definido
```

### Fluxo 3: Execução de Pagamento

```
1. Execução do Lote
   └─> PaymentBatch (status: SENT_TO_BANK)
   └─> TreasuryEntry (BATCH_EXECUTION)
   
2. Confirmação Individual
   └─> TreasuryPayment (status: PAID)
   └─> TreasuryEntry (PAYMENT_EXECUTION)
   └─> CashAccount.currentBalance reduzido
   └─> CashFlow registrado (OUTFLOW)
   
3. Atualização Orçamentária
   └─> BudgetExecution (PAYMENT) criado
```

### Fluxo 4: Conciliação Bancária

```
1. Importação de Extrato
   └─> BankReconciliation criado
   └─> ReconciliationItems importados
   
2. Conciliação Automática
   └─> Matching de transações
   └─> Identificação de diferenças
   
3. Conciliação Manual
   └─> Ajustes manuais
   └─> TreasuryEntry (BANK_RECONCILIATION)
   
4. Finalização
   └─> BankReconciliation (status: RECONCILED)
   └─> CashAccount.currentBalance atualizado
```

---

## 📊 Serviços a Implementar

### 1. **TreasuryEntryService**

**Responsabilidades:**
- Criar entradas de tesouraria
- Validar disponibilidade de caixa
- Atualizar saldos de contas
- Rastrear histórico completo
- Integrar com orçamento

**Métodos:**
```java
TreasuryEntryDTO create(CreateTreasuryEntryDTO dto)
Page<TreasuryEntryDTO> findByCashAccount(UUID cashAccountId, Pageable pageable)
Page<TreasuryEntryDTO> findByType(TreasuryEntryType type, Pageable pageable)
BigDecimal calculateAvailableBalance(UUID cashAccountId)
void updateCashAccountBalance(UUID cashAccountId, BigDecimal amount, TreasuryEntryType type)
```

### 2. **PaymentAuthorizationService**

**Responsabilidades:**
- Gerenciar workflow de aprovação
- Validar níveis de aprovação
- Registrar aprovações
- Notificar próximos aprovadores

**Métodos:**
```java
PaymentAuthorizationDTO requestAuthorization(UUID paymentOrderId, Integer requiredLevel)
PaymentAuthorizationDTO approve(UUID authorizationId, UUID approverId, String comments)
PaymentAuthorizationDTO reject(UUID authorizationId, UUID approverId, String reason)
List<PaymentAuthorizationDTO> findPendingApprovals(UUID approverId)
```

### 3. **CashAccountService**

**Responsabilidades:**
- Gerenciar contas de caixa/bancárias
- Calcular saldos disponíveis
- Validar operações
- Histórico de movimentações

**Métodos:**
```java
CashAccountDTO create(CreateCashAccountDTO dto)
CashAccountDTO update(UUID id, UpdateCashAccountDTO dto)
CashAccountDTO findById(UUID id)
BigDecimal getAvailableBalance(UUID cashAccountId)
BigDecimal getCurrentBalance(UUID cashAccountId)
void updateBalance(UUID cashAccountId, BigDecimal amount, String operation)
List<CashAccountDTO> findAll()
```

### 4. **CashFlowService**

**Responsabilidades:**
- Registrar fluxo de caixa
- Calcular projeções
- Relatórios de fluxo
- Análise de tendências

**Métodos:**
```java
CashFlowDTO registerFlow(CreateCashFlowDTO dto)
Page<CashFlowDTO> findByCashAccount(UUID cashAccountId, LocalDate startDate, LocalDate endDate, Pageable pageable)
BigDecimal calculateProjectedBalance(UUID cashAccountId, LocalDate targetDate)
Map<String, BigDecimal> getFlowSummary(UUID cashAccountId, LocalDate startDate, LocalDate endDate)
```

### 5. **BankReconciliationService**

**Responsabilidades:**
- Importar extratos bancários
- Conciliação automática
- Identificar diferenças
- Ajustes e correções

**Métodos:**
```java
BankReconciliationDTO importStatement(UUID cashAccountId, List<StatementItem> items)
BankReconciliationDTO reconcile(UUID reconciliationId)
List<ReconciliationItemDTO> findUnmatchedItems(UUID reconciliationId)
void matchItem(UUID reconciliationId, UUID itemId, UUID systemTransactionId)
BankReconciliationDTO finalize(UUID reconciliationId)
```

### 6. **TreasuryIntegrationService** (Similar a BudgetIntegrationService)

**Responsabilidades:**
- Integração com módulo RH
- Integração com módulo Orçamento
- Validações cruzadas
- Sincronização de dados

**Métodos:**
```java
void validatePaymentOrder(UUID paymentOrderId)
void registerPaymentExecution(UUID paymentOrderId, BigDecimal amount)
void updateBudgetExecution(UUID paymentOrderId)
void validateCashAvailability(UUID cashAccountId, BigDecimal amount)
```

---

## 🗄️ Estrutura de Banco de Dados

### Tabelas Novas

```sql
-- Contas de Caixa/Bancárias
CREATE TABLE cash_account (
    id UUID PRIMARY KEY,
    code VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(200) NOT NULL,
    type VARCHAR(20) NOT NULL, -- CASH, BANK_ACCOUNT
    bank_id UUID,
    account_number VARCHAR(50),
    branch_code VARCHAR(20),
    currency VARCHAR(3) DEFAULT 'XOF',
    is_active BOOLEAN DEFAULT true,
    current_balance NUMERIC(19,2) DEFAULT 0,
    available_balance NUMERIC(19,2) DEFAULT 0,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

-- Entradas de Tesouraria (Similar a BudgetEntry)
CREATE TABLE treasury_entry (
    id UUID PRIMARY KEY,
    type VARCHAR(50) NOT NULL,
    amount NUMERIC(19,2) NOT NULL,
    transaction_date DATE NOT NULL,
    document_reference VARCHAR(100),
    description TEXT,
    status VARCHAR(20) NOT NULL, -- DRAFT, PENDING_APPROVAL, APPROVED, REJECTED, EXECUTED
    approval_level INTEGER,
    approved_by UUID,
    approved_at TIMESTAMP,
    cash_account_id UUID REFERENCES cash_account(id),
    payment_order_id UUID,
    payment_batch_id UUID,
    budget_line_id UUID,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

-- Autorizações de Pagamento
CREATE TABLE payment_authorization (
    id UUID PRIMARY KEY,
    payment_order_id UUID,
    payment_batch_id UUID,
    requested_by UUID NOT NULL,
    requested_at TIMESTAMP NOT NULL,
    required_approval_level INTEGER NOT NULL,
    current_approval_level INTEGER DEFAULT 1,
    status VARCHAR(20) NOT NULL, -- PENDING, PARTIALLY_APPROVED, APPROVED, REJECTED
    rejection_reason TEXT,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

-- Aprovações (Histórico)
CREATE TABLE approval (
    id UUID PRIMARY KEY,
    authorization_id UUID REFERENCES payment_authorization(id) NOT NULL,
    level INTEGER NOT NULL,
    approved_by UUID NOT NULL,
    approved_at TIMESTAMP NOT NULL,
    comments TEXT,
    signature_hash VARCHAR(255)
);

-- Fluxo de Caixa
CREATE TABLE cash_flow (
    id UUID PRIMARY KEY,
    cash_account_id UUID REFERENCES cash_account(id) NOT NULL,
    transaction_date DATE NOT NULL,
    type VARCHAR(20) NOT NULL, -- INFLOW, OUTFLOW
    amount NUMERIC(19,2) NOT NULL,
    description TEXT,
    reference_id UUID,
    reference_type VARCHAR(50),
    balance_after NUMERIC(19,2) NOT NULL,
    created_at TIMESTAMP NOT NULL
);

-- Conciliação Bancária
CREATE TABLE bank_reconciliation (
    id UUID PRIMARY KEY,
    cash_account_id UUID REFERENCES cash_account(id) NOT NULL,
    reconciliation_date DATE NOT NULL,
    statement_balance NUMERIC(19,2) NOT NULL,
    system_balance NUMERIC(19,2) NOT NULL,
    difference NUMERIC(19,2),
    status VARCHAR(20) NOT NULL, -- PENDING, RECONCILED, DISCREPANCY
    reconciled_by UUID,
    reconciled_at TIMESTAMP,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL
);

-- Itens de Conciliação
CREATE TABLE reconciliation_item (
    id UUID PRIMARY KEY,
    reconciliation_id UUID REFERENCES bank_reconciliation(id) NOT NULL,
    transaction_date DATE NOT NULL,
    description TEXT,
    statement_amount NUMERIC(19,2),
    system_amount NUMERIC(19,2),
    match_status VARCHAR(20) NOT NULL, -- MATCHED, UNMATCHED, PENDING
    matched_transaction_id UUID,
    created_at TIMESTAMP NOT NULL
);
```

---

## 🔐 Regras de Negócio

### 1. **Validação de Disponibilidade de Caixa**

```java
// Antes de criar ordem de pagamento
BigDecimal available = cashAccountService.getAvailableBalance(cashAccountId);
if (paymentAmount.compareTo(available) > 0) {
    throw new InsufficientCashException("Saldo disponível insuficiente");
}
```

### 2. **Workflow de Aprovação Hierárquica**

```java
// Valores até 100.000 XOF: 1 nível
// Valores 100.001 - 500.000 XOF: 2 níveis
// Valores acima de 500.000 XOF: 3 níveis
Integer requiredLevel = calculateRequiredLevel(paymentAmount);
```

### 3. **Comprometimento de Caixa**

```java
// Ao programar pagamento
cashAccount.availableBalance -= paymentAmount;
// Ao executar pagamento
cashAccount.currentBalance -= paymentAmount;
```

### 4. **Conciliação Obrigatória**

```java
// Mensalmente, todas as contas bancárias devem ser conciliadas
// Sistema deve alertar se não houver conciliação nos últimos 30 dias
```

---

## 📱 Frontend - Páginas a Criar

### 1. **CashAccountsPage** (`/treasury/cash-accounts`)
- Listar contas de caixa/bancárias
- Criar/editar contas
- Visualizar saldos
- Histórico de movimentações

### 2. **TreasuryEntriesPage** (`/treasury/entries`)
- Listar entradas de tesouraria
- Filtrar por tipo, status, conta
- Visualizar histórico completo
- Criar novas entradas

### 3. **PaymentAuthorizationsPage** (`/treasury/authorizations`)
- Listar autorizações pendentes
- Aprovar/rejeitar pagamentos
- Histórico de aprovações
- Filtros por nível, status

### 4. **CashFlowPage** (`/treasury/cash-flow`)
- Visualizar fluxo de caixa
- Projeções futuras
- Gráficos de entradas/saídas
- Análise de tendências

### 5. **BankReconciliationPage** (`/treasury/reconciliation`)
- Importar extratos
- Conciliação automática
- Ajustes manuais
- Relatórios de conciliação

### 6. **TreasuryDashboardPage** (`/treasury/dashboard`)
- Saldos de todas as contas
- Pagamentos pendentes de aprovação
- Conciliações pendentes
- Alertas e notificações

---

## ✅ Checklist de Implementação

### Fase 1: Entidades e Repositories
- [ ] Criar `CashAccount` entity
- [ ] Criar `TreasuryEntry` entity
- [ ] Criar `PaymentAuthorization` entity
- [ ] Criar `Approval` embeddable
- [ ] Criar `CashFlow` entity
- [ ] Criar `BankReconciliation` entity
- [ ] Criar `ReconciliationItem` entity
- [ ] Criar todos os repositories

### Fase 2: Services
- [ ] Implementar `TreasuryEntryService`
- [ ] Implementar `PaymentAuthorizationService`
- [ ] Implementar `CashAccountService`
- [ ] Implementar `CashFlowService`
- [ ] Implementar `BankReconciliationService`
- [ ] Implementar `TreasuryIntegrationService`

### Fase 3: Controllers e DTOs
- [ ] Criar DTOs para todas as entidades
- [ ] Implementar `TreasuryEntryController`
- [ ] Implementar `PaymentAuthorizationController`
- [ ] Implementar `CashAccountController`
- [ ] Implementar `CashFlowController`
- [ ] Implementar `BankReconciliationController`

### Fase 4: Frontend
- [ ] Criar `CashAccountsPage`
- [ ] Criar `TreasuryEntriesPage`
- [ ] Criar `PaymentAuthorizationsPage`
- [ ] Criar `CashFlowPage`
- [ ] Criar `BankReconciliationPage`
- [ ] Criar `TreasuryDashboardPage`
- [ ] Atualizar navegação

### Fase 5: Integração
- [ ] Integrar com módulo RH
- [ ] Integrar com módulo Orçamento
- [ ] Atualizar `PaymentOrderService` para usar nova arquitetura
- [ ] Atualizar `PaymentBatchService` para usar nova arquitetura
- [ ] Testes de integração

---

## 🎯 Resultado Esperado

Após a implementação, o módulo Tesouro terá:

✅ **Arquitetura completa** similar ao módulo Orçamento  
✅ **Workflow de aprovação** hierárquica  
✅ **Controles de caixa** rigorosos  
✅ **Conciliação bancária** automatizada  
✅ **Rastreamento completo** do ciclo de vida  
✅ **Integração robusta** com outros módulos  
✅ **Conformidade** com padrões GFP/SIGFIP  

---

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