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

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

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

<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

{
  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

{
  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

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