Pular para o conteúdo principal

Autenticação Web e Gestão de 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/LoginPage, src/store/authStore), gatein-server (app/api/web/auth.py, app/core/dependencies.py), gatein-app (Consumidor de dados configurados no Web App)

1. Visão Geral e Arquitetura de Identidade​

O sistema de Autenticação Web gerencia o acesso de operadores de Terminais, empresas Transportadoras e Administradores de Plataforma. Ao contrário do aplicativo mobile (que utiliza login direto por CPF com tokens JWT próprios do Gatein), o aplicativo Web adota uma arquitetura híbrida de segurança:

  1. Identidade e Autenticação Criptográfica: Gerenciada pelo Firebase Auth SDK (Web), responsável pelo controle de credenciais (E-mail/Senha), emissão e renovação automática de ID Tokens (JWT com validade de 1 hora).
  2. Autorização e Regras de Tenant (RBAC): Processada no backend FastAPI via validação da tabela company_users, associando a identidade Firebase a um company_id específico e atribuindo papéis funcionais (role).

1.1 Diagrama de Sequência de Autenticação e Integração com Mobile​

sequenceDiagram
    autonumber
    actor U as Usuário Web (Operador / Admin)
    participant W as Web App (React / Vite)
    participant FB as Firebase Auth
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL
    actor M as App Mobile (Motorista)

    U->>W: Insere E-mail e Senha no formulário
    W->>FB: signInWithEmailAndPassword(email, password)
    FB-->>W: Retorna Firebase ID Token (JWT com TTL 1h)
    W->>S: GET /web/auth/me (Header: Authorization Bearer <token>)
    S->>FB: verify_id_token(token) via Firebase Admin SDK
    S->>DB: Query CompanyUser (join Company) por email/uid
    S->>S: Valida is_active == True e permissões por Role
    S-->>W: Retorna perfil completo (CompanyUserResponse)
    W->>W: Armazena estado global na authStore e abre Dashboard
    
    note over W, M: Configurações de Pátio, Layouts e Geofence salvas no Web App<br/>ficam disponíveis instantaneamente para o App Mobile dos motoristas.

2. Estrutura de Usuários e Matriz de Permissões (RBAC)​

2.1 Modelo Relacional no Banco de Dados (company_users)​

ColunaTipo SQLConstraintsDescrição / Regra
idUUIDPRIMARY KEY, Default gen_random_uuid()Identificador único interno
company_idUUIDFOREIGN KEY (companies.id), NOT NULLEmpresa à qual o usuário pertence (Tenant)
emailVARCHAR(255)UNIQUE, NOT NULLE-mail de login (chave de vínculo com Firebase Auth)
nameVARCHAR(255)NOT NULLNome completo do usuário/operador
roleVARCHAR(32)NOT NULL, Default 'terminal'Papel funcional no sistema (admin, terminal, transportador, platform_admin)
is_activeBOOLEANNOT NULL, Default TrueStatus de ativação da conta física
created_atTIMESTAMPTZNOT NULL, Default now()Data de provisionamento do usuário

2.2 Matriz de Acesso por Role​

RoleEscopo de AcessoAções PermitidasImpacto no App Mobile
adminTotal na EmpresaAcesso irrestrito a API Keys, usuários, geofence, serviços, layouts, anúncios e relatórios.Controla parâmetros globais visualizados pelo motorista.
terminalOperacional PátioGestão de agendamentos (Appointments), aprovação/rejeição de check-ins, controle de docas e emissão de tickets.Libera entradas físicas e despacha notificações FCM de ticket ao celular do motorista.
transportadorOperacional FrotaCadastro de viagens (Trips), solicitação de agendamentos e acompanhamento de status de carga.Define viagens e cargas atribuídas ao CPF do motorista.
platform_adminGlobal / InfraAcesso a todas as empresas clientes, gestão de chaves de sistema e ferramentas de homologação.Gerencia dados de staging/fake GPS.

3. Schemas de Requisição e Resposta​

Resposta de Perfil Autenticado (CompanyUserResponse):​

{
  "success": true,
  "data": {
    "user": {
      "id": "p4k2n8m9",
      "email": "carlos.eduardo@terminal-santos.com.br",
      "name": "Carlos Eduardo",
      "role": "admin",
      "is_active": true,
      "company": {
        "id": "c9x8v7b6",
        "name": "Terminal Marítimo Santos",
        "type": "terminal",
        "use_remote_checkin": true
      }
    }
  }
}

Alteração de Senha (POST /web/auth/change-password):​

  • Request:
{
  "current_password": "SenhaAntiga123!",
  "new_password": "NovaSenhaSegura456!"
}
  • Response: { "success": true, "message": "Senha alterada com sucesso." }

4. Regras de Negócio Explícitas (RN-WEB-AUTH-XXX)​

RN-WEB-AUTH-001: Validação Rígida de Status Ativo (is_active)​

Mesmo que a autenticação no Firebase Auth retorne sucesso, a dependência get_current_company_user do FastAPI consulta o banco de dados e rejeita requisições com HTTP 403 (USER_DEACTIVATED) caso o campo is_active esteja como False.

RN-WEB-AUTH-002: Isolamento Automático de Tenant (company_id)​

A extração do company_id é efetuada estritamente através da sessão do usuário autenticado no token Firebase. O cliente Web não tem permissão para alterar o company_id nos cabeçalhos ou payloads para acessar dados de terceiros.

RN-WEB-AUTH-003: Papel Admin com Acesso Irrestrito Dentro da Empresa​

Usuários com role == "admin" possuem validação bypassed em checagens de permissões granulares (require_permission), tendo controle total sobre os módulos da sua empresa. A interface exibe a tag "Acesso Total".

RN-WEB-AUTH-004: Sincronização entre Web App e App Mobile​

Alterações realizadas por usuários web (ex: atualizar geofence, publicar anúncios, emitir tickets) disparam invalidação de cache e/ou notificações FCM em tempo real para os aplicativos mobile dos motoristas impactados.

5. Tabela de Erros de Autenticação Web​

Código HTTPCódigo InternoCausa RaizAção Recomendada no Web App
401 UnauthorizedINVALID_FIREBASE_TOKENID Token expirado (> 1h) ou token corrompidoExecutar firebase.auth().signOut() e redirecionar para /login
403 ForbiddenUSER_DEACTIVATEDOperador desativado pelo administrador da empresaExibir modal notificando o bloqueio da conta
404 Not FoundCOMPANY_USER_NOT_FOUNDE-mail autenticado no Firebase não existe em company_usersExibir mensagem de erro de provisionamento cadastral