sgse-app/COMO_ASSOCIAR_FUNCIONARIO_A_USUARIO.md

✅ COMO ASSOCIAR FUNCIONÁRIO A USUÁRIO

Data: 30 de outubro de 2025
Objetivo: Associar cadastro de funcionário a usuários para habilitar funcionalidades como férias

---

🎯 PROBLEMA RESOLVIDO

ANTES:
❌ "Perfil de funcionário não encontrado" ao tentar solicitar férias
❌ Usuários não tinham acesso a funcionalidades de RH
❌ Sem interface para fazer associação

DEPOIS:
✅ Interface completa em TI > Gerenciar Usuários
✅ Busca e seleção visual de funcionários
✅ Validação de duplicidade
✅ Opção de associar, alterar e desassociar

---

🚀 COMO USAR (PASSO A PASSO)

1️⃣ Acesse o Gerenciamento de Usuários

1. Faça login como TI_MASTER
2. Menu lateral > Tecnologia da Informação
3. Click em "Gerenciar Usuários"

---

2️⃣ Localize o Usuário

Opção A: Busca Direta

• Digite nome, matrícula ou email no campo de busca

Opção B: Filtros

• Filtre por status: Todos / Ativos / Bloqueados / Inativos

Visual:

┌─────────────────────────────────────────────────┐
│ Matrícula │ Nome │ Email │ Funcionário │ Status │
├───────────┼──────┼───────┼─────────────┼────────┤
│ 00001     │ TI   │ ti@   │ ⚠️ Não      │ ✅     │
│           │Master│gov.br │ associado   │ Ativo  │
└─────────────────────────────────────────────────┘

---

3️⃣ Associar Funcionário

Click no botão azul "Associar" ou "Alterar"

Um modal abrirá com:

┌─────────────────────────────────────────────┐
│ Associar Funcionário ao Usuário             │
├─────────────────────────────────────────────┤
│ Usuário: Gestor TI Master (00001)           │
│                                              │
│ Buscar Funcionário:                         │
│ [Digite nome, CPF ou matrícula...]          │
│                                              │
│ Selecione o Funcionário:                    │
│ ┌─────────────────────────────────────────┐ │
│ │ ○ João da Silva                         │ │
│ │   CPF: 123.456.789-00                   │ │
│ │   Cargo: Analista                       │ │
│ ├─────────────────────────────────────────┤ │
│ │ ● Maria Santos (SELECIONADO)           │ │
│ │   CPF: 987.654.321-00                   │ │
│ │   Cargo: Gestor                         │ │
│ └─────────────────────────────────────────┘ │
│                                              │
│ [Cancelar]  [Desassociar]  [Associar]      │
└─────────────────────────────────────────────┘

---

4️⃣ Buscar e Selecionar

1. Busque o funcionário (digite nome, CPF ou matrícula)
2. Click no radio button ao lado do funcionário correto
3. Verifique os dados (nome, CPF, cargo)
4. Click em "Associar"

---

5️⃣ Confirmação

✅ Sucesso! Você verá:

Alert: "Funcionário associado com sucesso!"

A coluna "Funcionário" agora mostrará:

✅ Associado (badge verde)

---

🧪 TESTAR O SISTEMA DE FÉRIAS

Após associar o funcionário:

1. Recarregue a página (F5)

2. Acesse seu Perfil:

   • Click no avatar (canto superior direito)
   • "Meu Perfil"

3. Vá para "Minhas Férias":

   • Agora deve mostrar o Dashboard de Férias ✨
   • Sem mais erro de "Perfil não encontrado"!

4. Solicite Férias:

   • Click em "Solicitar Novas Férias"
   • Siga o wizard de 3 passos
   • Teste o calendário interativo

---

🔧 FUNCIONALIDADES DO MODAL

✅ Associar Novo Funcionário

• Busca em tempo real
• Ordenação alfabética
• Exibe nome, CPF, matrícula e cargo

🔄 Alterar Funcionário Associado

• Mesma interface
• Alert avisa se já tem associação
• Atualiza automaticamente

❌ Desassociar Funcionário

• Botão vermelho "Desassociar"
• Confirmação antes de executar
• Remove a associação

---

🛡️ VALIDAÇÕES E SEGURANÇA

✅ O Sistema Verifica:

1. Funcionário existe?

   ❌ Erro: "Funcionário não encontrado"
   

2. Já está associado a outro usuário?

   ❌ Erro: "Este funcionário já está associado ao usuário: João Silva (12345)"
   

3. Funcionário selecionado?

   ❌ Botão "Associar" fica desabilitado
   

---

🎨 INDICADORES VISUAIS

Coluna "Funcionário"

✅ Associado:

🟢 Badge verde com ícone de check

⚠️ Não Associado:

🟡 Badge amarelo com ícone de alerta

Botão de Ação

🔵 Associar (azul)

• Usuário sem funcionário

🔵 Alterar (azul)

• Usuário com funcionário já associado

---

📊 ESTATÍSTICAS

Você pode ver quantos usuários têm/não têm funcionários:

Cards no topo:
┌─────────┬─────────┬────────────┬──────────┐
│ Total   │ Ativos  │ Bloqueados │ Inativos │
│   42    │   38    │     2      │    2     │
└─────────┴─────────┴────────────┴──────────┘

---

🐛 TROUBLESHOOTING

Problema: "Funcionário já está associado"

Causa: Funcionário está vinculado a outro usuário

Solução:

1. Identifique qual usuário tem o funcionário (mensagem de erro mostra)
2. Desassocie do usuário antigo primeiro
3. Associe ao usuário correto

---

Problema: Lista de funcionários vazia

Causa: Nenhum funcionário cadastrado no sistema

Solução:

1. Vá em Recursos Humanos > Gestão de Funcionários
2. Click em "Cadastrar Funcionário"
3. Preencha os dados e salve
4. Volte para associar

---

Problema: Busca não funciona

Causa: Nome/CPF/matrícula não confere

Solução:

1. Limpe o campo de busca
2. Veja lista completa
3. Procure visualmente
4. Click para selecionar

---

💡 DICAS PRO

1. Associação em Lote

Para associar vários usuários:

1. Filtre por "Não associado"
2. Associe um por vez
3. Use busca rápida de funcionários

2. Verificar Associações

Filtro de coluna "Funcionário":
- Badge verde = OK
- Badge amarelo = Pendente

3. Organização

Recomendação:
- Associe funcionários assim que criar usuários
- Mantenha dados sincronizados
- Revise periodicamente

---

🎯 CASO DE USO: SEU TESTE DE FÉRIAS

Para o seu usuário TI Master:

1. Acesse: TI > Gerenciar Usuários

2. Localize: Seu usuário (ti.master@sgse.pe.gov.br)

3. Click: Botão azul "Associar"

4. Busque: Seu nome ou crie um funcionário de teste

5. Selecione: O funcionário correto

6. Confirme: Click em "Associar"

7. Teste: Perfil > Minhas Férias

✅ Pronto! Agora você pode testar todo o sistema de férias!

---

📝 CHECKLIST DE VERIFICAÇÃO

Após associar, verifique:

• Badge mudou de amarelo para verde
• Recarreguei a página
• Acessei meu perfil
• Abri aba "Minhas Férias"
• Dashboard carregou corretamente
• Não aparece mais erro
• Posso clicar em "Solicitar Férias"
• Wizard abre normalmente

---

🎉 RESULTADO ESPERADO

Interface Completa:

TI > Gerenciar Usuários
  └── Tabela com coluna "Funcionário"
      ├── Badge: ✅ Associado / ⚠️ Não associado
      └── Botão: [Associar] ou [Alterar]
          └── Modal com:
              ├── Busca de funcionários
              ├── Lista com radio buttons
              └── Botões: Cancelar | Desassociar | Associar

---

🔗 ARQUIVOS MODIFICADOS

Frontend:

apps/web/src/routes/(dashboard)/ti/usuarios/+page.svelte
  ├── + Coluna "Funcionário" na tabela
  ├── + Badge de status (Associado/Não associado)
  ├── + Botão "Associar/Alterar"
  ├── + Modal de seleção de funcionários
  ├── + Busca em tempo real
  └── + Funções: associar/desassociar

Backend:

packages/backend/convex/usuarios.ts
  ├── + associarFuncionario() mutation
  ├── + desassociarFuncionario() mutation
  └── + Validação de duplicidade

---

✅ CONCLUSÃO

Agora você tem uma interface completa e profissional para:

✅ Associar funcionários a usuários
✅ Alterar associações
✅ Desassociar quando necessário
✅ Buscar e filtrar funcionários
✅ Validações automáticas
✅ Feedback visual claro

RESULTADO: Todos os usuários podem agora acessar funcionalidades que dependem de cadastro de funcionário, como Gestão de Férias! 🎉

---

Desenvolvido por: Equipe SGSE
Data: 30 de outubro de 2025
Versão: 1.0.0 - Associação de Funcionários