🛡️ Sistema de Permissionamento Hierárquico - Documentação Completa

📋 Visão Geral

O Sistema de Permissionamento Hierárquico é responsável por controlar o acesso de usuários a diferentes níveis da estrutura organizacional com regras de cascata automática. Permite atribuir permissões baseadas na hierarquia (Instituição → Unidade → Turma → Horário) onde permissões de nível superior concedem automaticamente acesso aos níveis inferiores.

Estrutura Hierárquica

Instituição (Nível 1)
├── Unidade (Nível 2)
    ├── Turma (Nível 3)
        ├── Horário (Nível 4)

Regra de Cascata: Uma permissão em nível superior concede acesso automático a todos os níveis inferiores.

Tipos de Hierarquia

Conceitos Importantes

HierarquicoId

O hierarquicoId deve sempre referenciar o ID real da entidade no nível hierárquico correspondente:

TipoUsuarioId

O tipoUsuarioId referencia o ID da relação na tabela relacoes:

🎯 Endpoints Disponíveis

1. GET /api/UsuarioPermissoes

Obter Lista de Permissões

2. POST /api/UsuarioPermissoes

Criar Nova Permissão

3. POST /api/UsuarioPermissoes/verificar

Verificar Permissão

4. GET /api/UsuarioPermissoes/{id}

Obter Permissão por ID

5. PUT /api/UsuarioPermissoes/{id}

Atualizar Permissão

6. POST /api/UsuarioPermissoes/pesquisar

Pesquisar Permissões

7. GET /api/UsuarioPermissoes/usuario/{usuarioId}

Obter Permissões por Usuário

8. POST /api/UsuarioPermissoes/inativar/{id}

Inativar Permissão

9. POST /api/UsuarioPermissoes/reativar/{id}

Reativar Permissão

10. GET /api/UsuarioPermissoes/hierarquicas/{usuarioId}

Obter Permissões Hierárquicas

11. POST /api/Atletas/{id}/inativar

Inativar Atleta

12. GET /api/hierarquia/usuario/{usuarioId}

Obter Hierarquia Completa por Usuário

🔧 Modelo de Dados

Estrutura da Permissão

{
  "id": 1,
  "usuarioId": "user-123",
  "tipoHierarquico": "Instituicao",
  "hierarquicoId": 1,
  "tipoUsuarioId": 7,
  "status": true,
  "dataCriacao": "2024-12-20T10:00:00Z",
  "dataAtualizacao": "2024-12-20T10:00:00Z"
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Criação de Permissão

POST /api/UsuarioPermissoes
Content-Type: application/json
Authorization: Bearer {token}

{
  "usuarioId": "user-123",
  "tipoHierarquico": "Instituicao",
  "hierarquicoId": 1,
  "tipoUsuarioId": 7
}

2. Verificação de Permissão

POST /api/UsuarioPermissoes/verificar
Authorization: Bearer {token}

3. Pesquisa de Permissões

GET /api/UsuarioPermissoes/pesquisar
Content-Type: application/json
Authorization: Bearer {token}

{
  "tipoHierarquico": "Unidade",
  "hierarquicoId": 3,
  "tipoUsuarioId": 8
}

4. Listagem de Permissões

GET /api/UsuarioPermissoes
Authorization: Bearer {token}

5. Busca de Hierarquia por Usuário

GET /api/hierarquia/usuario/{usuarioId}
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Permissão

  1. Validação de dados no backend pela própria API
  2. POST /api/UsuarioPermissoes com dados validados
  3. Verificação de hierarquia automática
  4. Criação de permissão no sistema
  5. Propagação de acesso aos níveis inferiores

Fluxo de Verificação de Permissão

  1. POST /api/UsuarioPermissoes/verificar com dados do usuário
  2. Busca de permissões hierárquicas
  3. Aplicação de regras de cascata
  4. Retorno de acesso permitido/negado

Exemplo de Hierarquia por Usuário

Cenário 1: Usuário com permissão de Instituição

Quando o usuário possui permissão de nível Instituição (TipoHierarquico = 1), o sistema retorna toda a cascata hierárquica:

{
  "instituicao": [
    {
      "id": 2,
      "nome": "01 - Projeto Veleiros",
      "local": "São Paulo, SP",
      "tipo": 1
    }
  ],
  "unidades": [
    {
      "id": 1,
      "nome": "Unidade Centro",
      "local": "Centro",
      "tipo": 1,
      "instituicaoId": 2,
      "instituicaoNome": "01 - Projeto Veleiros"
    }
  ],
  "turmas": [
    {
      "id": 3,
      "nome": "Futsal Infantil",
      "status": true,
      "unidadeId": 1,
      "unidadeNome": "Unidade Centro",
      "responsavelNome": "João Silva",
      "alunosCount": 15
    }
  ],
  "horarios": [
    {
      "id": 10,
      "turmaId": 3,
      "turmaNome": "Futsal Infantil",
      "descHorario": "Segunda 08:30-10:30",
      "usuarios": [
        {
          "id": 28,
          "usuarioId": "guid-123",
          "usuarioNome": "Maria Santos",
          "papelId": 1,
          "papelNome": "Aluno"
        }
      ]
    }
  ]
}

Cenário 2: Usuário com permissão de Turma

Quando o usuário possui permissão de nível Turma (TipoHierarquico = 3), o sistema retorna arrays vazios para níveis superiores (Instituição e Unidades):

{
  "instituicao": [],
  "unidades": [],
  "turmas": [
    {
      "id": 3,
      "nome": "Futsal Infantil",
      "status": true,
      "unidadeId": 1,
      "unidadeNome": "Unidade Centro",
      "responsavelNome": "João Silva",
      "alunosCount": 15
    }
  ],
  "horarios": [
    {
      "id": 10,
      "turmaId": 3,
      "turmaNome": "Futsal Infantil",
      "descHorario": "Segunda 08:30-10:30",
      "usuarios": [...]
    }
  ]
}

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi