Pular para o conteúdo principal

Gestão de Usuários e Permissões (Web App)

Pilar: 02 — Funcionalidades Core / Web App
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-web (src/screens/admin/Users), gatein-server (app/api/web/users.py, app/core/dependencies.py)

1. Visão Geral e Arquitetura do Módulo​

O módulo de Gestão de Usuários e Permissões permite que Administradores de empresa provisionem, editem, alterem papéis funcionais e desativem contas de operadores que possuem acesso ao Web App. Cada usuário criado é vinculado automaticamente à empresa do Administrador (company_id) e sincronizado com o provedor de identidade Firebase Auth.

1.1 Diagrama de Sequência de Criar e Desativar Usuário Web​

sequenceDiagram
    autonumber
    actor A as Admin da Empresa (Web App)
    participant S as Gatein Server (FastAPI)
    participant FB as Firebase Admin SDK
    participant DB as PostgreSQL
    participant E as Serviço de E-mail

    rect rgb(240, 248, 255)
    note over A, E: Fluxo 1: Provisionamento de Novo Operador
    A->>S: POST /web/users (name, email, role)
    S->>S: Valida se email é único e se caller é Admin
    S->>FB: create_user(email, password_temp)
    S->>DB: Insere registro em company_users (is_active = True)
    S->>E: Dispara e-mail de definição de senha (Password Reset Link)
    S-->>A: HTTP 201 (Usuário provisionado com sucesso)
    end

    rect rgb(255, 240, 240)
    note over A, DB: Fluxo 2: Desativação e Revogação de Sessão
    A->>S: PATCH /web/users/{user_id} (is_active = False)
    S->>S: Verifica RN-USR-002 (Impede desativar último Admin)
    S->>DB: Atualiza CompanyUser.is_active = False
    S->>FB: revoke_refresh_tokens(uid) -> Invalida sessões ativas
    S-->>A: HTTP 200 (Usuário desativado com sucesso)
    end

2. Estruturas de Dados e Schemas Explícitos​

2.1 Schemas de Requisição e Resposta (Pydantic)​

Payload de Criação (CreateUserPayload):​

{
  "name": "Mariana Oliveira",
  "email": "mariana.oliveira@terminal.com.br",
  "role": "terminal"
}

Payload de Atualização (UpdateUserPayload):​

{
  "name": "Mariana Oliveira Santos",
  "role": "admin",
  "is_active": true
}

Schema de Resposta da Listagem (UserListResponse):​

{
  "success": true,
  "data": [
    {
      "id": "p4k2n8m9",
      "name": "Mariana Oliveira Santos",
      "email": "mariana.oliveira@terminal.com.br",
      "role": "admin",
      "is_active": true,
      "created_at": "2026-08-02T14:20:00Z"
    }
  ]
}

3. Regras de Negócio Explícitas (RN-USR-XXX)​

RN-USR-001: Bloqueio de Auto-Alteração de Role​

Um usuário logado no Web App não pode alterar seu próprio papel funcional (role) ou desativar a si mesmo. Tentativas de alterar a própria conta via PATCH /web/users/{self_id} retornarão HTTP 400 (CANNOT_MODIFY_SELF).

RN-USR-002: Proteção do Último Administrador da Empresa​

A plataforma impede a desativação (is_active = False) ou alteração de papel do último usuário com role == "admin" da empresa. A API verifica a contagem de admins ativos antes de processar a requisição e lança HTTP 400 (LAST_ADMIN_CANNOT_BE_DISABLED).

RN-USR-003: Unicidade Global de E-mail​

O endereço de e-mail deve ser único em todo o sistema (PostgreSQL + Firebase Auth). Submissões com e-mail duplicado retornam HTTP 400 (EMAIL_ALREADY_EXISTS).

RN-USR-004: Revogação Imediata de Tokens Firebase em Desativação​

Quando um operador tem seu campo is_active alterado para False, o backend invoca obrigatoriamente a função auth.revoke_refresh_tokens(firebase_uid) no Firebase Admin SDK. Qualquer requisição subsequente do operador desativado será bloqueada imediatamente no interceptor da API.

RN-USR-005: Regra de Exclusividade do Role "Admin" (Sem Admin Parcial)​

No ecossistema Gatein, o papel admin possui permissões totais sobre a empresa. Não é possível aplicar restrições parciais a um usuário admin. Na interface do Web App, todos os admins exibem a tag fixa "Acesso Total".

4. Detalhamento de Endpoints​

4.1 GET /web/users​

Retorna a lista de usuários da empresa do administrador autenticado.

4.2 POST /web/users​

Provisiona um novo operador no Firebase Auth e na tabela company_users.

4.3 PATCH /web/users/{user_id}​

Atualiza o nome, papel funcional ou status de ativação de um operador.

4.4 DELETE /web/users/{user_id}​

Realiza a desativação lógica (is_active = False) e revoga sessões no Firebase.

5. Regras de Segurança e Tabela de Erros​

Código HTTPCódigo InternoCausa RaizAção no Web App
400 Bad RequestCANNOT_MODIFY_SELFAdmin tentou alterar a própria contaExibir alerta de ação não permitida
400 Bad RequestLAST_ADMIN_CANNOT_BE_DISABLEDTentativa de desativar o único adminPromover outro usuário a admin antes
400 Bad RequestEMAIL_ALREADY_EXISTSE-mail já cadastrado em outra contaSolicitar outro endereço de e-mail
403 ForbiddenINSUFFICIENT_PERMISSIONSOperador sem permissão admin tentou gerenciar usuáriosOcultar aba de gestão na UI