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:**
```java
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)