Pular para o conteúdo principal

Autenticação e Onboarding do Motorista (App Mobile)

Pilar: 02 — Funcionalidades Core / App Mobile
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/api/mobile/auth.py, app/core/security.py), gatein-app (src/screens/Welcome, src/screens/Login, src/screens/register-screens)

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

O sistema de Autenticação e Onboarding do Motorista no ecossistema Gatein foi projetado para proporcionar uma experiência fluida de cadastro progressivo e acesso seguro baseado no CPF (tax_id). A arquitetura combina validação de número de telefone via OTP (Redis), verificação de CNH contra o cadastro prévio de transportadoras/terminais, vinculação de dispositivo confiável (Device Fingerprinting) e suporte especial a senhas de homologação/staging para simulação operacional.

1.1 Diagrama de Sequência de Onboarding e Autenticação​

flowchart TD
    A[Início App Mobile] --> B[POST /mobile/auth/check-status]
    B -->|register_step: new| C[Formulário: Nome & Telefone]
    C --> D[POST /mobile/auth/otp/send]
    D --> E[POST /mobile/auth/otp/verify]
    E --> F[POST /mobile/auth/driver-license/validate]
    F --> G[POST /mobile/auth/register - Cria Senha]
    G --> H[Recebe JWT + Registra FCM Token]
    
    B -->|register_step: registered| I[Tela de Login: CPF + Senha + Device]
    I --> J[POST /mobile/auth/login]
    J -->|Sucesso| H
    J -->|Erro: DEVICE_NOT_VALIDATED| K[Validação CNH para Troca de Aparelho]
    K --> F
    
    B -->|register_step: driver_license| F

2. Estruturas de Dados e Schemas Explícitos​

2.1 Tabela de Registros Temporários (register_requests)​

Utilizada para armazenar o estado do onboarding em andamento antes da criação física da conta na tabela users:

ColunaTipo SQLConstraintsDescrição / Regra
idUUIDPRIMARY KEY, Default gen_random_uuid()Identificador único interno
tax_idVARCHAR(14)UNIQUE, NOT NULLCPF limpo (11 dígitos)
nameVARCHAR(255)NULLABLENome completo informado na etapa de OTP
phoneVARCHAR(20)NULLABLETelefone validado via OTP
driver_licenseVARCHAR(20)NULLABLENúmero da CNH validado
register_stepVARCHAR(32)NOT NULL, Default 'new'Etapa atual (new, driver_license, password)
trusted_deviceVARCHAR(255)NULLABLEFingerprint do dispositivo validado
created_atTIMESTAMPTZNOT NULL, Default now()Timestamp de criação

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

Check Status (POST /mobile/auth/check-status):​

  • Request: { "tax_id": "12345678901" }
  • Response:
{
  "success": true,
  "data": {
    "user": {
      "register_step": "registered"
    }
  }
}

OTP Send (POST /mobile/auth/otp/send):​

  • Request: { "tax_id": "12345678901", "phone": "+5511999998888" }

OTP Verify (POST /mobile/auth/otp/verify):​

  • Request:
{
  "tax_id": "12345678901",
  "phone": "+5511999998888",
  "name": "Roberto Silva Santos",
  "code": "4829"
}

Login Mobile (POST /mobile/auth/login):​

  • Request:
{
  "tax_id": "12345678901",
  "password": "SenhaSegura123!",
  "device": "FINGERPRINT_UUID_APARELHO"
}
  • Response (com localização de staging):
{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "tax_id": "12345678901",
      "name": "Roberto Silva Santos",
      "phone": "+5511999998888",
      "email": "roberto@transportes.com.br",
      "company_location": {
        "geofence": {
          "type": "circle",
          "center": { "lat": -23.5505, "lng": -46.6333 },
          "radius": 500
        },
        "lat": -23.5505,
        "lng": -46.6333
      }
    }
  }
}

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

RN-AUT-001: Máquina de Estados de Onboarding (register_step)​

O status de cadastro do motorista evolui através dos seguintes valores no campo register_step:

  1. new: Motorista não possui cadastro físico em users nem em register_requests.
  2. phone_validation: Formulário inicial preenchido; aguardando submissão de OTP.
  3. driver_license: Telefone validado via OTP; aguardando submissão e validação da CNH.
  4. password: CNH validada contra o cadastro de motoristas; aguardando criação da senha.
  5. registered: Conta ativa criada na tabela users. Redireciona diretamente para a tela de Login com Senha.

RN-AUT-002: Armazenamento de OTP no Redis com TTL de 300s​

O código de verificação numérico de 4 dígitos é gerado aleatoriamente (random.randint(1000, 9999)) e armazenado no Redis com a chave otp:{tax_id} e tempo de expiração de 300 segundos (5 minutos). O valor gravado é um JSON contendo {"code": code, "phone": phone}.

RN-AUT-003: Verificação de Dispositivo Confiável (Device Fingerprinting)​

Ao efetuar login (POST /mobile/auth/login), o servidor compara o parâmetro device enviado pelo app com o campo user.validated_device:

  • Se forem iguais, o login é autorizado normalmente.
  • Se forem diferentes e a conta não estiver usando senha de homologação, o servidor rejeita a autenticação com HTTP 400 (DEVICE_NOT_VALIDATED). O motorista é instruído a validar sua CNH para autorizar a troca de aparelho.

RN-AUT-004: Troca de Dispositivo por Validação de CNH​

Quando o login é bloqueado por DEVICE_NOT_VALIDATED, o app direciona o motorista para a tela de confirmação de CNH enviando from_login = True em POST /mobile/auth/driver-license/validate. Ao validar com sucesso, o campo user.validated_device é atualizado para o novo fingerprint.

RN-AUT-005: Senha de Homologação / Staging (staging_passwords)​

Em ambientes onde settings.should_use_staging_logic == True, se a validação da senha principal falhar, o backend busca a senha informada na tabela staging_passwords:

  • Se encontrar uma correspondência válida:
    1. Concede o acesso (password_valid = True).
    2. Bypassa a restrição de dispositivo (user.validated_device != device).
    3. Injeta a geofence e coordenadas do terminal associado em company_location para permitir testes de check-in e Fake GPS.

RN-AUT-006: Registro Mandatório de FCM Token Pós-Login​

Logo após o recebimento do token JWT, o aplicativo mobile deve obrigatoriamente chamar o endpoint POST /mobile/auth/register-fcm-token informando o FCM Push Token do dispositivo. O token é persistido em user.fcm_token para envio de notificações transacionais de pátio.

RN-AUT-007: Hash de Senha de Alta Segurança​

Senhas de motoristas são criptografadas utilizando bcrypt / hash_secret() antes da gravação no banco de dados. Nunca são armazenadas senhas em texto plano.

4. Detalhamento de Endpoints​

4.1 POST /mobile/auth/check-status​

Determina a etapa de onboarding ou direciona para login.

4.2 POST /mobile/auth/otp/send​

Gera o OTP no Redis e dispara SMS (ou exibe nos logs do servidor em modo DEV).

4.3 POST /mobile/auth/otp/verify​

Valida o OTP e atualiza register_requests para register_step = "driver_license".

4.4 POST /mobile/auth/driver-license/validate​

Valida a CNH contra a tabela drivers. Se from_login = true, autoriza a troca de aparelho.

4.5 POST /mobile/auth/register​

Cria a entrada definitiva na tabela users, remove o registro temporário de register_requests e emite o token JWT.

4.6 POST /mobile/auth/login​

Autentica o motorista via CPF + Senha + Device Fingerprint.

4.7 POST /mobile/auth/register-fcm-token​

Associa o token do Firebase Cloud Messaging ao motorista autenticado.

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

Código HTTPCódigo de ErroCausa RaizSolução / Ação no Mobile
400 Bad RequestOTP_EXPIREDCódigo OTP não encontrado no Redis (TTL > 300s)Solicitar novo código
400 Bad RequestPHONE_VALIDATION_CODE_INVALIDCódigo OTP digitado não confereExibir erro de código inválido
400 Bad RequestTAX_ID_AND_PHONE_MISMATCHTelefone divergente do informado no envioReiniciar etapa de envio
400 Bad RequestDRIVER_LICENSE_PENDING_VALIDATIONCNH não encontrada no cadastro prévio de motoristasInstruir motorista a contatar o terminal
400 Bad RequestDEVICE_NOT_VALIDATEDTentativa de login em novo aparelho sem autorizaçãoRedirecionar para validação de CNH
401 UnauthorizedINVALID_CREDENTIALSCPF ou Senha incorretosExibir erro de credenciais