Files
sgse-app/SISTEMA_FERIAS_MODERNO_COMPLETO.md

637 lines
18 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🎉 SISTEMA MODERNO DE GESTÃO DE FÉRIAS - IMPLEMENTAÇÃO COMPLETA
**Data de Conclusão:** 30 de outubro de 2025
**Versão:** 2.0.0 - Sistema Premium Multi-Regime
**Status:****100% IMPLEMENTADO E FUNCIONAL**
---
## 📋 ÍNDICE
1. [Visão Geral](#visão-geral)
2. [Arquitetura do Sistema](#arquitetura-do-sistema)
3. [Funcionalidades Implementadas](#funcionalidades-implementadas)
4. [Componentes Frontend](#componentes-frontend)
5. [Backend e API](#backend-e-api)
6. [Regras de Negócio](#regras-de-negócio)
7. [Fluxo do Usuário](#fluxo-do-usuário)
8. [Guia de Uso](#guia-de-uso)
9. [Tecnologias Utilizadas](#tecnologias-utilizadas)
10. [Testes e Validação](#testes-e-validação)
---
## 🎯 VISÃO GERAL
O **Sistema de Gestão de Férias** do SGSE é uma solução moderna, intuitiva e robusta para gerenciamento completo de férias de funcionários, com suporte a **múltiplos regimes de trabalho** (CLT e Servidor Público Estadual de PE).
### ⭐ Diferenciais
-**Multi-Regime**: Suporta CLT e Servidor Público PE com regras específicas
-**Wizard Intuitivo**: Processo de solicitação em 3 passos guiados
-**Calendário Interativo**: FullCalendar para seleção visual de períodos
-**Validação em Tempo Real**: Feedback instantâneo sobre regras CLT/Servidor PE
-**Dashboard Analytics**: Gráficos e estatísticas em tempo real
-**Toast Notifications**: Feedback visual moderno com Sonner
-**Cálculo Automático de Saldo**: Sistema inteligente de períodos aquisitivos
-**Gestão por Times**: Estrutura de times e gestores para aprovações
-**Responsivo**: 100% adaptado para mobile, tablet e desktop
---
## 🏗️ ARQUITETURA DO SISTEMA
```
┌─────────────────────────────────────────────────────────────┐
│ FRONTEND (SvelteKit) │
├─────────────────────────────────────────────────────────────┤
│ /perfil > Aba "Minhas Férias" │
│ ├── DashboardFerias.svelte (Analytics + Gráficos) │
│ └── WizardSolicitacaoFerias.svelte (Processo 3 Passos) │
│ └── CalendarioFerias.svelte (FullCalendar) │
├─────────────────────────────────────────────────────────────┤
│ BACKEND (Convex) │
├─────────────────────────────────────────────────────────────┤
│ Schemas: │
│ ├── funcionarios (+ regimeTrabalho) │
│ ├── periodosAquisitivos (novo!) │
│ ├── solicitacoesFerias │
│ └── notificacoesFerias │
│ │
│ Modules: │
│ ├── saldoFerias.ts (Cálculos + Validações) │
│ ├── ferias.ts (CRUD + Aprovações) │
│ ├── times.ts (Gestão de Times) │
│ └── crons.ts (Automações) │
└─────────────────────────────────────────────────────────────┘
```
---
## ✨ FUNCIONALIDADES IMPLEMENTADAS
### 🔹 **FASE 1: Backend & Regras de Negócio**
#### ✅ Schema de Períodos Aquisitivos
- **Tabela:** `periodosAquisitivos`
- **Campos:**
- `anoReferencia`: Ano do período (ex: 2025)
- `diasDireito`: Dias totais (30)
- `diasUsados`: Dias já gozados
- `diasPendentes`: Dias em solicitações aguardando
- `diasDisponiveis`: Saldo disponível
- `abonoPermitido`: Permite venda de férias (só CLT)
- `status`: `ativo`, `vencido`, `concluido`
#### ✅ Cálculo Automático de Saldo
- **Query:** `saldoFerias.obterSaldo`
- Cria automaticamente períodos aquisitivos se não existirem
- Calcula saldo baseado no regime de trabalho
- Retorna informações completas do período
#### ✅ Validação CLT vs Servidor PE
- **Query:** `saldoFerias.validarSolicitacao`
- **CLT:** Máx 3 períodos, mín 5 dias, 1 período com 14+ dias
- **Servidor PE:** Máx 2 períodos, mín 10 dias cada
- Valida sobreposição de datas
- Valida saldo disponível
- Retorna erros e avisos contextuais
#### ✅ Reserva e Liberação de Dias
- **Mutation:** `saldoFerias.reservarDias`
- Reserva dias ao criar solicitação (impede uso duplo)
- **Mutation:** `saldoFerias.liberarDias`
- Libera dias ao reprovar solicitação
- **Mutation:** `saldoFerias.atualizarSaldoAposAprovacao`
- Marca dias como usados após aprovação
#### ✅ Cron Jobs Automáticos
- **Diário:** Criar períodos aquisitivos para novos funcionários
- **Diário:** Atualizar status de férias (ativo/em_ferias)
---
### 🔹 **FASE 2: Frontend Premium**
#### ✅ Wizard de Solicitação (3 Passos)
**Componente:** `WizardSolicitacaoFerias.svelte`
**Passo 1 - Ano & Saldo:**
- Seletor visual de ano (cards)
- Card premium com estatísticas do saldo:
- Total Direito
- Disponível
- Usado
- Pendente
- Informações do regime de trabalho
- Alertas de saldo zerado
**Passo 2 - Seleção de Períodos:**
- Calendário interativo (FullCalendar)
- Drag & drop para selecionar períodos
- Click para remover períodos
- Validação em tempo real:
- Erros visuais (vermelho)
- Avisos contextuais (amarelo)
- Sucesso (verde)
- Progress bar de saldo:
- Disponível / Selecionado / Restante
**Passo 3 - Confirmação:**
- Resumo visual da solicitação
- Lista de períodos com datas formatadas
- Campo de observação opcional
- Botões de ação premium
**Animações:**
- FadeIn entre passos
- Hover effects
- Loading states
- Toast notifications
---
#### ✅ Calendário Interativo
**Componente:** `CalendarioFerias.svelte`
**Features:**
- **FullCalendar Integration:**
- View mensal e anual (multiMonth)
- Localização PT-BR
- Seleção por drag
- Eventos coloridos por período
- **Validações Visuais:**
- Destaque de fins de semana
- Bloqueio de datas passadas
- Cores distintas por período (roxo, rosa, azul)
- Tooltip em eventos
- **Customização:**
- Toolbar moderna com gradiente
- Eventos com sombra e hover
- Grid limpo e profissional
- 100% responsivo
**Eventos:**
- `onPeriodoAdicionado`: Callback ao adicionar período
- `onPeriodoRemovido`: Callback ao remover período
---
#### ✅ Dashboard de Analytics
**Componente:** `DashboardFerias.svelte`
**Cards de Estatísticas (4):**
1. **Disponível** (Verde): Dias disponíveis
2. **Usado** (Vermelho): Dias já gozados
3. **Pendente** (Amarelo): Dias aguardando aprovação
4. **Total Direito** (Roxo): Dias totais do ano
**Gráficos de Pizza (2):**
1. **Distribuição de Saldo:**
- Disponível (verde)
- Pendente (laranja)
- Usado (vermelho)
2. **Status de Solicitações:**
- Aprovadas (verde)
- Pendentes (laranja)
- Reprovadas (vermelho)
**Tabela de Histórico:**
- Todos os saldos por ano
- Status visual (ativo/vencido/concluído)
- Breakdown de dias
**Tecnologias:**
- Canvas API para gráficos (sem bibliotecas pesadas!)
- Design glassmorphism
- Animações suaves
- Hover effects premium
---
#### ✅ Toast Notifications
**Biblioteca:** Svelte-Sonner
**Tipos:**
- `toast.success()`: Ações bem-sucedidas
- `toast.error()`: Erros e validações
- `toast.info()`: Informações gerais
- `toast.warning()`: Avisos importantes
**Exemplos:**
```typescript
toast.success("Período de 14 dias adicionado! ✅");
toast.error("Máximo de 3 períodos atingido");
toast.warning("Seu saldo está baixo!");
```
**Configuração:**
- Posição: top-right
- Rich colors: ativado
- Close button: sim
- Expand: sim
---
## 📊 REGRAS DE NEGÓCIO
### CLT (Consolidação das Leis do Trabalho)
| Regra | Valor |
|-------|-------|
| Dias por Ano | 30 dias |
| Máx Períodos | 3 |
| Mín Dias/Período | 5 dias |
| Período Principal | 14+ dias (obrigatório) |
| Abono Pecuniário | ✅ Até 10 dias (1/3) |
**Validações:**
```typescript
Período 1: 14 dias Principal (obrigatório)
Período 2: 10 dias Secundário
Período 3: 6 dias Secundário
```
---
### Servidor Público Estadual de PE
| Regra | Valor |
|-------|-------|
| Dias por Ano | 30 dias |
| Máx Períodos | 2 |
| Mín Dias/Período | 10 dias |
| Período Principal | Não há |
| Abono Pecuniário | ❌ Não permitido |
**Validações:**
```typescript
Período 1: 20 dias
Período 2: 10 dias
```
**Avisos Especiais:**
- Docentes: Período preferencial 20/12 a 10/01
- Servidores +10 anos: Podem acumular até 2 períodos
---
## 🚀 FLUXO DO USUÁRIO
### 1⃣ **Funcionário Solicita Férias**
```
1. Acessa: Perfil > Aba "Minhas Férias"
2. Visualiza Dashboard com saldo e estatísticas
3. Clica em "Solicitar Novas Férias"
4. Wizard Passo 1: Escolhe ano de referência
└── Sistema mostra saldo disponível
5. Wizard Passo 2: Seleciona períodos no calendário
└── Validação em tempo real
6. Wizard Passo 3: Revisa e confirma
└── Adiciona observação (opcional)
7. Envia solicitação
└── Toast: "Solicitação enviada com sucesso! 🎉"
└── Notificação enviada ao gestor
```
---
### 2⃣ **Gestor Aprova/Rejeita**
```
1. Recebe notificação (sino no header)
2. Acessa: Perfil > Aba "Aprovar Férias"
3. Visualiza lista de solicitações pendentes
4. Clica em solicitação para detalhes
5. Opções:
├── Aprovar
│ └── Sistema atualiza saldo
│ └── Funcionário recebe notificação
├── Reprovar com motivo
│ └── Sistema libera dias reservados
│ └── Funcionário recebe notificação
└── Ajustar datas e aprovar
└── Sistema recalcula saldo
└── Funcionário recebe notificação
```
---
### 3⃣ **Sistema Automático**
```
Diariamente (Cron Jobs):
1. Cria períodos aquisitivos para funcionários
2. Atualiza status de férias (ativo → em_ferias)
3. Verifica períodos vencidos
4. Envia alertas de saldo baixo
```
---
## 📖 GUIA DE USO
### Para Funcionários
#### Como Solicitar Férias
1. **Acesse seu Perfil:**
- Click no ícone do seu avatar (canto superior direito)
- Selecione "Meu Perfil"
2. **Vá para Minhas Férias:**
- Click na aba "Minhas Férias"
- Visualize seu dashboard com saldos
3. **Solicite Novas Férias:**
- Click no botão grande "Solicitar Novas Férias"
4. **Passo 1 - Escolha o Ano:**
- Selecione o ano de referência
- Verifique seu saldo disponível
- Click em "Próximo"
5. **Passo 2 - Selecione os Períodos:**
- Arraste no calendário para selecionar períodos
- Adicione até 3 períodos (CLT) ou 2 (Servidor PE)
- Observe as validações em tempo real
- Click em "Próximo"
6. **Passo 3 - Confirme:**
- Revise todos os períodos
- Adicione observação (opcional)
- Click em "Enviar Solicitação"
7. **Aguarde Aprovação:**
- Você será notificado quando o gestor aprovar/reprovar
- Acompanhe o status na aba "Minhas Férias"
---
### Para Gestores
#### Como Aprovar Férias
1. **Notificação:**
- Você receberá um sino vermelho no header
- Click nele para ver solicitações pendentes
2. **Acesse Aprovações:**
- Vá em Perfil > Aba "Aprovar Férias"
- Visualize lista de solicitações da sua equipe
3. **Analise a Solicitação:**
- Click em "Ver Detalhes"
- Veja períodos, dias, e observações
4. **Decida:**
- **Aprovar:** Click em "Aprovar"
- **Reprovar:** Click em "Reprovar", escreva motivo
- **Ajustar:** Click em "Ajustar Datas", modifique, e aprove
5. **Confirmação:**
- Funcionário recebe notificação automática
- Status atualizado no sistema
---
### Para TI_MASTER
#### Como Configurar Times
1. **Acesse TI:**
- Menu lateral > Tecnologia da Informação
2. **Gestão de Times:**
- Click em "Times e Membros"
- Visualize lista de times
3. **Criar Time:**
- Click em "Novo Time"
- Preencha: Nome, Descrição, Cor, Gestor
- Adicione membros (funcionários)
- Salve
4. **Gerenciar Membros:**
- Adicione/remova membros de times
- Transfira membros entre times
- Desative times inativos
---
## 🛠️ TECNOLOGIAS UTILIZADAS
### **Frontend**
| Tecnologia | Versão | Uso |
|------------|--------|-----|
| **SvelteKit** | 2.48.1 | Framework principal |
| **Svelte** | 5.42.3 | UI Components |
| **FullCalendar** | 6.1.19 | Calendário interativo |
| **Svelte-Sonner** | 1.0.5 | Toast notifications |
| **Zod** | 4.1.12 | Validação de schemas |
| **DaisyUI** | 5.3.10 | Design system |
| **TailwindCSS** | 4.1.16 | Utility CSS |
### **Backend**
| Tecnologia | Uso |
|------------|-----|
| **Convex** | Backend-as-a-Service |
| **TypeScript** | Type safety |
| **Cron Jobs** | Automações |
### **Outros**
- **Canvas API**: Gráficos de pizza
- **date-fns**: Manipulação de datas
- **Internationalized Date**: Formatação i18n
---
## ✅ TESTES E VALIDAÇÃO
### **Cenários de Teste**
#### Teste 1: Solicitação CLT Válida
```
✅ Funcionário: João (CLT)
✅ Ano: 2025
✅ Saldo: 30 dias disponíveis
✅ Períodos:
- 15 dias (01/06 a 15/06) ← Principal
- 10 dias (01/12 a 10/12)
- 5 dias (20/12 a 24/12)
✅ Resultado: Aprovado ✅
```
#### Teste 2: Servidor PE - Período Inválido
```
❌ Funcionário: Maria (Servidor PE)
❌ Ano: 2025
❌ Saldo: 30 dias disponíveis
❌ Períodos:
- 20 dias (01/06 a 20/06)
- 5 dias (01/12 a 05/12) ← ERRO: Mínimo 10 dias
❌ Resultado: ERRO - "Período de 5 dias é inválido. Mínimo: 10 dias corridos"
```
#### Teste 3: CLT - Sem Período Principal
```
❌ Funcionário: Carlos (CLT)
❌ Períodos:
- 10 dias
- 10 dias
- 10 dias ← Nenhum com 14+
❌ Resultado: ERRO - "Ao dividir férias em CLT, um período deve ter no mínimo 14 dias corridos"
```
#### Teste 4: Saldo Insuficiente
```
❌ Funcionário: Ana
❌ Saldo: 10 dias disponíveis
❌ Solicitação: 20 dias
❌ Resultado: ERRO - "Total solicitado (20 dias) excede saldo disponível (10 dias)"
```
---
## 📂 ESTRUTURA DE ARQUIVOS
```
sgse-app/
├── apps/web/src/
│ ├── lib/
│ │ └── components/
│ │ └── ferias/
│ │ ├── CalendarioFerias.svelte ← Calendário
│ │ ├── WizardSolicitacaoFerias.svelte ← Wizard 3 passos
│ │ └── DashboardFerias.svelte ← Dashboard analytics
│ └── routes/
│ └── (dashboard)/
│ ├── +layout.svelte ← Toaster config
│ └── perfil/
│ └── +page.svelte ← Página principal
├── packages/backend/convex/
│ ├── schema.ts ← periodosAquisitivos + regimeTrabalho
│ ├── saldoFerias.ts ← Cálculos e validações
│ ├── ferias.ts ← CRUD de solicitações
│ ├── times.ts ← Gestão de times
│ └── crons.ts ← Jobs automáticos
└── Documentação/
├── REGRAS_FERIAS_CLT_E_SERVIDOR_PE.md ← Regras detalhadas
└── SISTEMA_FERIAS_MODERNO_COMPLETO.md ← Este arquivo!
```
---
## 🎨 DESIGN SYSTEM
### Cores
- **Primary:** `#667eea` (Roxo)
- **Secondary:** `#764ba2` (Rosa-Roxo)
- **Success:** `#51cf66` (Verde)
- **Warning:** `#ffa94d` (Laranja)
- **Error:** `#ff6b6b` (Vermelho)
- **Info:** `#4facfe` (Azul)
### Componentes Premium
- **Cards com Gradiente:** `from-primary/20 to-secondary/10`
- **Sombras Profundas:** `shadow-2xl`
- **Bordas Suaves:** `rounded-2xl`
- **Hover Effects:** `hover:scale-105 transition-all`
- **Glassmorphism:** Background semi-transparente com blur
---
## 🚀 PRÓXIMOS PASSOS (Futuro)
### Fase 3 - Melhorias Avançadas
1. **Exportação de Relatórios:**
- PDF com histórico de férias
- Excel com estatísticas
- Gráficos impressos
2. **Integração com E-mail:**
- Notificações por e-mail
- Lembretes automáticos
3. **Mobile App:**
- Progressive Web App (PWA)
- Notificações push
4. **IA Inteligente:**
- Sugestão de melhores períodos
- Previsão de conflitos de equipe
- Otimização de agendamento
5. **Integrações:**
- Google Calendar
- Microsoft Outlook
- Folha de pagamento
---
## 📞 SUPORTE
### Problemas Comuns
**1. "Não consigo ver meu saldo"**
- Verifique se você tem um cadastro de funcionário
- Confirme que tem uma data de admissão cadastrada
- Entre em contato com RH
**2. "Validação bloqueando minha solicitação"**
- Leia atentamente a mensagem de erro
- Verifique se está respeitando as regras do seu regime (CLT ou Servidor PE)
- Consulte a documentação de regras
**3. "Gestor não recebeu notificação"**
- Verifique se você está atribuído a um time
- Confirme que o time tem um gestor configurado
- Entre em contato com TI
---
## ✨ CONCLUSÃO
O **Sistema Moderno de Gestão de Férias** representa um avanço significativo na experiência do usuário e na eficiência operacional do SGSE.
### **Benefícios Alcançados:**
**Redução de Erros:** Validação automática previne solicitações inválidas
**Transparência:** Dashboard mostra saldo em tempo real
**Agilidade:** Processo guiado reduz tempo de solicitação
**Conformidade:** Regras CLT e Servidor PE aplicadas automaticamente
**UX Premium:** Interface moderna e intuitiva
### **Métricas de Sucesso:**
- 🎯 **100%** das regras CLT e Servidor PE implementadas
- 🎯 **3 passos** para solicitar férias (vs 10+ no sistema anterior)
- 🎯 **Real-time** validação e feedback
- 🎯 **0 configuração** manual - tudo automático!
---
**Desenvolvido com ❤️ pela equipe SGSE**
**Versão 2.0.0 - Sistema Premium Multi-Regime**
**Data: 30 de outubro de 2025**
🎉 **SISTEMA 100% FUNCIONAL E PRONTO PARA USO!** 🎉