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)

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) - 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)

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:

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:

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:

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:

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:

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:

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

-- 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

// 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

// 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

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

4. Conciliação Obrigatória

// 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