sigrhapf/Documents/sigfip/sigefp/PLANO_MESTRE_INTEGRADO.md

🚀 PLANO MESTRE INTEGRADO DE IMPLEMENTAÇÃO: SIGEFP

Versão: 2.0 (Integrado - Auto + Antigravity)
Data: Dezembro 2024
Objetivo: Transitar de um protótipo funcional (~90%) para um Sistema de Estado de alta disponibilidade, corrigindo riscos críticos e completando todas as funcionalidades pendentes.

---

📊 STATUS ATUAL (Baseado em Ambas as Análises)

Backend: ~90-95% Completo

• ✅ Estrutura completa (100%)
• ✅ Integrações funcionais (100%)
• ⚠️ Testes (0% - CRÍTICO)
• ⚠️ Riscos técnicos identificados

Frontend: ~70-75% Completo

• ✅ Módulos ADMIN, ORG, RH, COMMON (100%)
• ❌ Módulos BUDGET, TREASURY (0%)
• ⚠️ Dashboard com dados mockados

---

🏗️ FASE 1: HARDENING E SEGURANÇA (PRIORIDADE CRÍTICA)

Duração Estimada: 2-3 semanas
Objetivo: Eliminar riscos de integridade de dados e preparar o sistema para escala nacional.

1.1 Refatoração de Identificadores (UUID Bridge) 🔴 CRÍTICO

Problema Identificado por Antigravity:

• PaymentOrderService usa .hashCode() para referências Long entre módulos
• Risco de colisão em volumes massivos de dados

Ações:

• Análise do código atual
  • Localizar todas as ocorrências de .hashCode() para conversão UUID → Long
  • Identificar impactos em outros módulos
• Implementar estratégia de ID sequencial real
  • Criar tabela de mapeamento UUID ↔ Long (se necessário)
  • OU migrar referências cruzadas para UUID nativo no banco de dados
• Arquivos Alvo:
  • sigefp-treasury/src/main/java/br/gov/sigefp/treasury/service/PaymentOrderService.java
  • sigefp-budget/src/main/java/br/gov/sigefp/budget/integration/BudgetIntegrationService.java
  • Verificar outros serviços que usam conversão de IDs

Critérios de Sucesso:

• ✅ Zero uso de .hashCode() para conversão de IDs
• ✅ Testes de integridade de dados passando
• ✅ Documentação da estratégia de IDs

---

1.2 Iniciação da Suíte de Testes (0% → 40%) 🔴 CRÍTICO

Foco: Motores de Cálculo e Integração Orçamentária

Testes Unitários (Prioridade ALTA)

1. PayrollServiceTest

• Validar cálculos de INPS
• Validar cálculos de IRPS (escalonados 10-25%)
• Validar cálculos de Selo
• Validar geração de itens de folha
• Validar processamento em lote

2. BudgetExecutionServiceTest

• Testar bloqueio de saldo insuficiente
• Validar criação de COMMITMENT
• Validar criação de LIQUIDATION
• Validar criação de PAYMENT
• Validar cálculos de saldo disponível

3. AgentServiceTest

• Validar validações do Decreto 12-A/94
• Validar regra de 3 anos de avaliações "Bom" para promoção
• Validar criação de eventos de carreira
• Validar estatísticas de agentes

4. TaxServiceTest

• Validar escalões de IRPS
• Validar regras globais de desconto
• Validar escalões ativos por data

Testes de Integração (Prioridade ALTA)

5. Fluxo RH → Budget → Treasury

• Testar: Criação de folha → Compromisso orçamentário
• Testar: Pagamento → Execução orçamentária
• Testar: Integridade de dados entre módulos
• Testar: Validações cruzadas

6. BudgetIntegrationServiceTest

• createCommitmentFromPayrollItem() - Integração RH → Budget
• createPaymentFromTreasury() - Integração Treasury → Budget
• Conversão de períodos (fiscalYear + month → periodId)

Estrutura de Testes:

sigefp-rh/src/test/java/br/gov/sigefp/rh/service/
├── PayrollServiceTest.java
├── AgentServiceTest.java
└── TaxServiceTest.java

sigefp-budget/src/test/java/br/gov/sigefp/budget/service/
├── BudgetExecutionServiceTest.java
└── integration/
    └── BudgetIntegrationServiceTest.java

sigefp-treasury/src/test/java/br/gov/sigefp/treasury/service/
└── PaymentOrderServiceTest.java

Critérios de Sucesso:

• ✅ Cobertura de testes: 40% mínimo
• ✅ Todos os testes de integração passando
• ✅ CI/CD configurado para executar testes

---

1.3 Padronização de Exceções e Respostas de Erro

Ação: Expandir o GlobalExceptionHandler com códigos de erro específicos

Exceções Customizadas a Criar:

• InsufficientBudgetException - Saldo orçamentário insuficiente
• AgentInactiveException - Agente inativo
• PeriodClosedException - Período fechado
• InvalidPromotionException - Promoção inválida (Decreto 12-A/94)
• DuplicateEntityException - Entidade duplicada
• BusinessRuleException - Regra de negócio violada

Estrutura de ErrorCode:

public enum ErrorCode {
    INSUFFICIENT_BUDGET("BUDGET_001", "Saldo orçamentário insuficiente"),
    AGENT_INACTIVE("RH_001", "Agente inativo"),
    PERIOD_CLOSED("RH_002", "Período de folha fechado"),
    INVALID_PROMOTION("RH_003", "Promoção inválida: requer 3 anos de avaliações 'Bom'"),
    // ...
}

Critérios de Sucesso:

• ✅ Todas as exceções customizadas implementadas
• ✅ Códigos de erro padronizados
• ✅ Logging estruturado de exceções
• ✅ Documentação de códigos de erro

---

💻 FASE 2: COMPLETUDE DO FRONTEND (MÓDULOS PLACEHOLDER)

Duração Estimada: 3-4 semanas
Objetivo: Transformar rotas vazias em interfaces funcionais baseadas na lógica já existente no backend.

2.1 Módulo de Orçamento (Budget UI) ❌ 0% → 100%

Páginas a Implementar

1. FiscalYearsPage (/budget/fiscal-years)

• Listagem de anos fiscais (com status: DRAFT, OPEN, CLOSED)
• Criar novo exercício fiscal
• Abrir exercício (com validações)
• Fechar exercício (com validações)
• Visualizar exercício corrente
• Filtros por status e ano

Componentes:

• FiscalYearFormModal - Formulário de criação
• FiscalYearStatusBadge - Badge de status
• FiscalYearActions - Botões de ação (abrir/fechar)

Hooks:

• useFiscalYears - Hook para gestão de anos fiscais

Serviços:

• budgetService.ts - Serviço de orçamento

Endpoints Backend (já existem):

• GET /api/budget/fiscal-years
• GET /api/budget/fiscal-years/current
• POST /api/budget/fiscal-years
• POST /api/budget/fiscal-years/{id}/open
• POST /api/budget/fiscal-years/{id}/close

---

2. BudgetLinesPage (/budget/lines)

• Listagem de linhas orçamentárias (com paginação)
• Visualização de saldos (alocado, comprometido, liquidado, disponível)
• Criar nova linha orçamentária
• Editar linha orçamentária
• Filtros por exercício fiscal, ministério, unidade orgânica
• Visualização de execuções por linha

Componentes:

• BudgetLineFormModal - Formulário de criação/edição
• BudgetLineCard - Card com saldos
• BudgetExecutionChart - Gráfico de execução
• AdvancedFilters - Filtros avançados

Hooks:

• useBudgetLines - Hook para gestão de linhas
• useBudgetExecution - Hook para execuções

Endpoints Backend (já existem):

• GET /api/budget/lines
• GET /api/budget/lines/{id}
• POST /api/budget/lines
• PUT /api/budget/lines/{id}

---

3. BudgetExecutionPage (/budget/execution)

• Listagem de execuções orçamentárias
• Filtros por linha, período, tipo de movimento
• Visualização de movimentos (COMMITMENT, LIQUIDATION, PAYMENT)
• Gráficos de execução por período
• Exportação de relatórios

Componentes:

• ExecutionTable - Tabela de execuções
• ExecutionFilters - Filtros
• ExecutionChart - Gráficos de execução
• ExportButton - Exportação

Hooks:

• useBudgetExecution - Hook para execuções

Endpoints Backend (já existem):

• GET /api/budget/execution
• POST /api/budget/execution

---

2.2 Módulo de Tesouraria (Treasury UI) ❌ 0% → 100%

Páginas a Implementar

1. PaymentBatchesPage (/treasury/batches)

• Listagem de lotes de pagamento
• Criar novo lote
• Alterar status do lote
• Visualizar ordens do lote
• Filtros por período, ministério, status
• Integração com Banco Central (preparado)

Componentes:

• PaymentBatchFormModal - Formulário de criação
• PaymentBatchStatusBadge - Badge de status
• PaymentBatchActions - Ações do lote

Hooks:

• usePaymentBatches - Hook para lotes

Endpoints Backend (já existem):

• GET /api/treasury/payment-batches
• GET /api/treasury/payment-batches/{id}
• POST /api/treasury/payment-batches
• POST /api/treasury/payment-batches/{id}/status

---

2. PaymentOrdersPage (/treasury/orders)

• Listagem de ordens de pagamento
• Visualizar detalhes da ordem
• Alterar status da ordem
• Filtros por lote, status, agente
• Visualização de pagamentos confirmados

Componentes:

• PaymentOrderCard - Card da ordem
• PaymentOrderDetails - Detalhes
• PaymentOrderStatusBadge - Badge de status

Hooks:

• usePaymentOrders - Hook para ordens

Endpoints Backend (já existem):

• GET /api/treasury/payment-orders
• GET /api/treasury/payment-orders/{id}
• POST /api/treasury/payment-orders
• POST /api/treasury/payment-orders/{id}/status

---

3. TreasuryPaymentsPage (/treasury/confirmations)

• Listagem de pagamentos confirmados
• Registrar confirmação de pagamento
• Visualizar histórico de pagamentos
• Filtros por ordem, status, data

Componentes:

• TreasuryPaymentFormModal - Formulário de confirmação
• PaymentHistoryTable - Histórico

Hooks:

• useTreasuryPayments - Hook para pagamentos

Endpoints Backend (já existem):

• GET /api/treasury/payments
• POST /api/treasury/payments

---

2.3 Dashboard Real-Time ⚠️ 50% → 100%

Ação: Substituir gráficos mockados por chamadas reais aos endpoints

Implementações:

• Integrar /api/rh/agents/stats para estatísticas de agentes
• Criar endpoint /api/budget/execution/stats para estatísticas orçamentárias
• Criar endpoint /api/treasury/payments/stats para estatísticas de pagamentos
• Implementar gráficos reais (Chart.js ou Recharts)
• Atualização em tempo real (polling ou WebSocket)
• Filtros por período no dashboard

Componentes:

• DashboardStats - Cards de estatísticas
• DashboardCharts - Gráficos
• DashboardFilters - Filtros de período

Critérios de Sucesso:

• ✅ Zero dados mockados no dashboard
• ✅ Gráficos funcionais com dados reais
• ✅ Atualização automática de métricas

---

⚖️ FASE 3: LÓGICA DE NEGÓCIO E CONFORMIDADE LEGAL

Duração Estimada: 2-3 semanas
Objetivo: Assegurar que o sistema execute as regras do Decreto 12-A/94 de forma automática.

3.1 Automação de Progressão/Promoção

Problema: Lógica de fechamento de ciclo de avaliação ainda é manual

Ações:

• Criar PerformanceEvaluationService
  • Registrar avaliações de desempenho
  • Calcular pontuação acumulada
  • Validar requisitos para promoção (3 anos de "Bom")
• Integrar com CareerEventService
  • Ao atingir pontuação necessária, sugerir promoção
  • Criar evento de carreira automaticamente
  • Atualizar salário baseado na nova posição
• Interface Frontend
  • Página de avaliações de desempenho
  • Dashboard de progressão de carreira
  • Alertas de promoções disponíveis

Arquivos a Criar:

• sigefp-rh/src/main/java/br/gov/sigefp/rh/service/PerformanceEvaluationService.java
• sigefp-rh/src/main/java/br/gov/sigefp/rh/domain/PerformanceEvaluation.java
• sigefp-rh/src/main/java/br/gov/sigefp/rh/api/PerformanceEvaluationController.java
• sigefp-frontend/src/modules/rh/pages/PerformanceEvaluationsPage.tsx

Critérios de Sucesso:

• ✅ Sistema sugere promoções automaticamente
• ✅ Validações do Decreto 12-A/94 implementadas
• ✅ Interface para gestão de avaliações

---

3.2 Fechamento de Ciclo de Folha

Ação: Implementar no Frontend a funcionalidade de "Encerrar Período"

Implementações:

• Backend: Endpoint de Encerramento
  • POST /api/rh/payroll-runs/{id}/close
  • Validar que todos os itens foram processados
  • Disparar liquidação orçamentária definitiva
  • Atualizar status do período
• Frontend: Interface de Encerramento
  • Botão "Encerrar Período" na PayrollRunsPage
  • Modal de confirmação com resumo
  • Visualização de status do encerramento
  • Histórico de períodos encerrados

Fluxo:

1. Processar folha (/payroll-runs/{id}/process)
2. Gerar itens (/payroll-runs/{id}/generate)
3. Validar itens
4. Encerrar período (/payroll-runs/{id}/close)
5. Criar execuções orçamentárias (LIQUIDATION)

Critérios de Sucesso:

• ✅ Encerramento de período funcional
• ✅ Liquidação orçamentária automática
• ✅ Validações de integridade

---

📊 FASE 4: MELHORIAS E OTIMIZAÇÕES (PRIORIDADE MÉDIA)

Duração Estimada: 2-3 semanas

4.1 Performance e Otimização

• Implementar cache (Spring Cache) para dados mestres
• Otimizar queries N+1
• Adicionar índices adicionais no banco
• Implementar paginação em todas as listagens
• Batch processing para operações em massa

4.2 Relatórios e Exportação

• Endpoints de relatórios consolidados
• Exportação para Excel/PDF
• Relatórios de execução orçamentária
• Relatórios de folha de pagamento
• Relatórios de pagamentos

4.3 Documentação

• Documentação Swagger completa
• Guias de uso
• Documentação de API
• Vídeos tutoriais

---

📊 MÉTRICAS DE SUCESSO DO PLANO

KPI	Atual	Meta Fase 1	Meta Fase 2	Meta Fase 3	Meta Final
Cobertura de Testes	0%	40%	50%	60%	70%
Interfaces Financeiras	Placeholder	-	100%	100%	100%
Risco de Colisão IDs	Alto	Zero	Zero	Zero	Zero
Dashboard	Mockado	-	Real-Time	Real-Time	Real-Time
Conformidade Legal	Manual	-	-	Automático	Automático
Frontend Completo	75%	75%	100%	100%	100%
Backend Completo	90%	95%	95%	98%	98%

---

🎯 CRONOGRAMA SUGERIDO

Semana 1-2: Fase 1.1 e 1.2 (Hardening)

• Refatoração de IDs
• Início dos testes

Semana 3-4: Fase 1.3 e 2.1 (Exceções + Budget UI)

• Padronização de exceções
• Implementação do módulo Budget

Semana 5-6: Fase 2.2 e 2.3 (Treasury UI + Dashboard)

• Implementação do módulo Treasury
• Dashboard real-time

Semana 7-8: Fase 3 (Conformidade Legal)

• Automação de promoções
• Fechamento de ciclo de folha

Semana 9-10: Fase 4 (Melhorias)

• Performance
• Relatórios
• Documentação

Total Estimado: 10 semanas (2.5 meses)

---

✅ CHECKLIST DE VALIDAÇÃO

Antes de considerar cada fase completa, validar:

Fase 1 (Hardening)

• Zero uso de .hashCode() para IDs
• Cobertura de testes ≥ 40%
• Todas as exceções customizadas implementadas
• Testes de integração passando

Fase 2 (Frontend)

• Todas as páginas Budget implementadas
• Todas as páginas Treasury implementadas
• Dashboard com dados reais
• Testes E2E básicos

Fase 3 (Conformidade)

• Sistema sugere promoções automaticamente
• Encerramento de período funcional
• Validações do Decreto 12-A/94 implementadas

Fase 4 (Melhorias)

• Cache implementado
• Relatórios funcionais
• Documentação completa

---

📝 NOTAS IMPORTANTES

1. Validação de Auditoria: Sempre validar a trilha de auditoria em STATUS_PROJETO.md para garantir que nenhuma regra do Decreto 12-A/94 seja violada.

2. Priorização: Fase 1 é CRÍTICA e deve ser feita antes de qualquer deploy em produção.

3. Testes: Não avançar para Fase 2 sem completar pelo menos 40% de cobertura de testes.

4. Integrações: Testar todas as integrações entre módulos após cada fase.

5. Documentação: Documentar todas as decisões técnicas e mudanças.

---

Última atualização: Dezembro 2024
Versão: 2.0 (Integrado)
Baseado em: PLANO_MESTRE_IMPLEMENTACAO.md (Antigravity) + ANALISE_COMPLETA_PROJETO.md (Auto)