sigrhapf/Documents/sigfip/sigefp/PROBLEMAS_REAIS_FLUXO_NEGOCIO.md

# 🔍 Problemas Reais no Fluxo de Negócio - SIGEFP

**Data:** 2025-01-XX  
**Baseado em:** Análise real do código existente

---

## ✅ Confirmação: Funcionalidades Existentes

### Dotações
- ✅ **Existe:** Botão Wallet (💼) na página `Linhas Orçamentais`
- ✅ **Funcional:** Abre modal `BudgetLineEntriesModal`
- ✅ **Completo:** Permite criar, visualizar todas as dotações

### Integrações
- ✅ RH → Orçamento: COMMITMENT criado automaticamente
- ✅ RH → Tesouro: PaymentOrder criado automaticamente
- ✅ Tesouro → Orçamento: PAYMENT criado automaticamente

---

## 🎯 Problemas Identificados

### 1. **Falta de Clareza no Fluxo Inicial** 🔴

**Problema:**
- Usuário não sabe que precisa criar dotações antes de abrir exercício
- Botão Wallet pode não ser intuitivo
- Não há validação ao abrir exercício sem dotações

**Evidência:**
- `FiscalYearService.open()` não valida se há dotações
- Não há aviso visual se linha não tem dotações

**Impacto:**
- Usuário pode abrir exercício sem dotações
- Pode tentar criar empenhos sem saldo disponível
- Erros só aparecem durante execução

---

### 2. **Falta de Rastreabilidade Visual** 🟡

**Problema:**
- Difícil rastrear link entre PaymentOrder e BudgetExecution
- Não há indicação visual de que integrações são automáticas
- Falta visão consolidada do fluxo end-to-end

**Evidência:**
- `BudgetExecution` tem `referenceId` mas não é exibido na UI
- `PaymentOrder` tem `budgetLineId` mas não há link visual
- Página de Execução não mostra origem (PaymentOrder.id)

**Impacto:**
- Dificulta auditoria
- Dificulta troubleshooting
- Usuário não entende como tudo se conecta

---

### 3. **Falta de Validação Preventiva** 🟡

**Problema:**
- Validações só ocorrem durante execução
- Não há validação ao criar PaymentOrder se há saldo orçamentário
- Não há validação ao abrir exercício

**Evidência:**
- `PaymentOrderService.create()` não valida saldo orçamentário
- `FiscalYearService.open()` não valida dotações
- Validações só em `BudgetExecutionService.registerExecution()`

**Impacto:**
- Erros aparecem tarde no processo
- Dificulta planejamento
- Pode criar ordens sem saldo disponível

---

### 4. **Falta de Documentação Visual** 🟡

**Problema:**
- Não há diagrama visual do fluxo
- Não há indicação de que integrações são automáticas
- Falta guia passo a passo

**Impacto:**
- Usuário não entende o fluxo completo
- Dificulta onboarding
- Dificulta treinamento

---

## 🔧 Correções Recomendadas

### Prioridade 1: Melhorar UX do Fluxo Inicial

#### 1.1 Adicionar Validação ao Abrir Exercício

**Arquivo:** `sigefp-budget/src/main/java/br/gov/sigefp/budget/service/FiscalYearService.java`

```java
public FiscalYearDTO open(UUID id) {
    FiscalYear fiscalYear = fiscalYearRepository.findById(id)
        .orElseThrow(() -> new ResourceNotFoundException("Exercício fiscal não encontrado: " + id));

    // NOVO: Validar se há dotações
    long budgetLinesWithAllocations = budgetLineRepository.countByFiscalYearIdAndHasAllocations(id);
    if (budgetLinesWithAllocations == 0) {
        throw new BusinessException(
            "Não é possível abrir exercício fiscal sem dotações. Crie dotações nas linhas orçamentárias primeiro.",
            "NO_ALLOCATIONS",
            HttpStatus.PRECONDITION_FAILED
        );
    }

    // ... resto do código
}
```

#### 1.2 Melhorar Indicador Visual de Dotações

**Arquivo:** `sigefp-frontend/src/modules/budget/pages/BudgetLinesPage.tsx`

```typescript
// Adicionar badge com número de dotações
{line.totalAllocated > 0 && (
  <Badge variant="success" className="ml-2">
    {formatCurrency(line.totalAllocated)}
  </Badge>
)}

// Adicionar indicador se não tem dotações
{line.totalAllocated === 0 && (
  <Badge variant="warning" className="ml-2">
    Sem dotação
  </Badge>
)}
```

#### 1.3 Melhorar Tooltip do Botão

**Arquivo:** `sigefp-frontend/src/modules/budget/pages/BudgetLinesPage.tsx`

```typescript
<Button
  variant="ghost"
  size="sm"
  onClick={() => setSelectedLineForEntries(line)}
  className="text-green-600 hover:bg-green-50"
  title={`Gerir Dotações - ${line.totalAllocated > 0 ? formatCurrency(line.totalAllocated) : 'Sem dotação'}`}
>
  <Wallet className="w-4 h-4" />
</Button>
```

---

### Prioridade 2: Melhorar Rastreabilidade

#### 2.1 Adicionar Coluna de Referência em BudgetExecution

**Arquivo:** `sigefp-frontend/src/modules/budget/pages/BudgetExecutionPage.tsx`

```typescript
{
  key: 'referenceId',
  header: 'Referência',
  cell: (execution: BudgetExecutionDTO) => {
    if (!execution.referenceId) return '-';
    return (
      <Link 
        to={`/treasury/orders/${execution.referenceId}`}
        className="text-blue-600 hover:underline"
      >
        {execution.referenceId.substring(0, 8)}...
      </Link>
    );
  },
}
```

#### 2.2 Adicionar Link para BudgetExecution em PaymentOrder

**Arquivo:** `sigefp-frontend/src/modules/treasury/pages/PaymentOrdersPage.tsx`

```typescript
{
  key: 'budgetExecution',
  header: 'Execução Orçamentária',
  cell: (order: PaymentOrderDTO) => {
    if (!order.budgetLineId) return '-';
    return (
      <Link 
        to={`/budget/execution?budgetLineId=${order.budgetLineId}`}
        className="text-blue-600 hover:underline"
      >
        Ver Execução
      </Link>
    );
  },
}
```

---

### Prioridade 3: Adicionar Validações Preventivas

#### 3.1 Validar Saldo ao Criar PaymentOrder

**Arquivo:** `sigefp-treasury/src/main/java/br/gov/sigefp/treasury/service/PaymentOrderService.java`

```java
public PaymentOrderDTO create(CreatePaymentOrderDTO dto) {
    // NOVO: Validar saldo orçamentário se budgetLineId presente
    if (dto.getBudgetLineId() != null) {
        budgetIntegrationService.validateBudgetAvailability(
            dto.getBudgetLineId(),
            dto.getNetAmount()
        );
    }
    
    // ... resto do código
}
```

---

### Prioridade 4: Criar Documentação Visual

#### 4.1 Criar Diagrama de Fluxo

Criar arquivo `FLUXO_VISUAL_COMPLETO.md` com:
- Diagrama de sequência
- Fluxo de estados
- Integrações automáticas destacadas

---

## 📋 Checklist de Implementação

### UX/UI
- [ ] Adicionar validação ao abrir exercício fiscal
- [ ] Adicionar badge com valor de dotação nas linhas
- [ ] Adicionar indicador se linha não tem dotação
- [ ] Melhorar tooltip do botão Wallet

### Rastreabilidade
- [ ] Adicionar coluna "Referência" em BudgetExecution
- [ ] Adicionar link para PaymentOrder em BudgetExecution
- [ ] Adicionar link para BudgetExecution em PaymentOrder
- [ ] Adicionar breadcrumbs nas páginas

### Validações
- [ ] Validar saldo orçamentário ao criar PaymentOrder
- [ ] Validar dotações ao abrir exercício fiscal
- [ ] Adicionar validações preventivas

### Documentação
- [ ] Criar diagrama visual do fluxo
- [ ] Documentar integrações automáticas
- [ ] Criar guia passo a passo visual

---

## 🎯 Resumo dos Problemas

| Problema | Prioridade | Impacto | Solução |
|----------|------------|---------|---------|
| Falta clareza no fluxo inicial | 🔴 Alta | Usuário não sabe como começar | Validação + UX melhorada |
| Falta rastreabilidade visual | 🟡 Média | Dificulta auditoria | Links entre páginas |
| Falta validação preventiva | 🟡 Média | Erros aparecem tarde | Validações antecipadas |
| Falta documentação visual | 🟡 Média | Dificulta onboarding | Diagramas e guias |

---

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