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