sgmp/README_PERMISSOES.md

# 🔐 Sistema de Login, Senhas e Permissões - SGMP

Este documento explica como funciona o sistema de autenticação e controle de permissões do SGMP.

---

## 📋 Índice

1. [Sistema de Login](#sistema-de-login)
2. [Criação de Usuários](#criação-de-usuários)
3. [Perfis e Permissões](#perfis-e-permissões)
4. [Gerenciamento de Permissões](#gerenciamento-de-permissões)
5. [Regras de Acesso](#regras-de-acesso)
6. [Fluxo de Aprovação](#fluxo-de-aprovação)

---

## 🔑 Sistema de Login

### Autenticação

O SGMP utiliza autenticação integrada com o sistema **Winthor** (TOTVS):

- **Login**: Matrícula do funcionário (mesma do sistema Winthor)
- **Senha**: Senha do sistema Winthor
- **Validação**: As credenciais são validadas diretamente no banco Oracle do Winthor

### Processo de Login

1. O usuário acessa a página de login
2. Informa sua **matrícula** e **senha**
3. O sistema consulta o Winthor para validar as credenciais
4. Se válido:
   - Cria/atualiza o registro `UsuarioSistema` no banco do SGMP
   - Cria uma sessão Django para o usuário
   - Redireciona para o Dashboard
5. Se inválido:
   - Exibe mensagem de erro
   - Permanece na página de login

### Primeiro Acesso

Quando um usuário faz login pela primeira vez:

- Um registro `UsuarioSistema` é criado automaticamente
- O perfil padrão é **GESTOR**
- O usuário fica **ativo** por padrão
- O nome é obtido do Winthor

---

## 👥 Criação de Usuários

### Criação Automática

Os usuários são criados **automaticamente** no primeiro login:

- Não é necessário criar usuários manualmente
- O sistema sincroniza com o Winthor
- A matrícula é usada como identificador único

### Criação Manual (Admin Django)

Para criar usuários manualmente ou ajustar dados:

1. Acesse `/admin/` (painel administrativo do Django)
2. Navegue até **Solicitações → Usuários do Sistema**
3. Crie ou edite usuários conforme necessário

**Campos importantes:**
- **Matrícula**: Deve corresponder à matrícula do Winthor
- **Nome**: Nome completo do usuário
- **Perfil**: Define as permissões (veja seção de Perfis)
- **Ativo**: Se desmarcado, o usuário não consegue fazer login

---

## 🎭 Perfis e Permissões

O sistema possui perfis com diferentes níveis de acesso.  
Hoje também existe suporte a **multi-perfis**: cada usuário tem um perfil principal e pode ter perfis adicionais.

### Perfis disponíveis

- `GESTOR`
- `ADMIN`
- `HEAD`
- `GG` (Gente e Gestão)
- `CONTROLADORIA`
- `DIRETORIA`

### Multi-perfis (`UsuarioPerfilExtra`)

- O campo `UsuarioSistema.perfil` guarda o **perfil principal**.
- A tabela `UsuarioPerfilExtra` registra **perfis adicionais**.
- O método `tem_perfil(perfil)` considera tanto o principal quanto os extras.

Exemplos práticos:

- Rosi como **GESTOR** (principal) + **HEAD** (extra):
  - Ela continua podendo criar solicitações como Gestora.
  - Também pode aprovar como Head para os gestores aos quais estiver vinculada (inclusive ela mesma, se for configurada como sua própria head).

---

### 0. ADMIN

**Permissões principais:**
- ✅ Visão completa de todas as solicitações (`dashboard` e `todas as solicitações`)
- ✅ Criar solicitações (como super-perfil de negócio)
- ✅ Registrar parecer técnico quando houver etapa pendente (GG/Controladoria)
- ✅ Aprovar/reprovar em etapas decisórias válidas por status (`AGUARDANDO_HEAD` e `AGUARDANDO_DIRETORIA`)
- ✅ Gerenciar permissões de usuários
- ⚠️ Não ignora o fluxo: ações continuam bloqueadas quando o status não permite

**Uso:** Perfil administrativo de negócio com acesso transversal e governança total.

---

### 1. GESTOR (Gestor)

**Permissões principais:**
- ✅ Criar solicitações (desligamento, admissão, movimentação)
- ✅ Visualizar e editar **suas próprias solicitações** em status `RASCUNHO`
- ✅ Enviar suas solicitações para aprovação
- ✅ Acessar a página de permissões `/permissoes/` para alterar perfis
- ❌ Não aprova solicitações por padrão (a menos que também tenha outro perfil, como HEAD ou DIRETORIA)

**Uso:** Gestores de equipe que iniciam processos de RH.

---

### 2. HEAD

**Permissões principais:**
- ✅ Visualizar solicitações com status `AGUARDANDO_HEAD`  
- ✅ Aprovar ou reprovar como Head quando:
  - A solicitação está em `AGUARDANDO_HEAD`, e
  - O solicitante é um Gestor vinculado a esse Head em `HeadGestor` (ou o próprio, se configurado)
- ✅ Acessar a página de permissões `/permissoes/` (mesmas regras gerais)
- ❌ Não cria solicitações apenas por ser Head (isso depende de também ter perfil de Gestor)

**Uso:** Camada intermediária de aprovação antes de a solicitação seguir para GG/Controladoria.

---

### 3. GG (Gente e Gestão)

**Permissões principais:**
- ✅ Visualizar solicitações com status `ENVIADA`
- ✅ Registrar **parecer técnico** (modelo `Parecer`) na etapa GG
- ✅ Visualizar detalhes completos das solicitações
- ✅ Acessar a página de permissões `/permissoes/`
- ❌ Não cria novas solicitações apenas por ser GG
- ❌ Não aprova/reprova a solicitação (apenas emite parecer)

**Uso:** Primeira etapa de análise técnica (pessoas).

---

### 4. CONTROLADORIA

**Permissões principais:**
- ✅ Visualizar solicitações com status `ENVIADA`
- ✅ Registrar **parecer técnico** na etapa Controladoria
- ✅ Visualizar detalhes completos das solicitações
- ✅ Acessar a página de permissões `/permissoes/`
- ❌ Não cria novas solicitações apenas por ser Controladoria
- ❌ Não aprova/reprova a solicitação (apenas emite parecer)

**Uso:** Análise financeira/orçamentária antes da decisão final.

---

### 5. DIRETORIA

**Permissões principais:**
- ✅ Visualizar solicitações em status `AGUARDANDO_DIRETORIA`
- ✅ Aprovar ou reprovar solicitações na **etapa final**, alterando o status para `FINALIZADA` ou `REPROVADA`
- ✅ Visualizar detalhes completos das solicitações
- ✅ Acessar a página de permissões `/permissoes/`
- ❌ Não cria novas solicitações apenas por ser Diretoria

**Uso:** Aprovação final e decisão executiva.

---

## ⚙️ Gerenciamento de Permissões

### Acessando a Página de Permissões

1. Faça login no sistema
2. No menu lateral, clique em **"Administração"** (ícone ⚙️)
3. Você será redirecionado para a página de gerenciamento de permissões

### Funcionalidades

A página de permissões permite:

- **Visualizar todos os usuários** do sistema
- **Buscar usuários** por nome ou matrícula
- **Alterar o perfil principal** de qualquer usuário (incluindo o seu próprio)
- **Atribuir/remover perfis adicionais** (multi-perfis)
- **Ver o status** (ativo/inativo) de cada usuário
- **Identificar seu próprio perfil** (marcado como "Você")

### Como Alterar perfis (principal e adicionais)

1. Na tabela de usuários, localize o usuário desejado.
2. Na coluna **Alterar Perfil**, escolha o **perfil principal** no dropdown.
3. Logo abaixo, marque/desmarque as **checkboxes de Perfis adicionais** (HEAD, GG, CONTROLADORIA, DIRETORIA, etc.).
4. Clique em **"Atualizar"**.
5. Uma mensagem de confirmação será exibida.

### Regras Importantes

- ✅ Qualquer usuário autenticado pode alterar permissões
- ✅ Você pode alterar seu próprio perfil
- ✅ Você pode alterar o perfil de outros usuários
- ⚠️ Alterar seu próprio perfil pode afetar suas permissões imediatamente

---

## 🔒 Regras de Acesso

### Dashboard

O dashboard exibe diferentes informações conforme o perfil:

#### GESTOR
- Vê apenas **suas próprias solicitações**.
- Pode filtrar por status (Total, Pendentes, Aprovadas, Reprovadas).
- Vê solicitações em todos os status (incluindo `RASCUNHO`).

#### HEAD
- Vê solicitações em `AGUARDANDO_HEAD` cujo solicitante é um Gestor vinculado a ele em `HeadGestor`.
- Visualiza o contexto completo da solicitação para poder decidir.

#### GG e CONTROLADORIA
- Veem solicitações em status `ENVIADA` onde ainda **não deram parecer**.
- Após registrar o parecer, essa solicitação deixa de aparecer para aquele usuário na tela principal de trabalho.

#### DIRETORIA
- Vê solicitações em status `AGUARDANDO_DIRETORIA` (aguardando decisão final).
- Não vê rascunhos nem solicitações já finalizadas / reprovadas como itens de trabalho.

### Criação de Solicitações

- **GESTOR e ADMIN** podem criar solicitações
- Outros perfis verão mensagem de erro se tentarem acessar formulários de criação

### Visualização de Detalhes

- Todos os perfis podem visualizar detalhes de solicitações
- O formulário de aprovação só aparece para perfis com permissão de aprovar

### Aprovação/Reprovação

- **HEAD** pode aprovar/reprovar solicitações em `AGUARDANDO_HEAD` desde que tenha perfil de Head (principal ou extra) e esteja vinculado ao gestor solicitante.
- **DIRETORIA** pode aprovar/reprovar solicitações em `AGUARDANDO_DIRETORIA`.
- **ADMIN** também pode aprovar/reprovar nas etapas válidas por status (sem burlar o estado atual).
- GG e CONTROLADORIA não aprovam; registram pareceres que alimentam a decisão da Diretoria.
- O solicitante **pode** aprovar se também tiver perfil de aprovação (por exemplo, for Head ou Diretoria e estiver autorizado pelas regras de vínculo).

---

## 📊 Fluxo de Aprovação

### Estados da Solicitação

1. **RASCUNHO**: Solicitação criada, ainda não enviada.
2. **AGUARDANDO_HEAD**: Aguardando decisão do Head (quando aplicável).
3. **ENVIADA**: Enviada para parecer de GG/Controladoria.
4. **APROVADA_GG** / **APROVADA_CONTROLADORIA**: estados intermediários registrados para histórico.
5. **AGUARDANDO_DIRETORIA**: Aguardando decisão final da Diretoria.
6. **FINALIZADA**: Aprovada pela Diretoria (processo concluído).
7. **REPROVADA**: Reprovação em qualquer etapa (processo encerrado).

### Fluxo Completo

```
GESTOR cria solicitação
    ↓
Status: RASCUNHO
    ↓
GESTOR envia para aprovação
    ↓
Status: AGUARDANDO_HEAD (quando há etapa de Head)
    ↓
HEAD analisa e aprova/reprova
    ↓
Status: ENVIADA
    ↓
GG registra parecer
    ↓
CONTROLADORIA registra parecer
    ↓
Status: AGUARDANDO_DIRETORIA
    ↓
DIRETORIA analisa pareceres e aprova/reprova
    ↓
Se aprovada → Status: FINALIZADA
```

### Regras de Aprovação

- Apenas perfis com permissão de decisão podem aprovar (HEAD e DIRETORIA, conforme etapa/status).
- GG e CONTROLADORIA registram pareceres, não aprovam.
- Uma reprovação em qualquer etapa de decisão encerra o processo.
- Solicitações em `RASCUNHO` só são visíveis para o criador.

---

## 🛠️ Solução de Problemas

### Não consigo fazer login

**Possíveis causas:**
- Matrícula ou senha incorretas
- Usuário inativo no sistema
- Problema de conexão com o Winthor

**Solução:**
1. Verifique suas credenciais do Winthor
2. Acesse o admin Django (`/admin/`) e verifique se o usuário está ativo
3. Verifique a conexão com o banco Oracle

### Não vejo minhas solicitações

**Possíveis causas:**
- Perfil incorreto
- Solicitações em status "Rascunho" (só visíveis para o criador)
- Filtro aplicado no dashboard

**Solução:**
1. Verifique seu perfil na página de permissões
2. Se for GESTOR, certifique-se de que criou as solicitações
3. Limpe os filtros no dashboard

### Não consigo aprovar solicitações

**Possíveis causas:**
- Perfil sem permissão de aprovação
- Tentando aprovar sua própria solicitação
- Solicitação não está na sua etapa

**Solução:**
1. Verifique seu perfil (deve ser GG, CONTROLADORIA ou DIRETORIA)
2. Certifique-se de que não é o solicitante
3. Verifique se a solicitação está no status correto para sua etapa

### Não consigo criar solicitações

**Possíveis causas:**
- Perfil não é GESTOR

**Solução:**
1. Acesse a página de permissões
2. Altere seu perfil para GESTOR
3. Faça logout e login novamente

---

## 📝 Notas Importantes

1. **Senhas**: As senhas são gerenciadas pelo Winthor. O SGMP não armazena senhas.

2. **Sincronização**: O nome do usuário é sincronizado do Winthor no primeiro login.

3. **Perfil Padrão**: Novos usuários recebem automaticamente o perfil GESTOR.

4. **Ativação**: Usuários podem ser desativados no admin Django, impedindo login.

5. **Segurança**: Qualquer usuário autenticado pode gerenciar permissões. Considere restringir isso se necessário.

---

## 🔗 Links Úteis

- **Página de Login**: `/login/`
- **Dashboard**: `/solicitacoes/`
- **Gerenciar Permissões**: `/solicitacoes/permissoes/`
- **Admin Django**: `/admin/`

---

**Última atualização**: 2024