Pular para o conteúdo principal

Ambientes de Execução e Flags de Configuração

Pilar: 01 — Arquitetura, Stack e Segurança
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (config.py, app/api/mobile/auth.py, app/api/admin/system.py), gatein-app (.env), gatein-web (.env)

1. Visão Geral dos Ambientes​

O ecossistema Gatein opera sob 4 ambientes de execução rigorosamente isolados: development, development-staging, homologation e production. A alternância do ambiente modifica o comportamento de validações de segurança, GPS fake, emissão de notificações push, logs de auditoria e bypass de senha OTP.

graph TD
    DEV[development<br/>Debug Local, GPS Fake, Mocks] --> STG[development-staging<br/>Testes Conectados a Staging]
    STG --> HOM[homologation<br/>Testes de Aceitação de Cliente / Fake Driver / StagingPassword]
    HOM --> PROD[production<br/>Ambiente Real de Operação / Validação Estrita / Sem Bypass]

2. Matriz de Comportamentos por Ambiente​

Funcionalidade / Guarddevelopmentdevelopment-staginghomologationproduction
Bypass de Senha OTP (StagingPassword)✅ Ativo✅ Ativo✅ Ativo❌ BLOQUEADO
Criação de Motoristas Fake (CreateFakeDriver)✅ Ativo✅ Ativo✅ Ativo❌ BLOQUEADO
Simulação de Localização GPS (Mock Location)✅ Permitido✅ Permitido✅ Permitido❌ BLOQUEADO (Strict Check)
Injeção de Localização de Teste no Login✅ Ativo✅ Ativo✅ Ativo❌ Inativo
Notificações Push FCM Reais⚠️ Opcional✅ Ativo✅ Ativo✅ Ativo
Log Level no ServidorDEBUGDEBUGINFOWARNING / ERROR
Validação Estrita de Dispositivo (validated_device)❌ Exonerado em StagingPass❌ Exonerado em StagingPass❌ Exonerado em StagingPass✅ Obrigatório

3. Variáveis de Ambiente Críticas (config.py)​

No servidor (gatein-server), a classe Settings em config.py resolve dinamicamente as flags de comportamento a partir das variáveis de ambiente:

class Settings(BaseSettings):
    ENVIRONMENT: str = "development"  # development, development-staging, homologation, production
    DATABASE_URL: str
    REDIS_URL: str
    JWT_SECRET_KEY: str
    JWT_EXPIRATION_DELTA_MOBILE: int = 2592000  # 30 dias em segundos

    @property
    def is_development(self) -> bool:
        return self.ENVIRONMENT.lower() in ("development", "dev")

    @property
    def should_use_staging_logic(self) -> bool:
        return self.ENVIRONMENT.lower() in ("development", "dev", "development-staging", "staging", "homologation")

    @property
    def is_production(self) -> bool:
        return self.ENVIRONMENT.lower() in ("production", "prod")

4. Lógica de Bypass em Homologação e Staging​

4.1 Injeção de Localização de Teste (get_test_company_location)​

Quando settings.should_use_staging_logic == True, no retorno da rota de login/registro mobile (/mobile/auth/login), o backend busca dinamicamente o terminal correspondente à senha de staging utilizada ou o primeiro terminal disponível no banco, injetando as coordenadas lat, lng e o polígono geofence no objeto company_location:

{
  "user": {
    "name": "Motorista Teste Staging",
    "tax_id": "12345678901",
    "company_location": {
      "lat": -23.9612,
      "lng": -46.3021,
      "geofence": {
        "type": "Polygon",
        "coordinates": [[[-46.303, -23.962], [-46.301, -23.962], [-46.301, -23.960], [-46.303, -23.960], [-46.303, -23.962]]]
      }
    }
  }
}

5. Regras de Negócio de Segurança de Ambiente (RN-ENV-XXX)​

RN-ENV-001: Trava de Segurança Contra Execução de Staging em Produção​

Se ENVIRONMENT == 'production', qualquer tentativa de invocar endpoints decorados ou condicionados pela flag should_use_staging_logic (como rotas de criação de motorista fake ou alteração de senha de staging) lançará erro HTTP 403 (FEATURE_DISABLED_IN_PRODUCTION).

RN-ENV-002: Verificação Anti-Mock Location em Produção​

No aplicativo mobile, se ENVIRONMENT == 'production', a coleta de coordenadas GPS no envio do Check-in inspecionará o atributo isFromMockProvider do sistema operacional. Se detectado uso de GPS Fake em produção, a requisição é rejeitada com HTTP 400 (MOCK_LOCATION_FORBIDDEN).

RN-ENV-003: Isolamento de Notificações por Projeto Firebase​

Cada ambiente deve obrigatoriamente utilizar credenciais separadas do serviceAccountKey.json apontando para projetos Firebase isolados (ex: gatein-staging vs gatein-prod), prevenindo disparos de mensagens de teste para motoristas reais em trânsito.