# 07 — Autorização e Papéis de Usuário

## Campo `cargo` — O Núcleo da Autorização

O sistema não usa papéis (roles) em tabela separada. A autorização é baseada em um único campo inteiro:

```
usuario.cargo → 0 | 1 | 2 | 3 | 4
```

| Valor | Papel Padrão | Nome Configurável via `constantes.niveis_gerenciais` |
|-------|-------------|------------------------------------------------------|
| `0` | Executor | "Colaborador" (padrão) |
| `1` | Gestor N1 | "Supervisor" |
| `2` | Gestor N2 | "Coordenador" |
| `3` | Gestor N3 | "Diretor" |
| `4` | Gestor N4 | "Presidente" |

O campo `admin` (0 ou 1) é separado e controla apenas o acesso às telas de Configurações. Administradores podem ter qualquer `cargo`.

---

## Visibilidade por Cargo no Dashboard

### Card INBOX
```
cargo == 0 → 0 (executores não veem inbox)
cargo >= 1 → COUNT(tarefas com distribuicao=1 na minha divisão, status ≠ 7,8)
```

### Card EXECUÇÃO
```
cargo == 0 → Minhas tarefas (status IN 1,2,9,10,4,6,13,15 excluindo conclusão)
cargo == 1 → Tarefas da minha divisão (status IN 1,2,3,6,9,10)
cargo == 2 → Tarefas da minha coordenação (status IN 1,2,5,13,9,10)
cargo == 3 → Tarefas da minha diretoria (status IN 1,2,11,15,9,10)
cargo == 4 → Tarefas da minha estrutura_4 (status IN 1,2,14,9,10)
```

### Card MONITORAMENTO
```
cargo == 0 → Minhas tarefas em status de revisão (status IN 3,5,6,11,13,14,15)
cargo == 1 → Tarefas da divisão em status acima do meu (5,6,9,10,11,13,14,15)
cargo == 2 → Tarefas em status acima (9,10,11,13,14,15)
cargo == 3 → Tarefas em status acima (9,10,14,15)
cargo == 4 → Tarefas em status 9,10
```

### Card CUSTOS
```
cargo == 0 → 0 (não aprova)
cargo >= 1 → COUNT(autoriza_custo pendente para categorias com alcada_custo.cargo <= meu cargo)
```

### Card CONCLUÍDOS
```
Todos → COUNT(tarefa_conclusao WHERE usuario_id = $user_id AND ciencia = 0)
       + COUNT(demanda_conclusao WHERE usuario_id = $user_id AND ciencia = 0)
```

---

## Revisão de Tarefas por Cargo

### Regra de Notificação ao Mudar Status

| Novo status_id | status_desc | Quem recebe push |
|----------------|-------------|-----------------|
| 3 | Em análise - N1 | cargo=1 do projeto |
| 4 | Analisada - N1 | cargo=0 do executor |
| 5 | Em análise - N2 | cargo=2 do projeto |
| 6 | Analisada - N2 | cargo=1 do projeto |
| 11 | Em análise - N3 | cargo=3 do projeto |
| 13 | Analisada - N3 | cargo=2 do projeto |
| 14 | Em análise - N4 | cargo=4 do projeto |
| 15 | Analisada - N4 | cargo=3 do projeto |

**Query para encontrar destinatários:**
```sql
SELECT DISTINCT u.usuario_id 
FROM demanda_recursos dr
JOIN usuario u ON dr.usuario_id = u.usuario_id
JOIN tarefa t ON t.demanda_id = dr.demanda_id
WHERE t.tarefa_id = $tarefa_id 
  AND u.cargo = $target_cargo 
  AND u.ativo = 1
  AND dr.status = 1
  AND u.usuario_id != $user_id  -- não notifica quem fez a mudança
```

---

## Alçadas de Aprovação de Custo

A tabela `alcada_custo` define quem pode aprovar qual tipo de custo e até qual valor:

```sql
CREATE TABLE alcada_custo (
  alcada_custo_id INT PK,
  categoria_custo_id INT FK,
  cargo INT,          -- Cargo mínimo para aprovar
  autorizacao INT,    -- 1 = pode autorizar
  limite DECIMAL      -- Valor máximo que pode aprovar
);
```

**Lógica de aprovação:**
```
Um custo está disponível para aprovação por um usuário SE:
  1. custo.necessita_aprovacao = 1
  2. autoriza_custo.status = 0 (pendente)
  3. usuario.cargo >= alcada_custo.cargo da categoria do custo
  4. custo.valor <= alcada_custo.limite (OR limite = NULL = sem limite)
```

---

## Distribuição de Tarefas (INBOX)

### Fluxo
1. Criador cria tarefa com `distribuicao=1` + `distribuicao_divisao_id`
2. Gestor (cargo ≥ 1) da divisão vê no INBOX
3. Gestor escolhe o responsável → `update_task_responsible` com `distribuicao=false` + `new_user_id`
4. Tarefa sai do INBOX e vai para EXECUÇÃO

### Criação de Tarefa para Distribuição
```
POST task_actions.php
{
  "action": "create_task",
  "distribuicao": true,
  "distribuicao_divisao_id": 5,
  "descricao": "...",
  ...
}
```
→ Push para todos os usuários da divisão com cargo IN (1,2,3,4)

---

## Campo `admin` — Controle de Configurações

| `admin` | Acesso |
|---------|--------|
| `0` | Usuário normal |
| `1` | Acesso ao menu "Configurações" e todas as settings screens |

O menu `GlobalMenu` verifica `userData?.admin == 1` para exibir o item "Configurações".

---

## Visão por Nível da Organização

Ao buscar tarefas para exibição, o backend usa a hierarquia do usuário:

```php
// Rehydrate do usuário (dashboard.php)
$sql_user = "SELECT usuario.*, divisao.*, coordenacao.*, diretoria.*, estrutura_gerencial_4.*
             FROM usuario
             LEFT JOIN divisao ON usuario.divisao_id = divisao.divisao_id
             LEFT JOIN coordenacao ON divisao.coordenacao_id = coordenacao.coordenacao_id
             LEFT JOIN diretoria ON coordenacao.diretoria_id = diretoria.diretoria_id
             LEFT JOIN estrutura_gerencial_4 ON diretoria.estrutura_gerencial_4_id = ...
             WHERE usuario.usuario_id = $user_id";

// Variáveis extraídas:
$sess_divisao_id = ...
$sess_coordenacao_id = ...
$sess_diretoria_id = ...
$sess_estrutura_gerencial_4_id = ...
```

Cada query de contagem usa o ID correspondente ao nível do cargo do usuário para filtrar tarefas de **toda a sua área de responsabilidade**, não apenas as suas.