Atualização Cadastral e Perfil (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/api/web/uploads.py), gatein-app (src/screens/Profile, src/screens/EditProfile)

---

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

O módulo de Atualização Cadastral permite que o motorista gerencie seus dados pessoais, foto de perfil, e-mail de contato, CNH e credenciais de telefone diretamente no aplicativo mobile. Como a identidade do motorista é a chave operacional para liberação em pátios e checagem de segurança, determinados campos (como CPF) possuem imutabilidade rígida, enquanto outros (como telefone) exigem re-autenticação via OTP (One-Time Password).

1.1 Diagrama de Sequência de Atualização de Dados e Troca de Telefone

sequenceDiagram
    autonumber
    actor M as Motorista / App Mobile
    participant S as Gatein Server (FastAPI)
    participant R as Redis (OTP Cache)
    participant ST as Cloud Storage (S3/Firebase)
    participant DB as PostgreSQL

    rect rgb(240, 248, 255)
    note over M, DB: Fluxo 1: Upload de Foto de Perfil
    M->>S: POST /web/uploads (Multipart File Binary)
    S->>S: Valida MIME Type (JPEG/PNG) + Tamanho (< 5MB)
    S->>ST: Envia arquivo comprimido para Bucket
    ST-->>S: Retorna URL Pública da Imagem
    S->>DB: Atualiza User.photo_url e Driver.photo_url
    S-->>M: HTTP 200 (Retorna nova foto de perfil)
    end

    rect rgb(255, 250, 240)
    note over M, DB: Fluxo 2: Troca Segura de Telefone (Re-OTP)
    M->>S: POST /mobile/auth/profile/phone/send (novo telefone)
    S->>R: Grava OTP (4 dígitos, TTL: 300s, key: otp_change:{tax_id})
    S-->>M: HTTP 200 (OTP enviado via SMS/Push)
    M->>S: POST /mobile/auth/profile/phone/verify (código OTP)
    S->>R: Checa código no Redis
    S->>DB: Atualiza User.phone e RegisterRequest.phone
    S-->>M: HTTP 200 (Telefone atualizado com sucesso)
    end

---

2. Estruturas de Dados e Schemas Explícitos

2.1 Matriz de Editabilidade e Restrições de Campos

Campo	Editable no Mobile	Tipo / Formato	Constraint / Regra de Negócio
tax_id (CPF)	❌ Imutável	VARCHAR(14)	Chave primária de vínculo do motorista. Imutável no app.
name	✅ Sim	VARCHAR(255)	Mínimo de 3 caracteres, apenas letras e espaços.
phone	⚠️ Requer OTP	VARCHAR(20)	Exige confirmação por código OTP enviado ao novo número.
email	✅ Sim	VARCHAR(255)	Validação por expressão regular RFC 5322; deve ser único na tabela users.
driver_license (CNH)	⚠️ Validado	VARCHAR(20)	Somente dígitos (11 caracteres). Validado contra a tabela drivers.
cnh_expiration	⚠️ Validado	DATE	Data futura. Não pode ser anterior à data atual do servidor.
photo_url	✅ Sim	VARCHAR(512)	Upload para S3/Firebase Storage. Máximo 5MB (JPEG, PNG, WEBP).

2.2 Schemas de Requisição e Resposta

Schema de Envio de Novo Telefone (ProfilePhoneSendRequest):

{
  "new_phone": "+5511999998888"
}

Schema de Verificação de Troca de Telefone (ProfilePhoneVerifyRequest):

{
  "new_phone": "+5511999998888",
  "code": "4829"
}

Schema de Resposta de Perfil Atualizado (UserProfileResponse):

{
  "success": true,
  "data": {
    "user": {
      "tax_id": "12345678901",
      "name": "Roberto Silva Santos",
      "phone": "+5511999998888",
      "email": "roberto.silva@transportes.com.br",
      "photo_url": "https://cdn.gatein.app/profiles/12345678901_avatar.jpg",
      "driver_license": "12345678900",
      "cnh_expiration": "2028-12-31"
    }
  }
}

---

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

RN-CAD-001: Imutabilidade Absoluta do CPF

O campo tax_id (CPF) é a âncora de identidade do motorista no ecossistema Gatein. Qualquer tentativa de alteração do CPF via payload de atualização cadastral deve ser sumariamente ignorada ou rejeitada pelo servidor com HTTP 400 (CPF_IS_IMMUTABLE).

RN-CAD-002: Troca de Telefone Protegida por Re-autenticação OTP

O número de telefone não pode ser editado via submissão simples. A alteração exige a execução em dois passos:

1. Envio do código de 4 dígitos para o novo telefone (POST /mobile/auth/profile/phone/send).
2. Validação do código armazenado no Redis (key: otp_profile:{tax_id}) com TTL de 300 segundos.

RN-CAD-003: Unicidade e Validação de E-mail

O e-mail cadastrado deve ser único em toda a tabela users. Se o motorista tentar associar um e-mail que já pertence a outra conta física, o servidor retornará HTTP 400 com o código interno EMAIL_ALREADY_IN_USE.

RN-CAD-004: Consistência e Validade Futura da CNH

Ao atualizar o número ou a data de vencimento da CNH:

• O número da CNH deve conter exatamente 11 dígitos numéricos válidos.
• A data de vencimento (cnh_expiration) deve satisfazer a condição cnh_expiration >= CURRENT_DATE. Se a CNH estiver vencida, a submissão é bloqueada.

RN-CAD-005: Regra de Redimensionamento e Upload de Foto

Fotos de perfil submetidas pelo app mobile devem ser processadas antes ou durante o upload:

• Resolução máxima aceita: 1024x1024 pixels.
• Formatos MIME suportados: image/jpeg, image/png, image/webp.
• Limite de tamanho de arquivo: 5.242.880 bytes (5 MB).
• A URL gerada no Storage é atribuída simultaneamente ao registro do User e do Driver associado.

RN-CAD-006: Atualização Otimista e Rollback no Mobile App

O aplicativo mobile utiliza atualização otimista (Zustand state / React Query) para refletir alterações de nome e foto instantaneamente na interface. Em caso de falha de rede ou rejeição pelo servidor (ex: erro 422/400), o estado local é revertido automaticamente (rollback) e um alert/toast explicativo é exibido.

---

4. Detalhamento de Endpoints

4.1 POST /mobile/auth/profile/phone/send

Solicita código de verificação OTP para alteração de número de telefone.

4.2 POST /mobile/auth/profile/phone/verify

Valida o código de verificação e confirma a troca do telefone no banco de dados.

4.3 POST /web/uploads (ou endpoint mobile de upload de mídia)

Recebe multipart/form-data com o arquivo de imagem do avatar, envia para o bucket de armazenamento e retorna a URL pública gerada.

---

5. Regras de Segurança e Tratamento de Erros

Código HTTP	Código Interno	Causa Raiz	Ação no App Mobile
400 Bad Request	CPF_IS_IMMUTABLE	Tentativa de sobrescrever o CPF autenticado	Bloquear campo na UI
400 Bad Request	EMAIL_ALREADY_IN_USE	E-mail informado pertence a outro usuário	Solicitar outro e-mail válido
400 Bad Request	INVALID_CNH_EXPIRATION	Data de vencimento da CNH está no passado	Exibir aviso de CNH expirada
400 Bad Request	OTP_EXPIRED	Código de validação do telefone expirou	Solicitar novo envio de OTP
413 Payload Too Large	FILE_TOO_LARGE	Foto de perfil excede 5MB	Notificar o motorista para escolher imagem menor