Ambiente de Homologação e Ferramentas de Teste (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/StagingPassword, src/screens/admin/CreateFakeDriver), gatein-server (app/api/admin/system.py, app/models.py), gatein-app (Simulação de Autenticação e Geofence em Homologação)

---

1. Visão Geral e Arquitetura de Simulação Operacional

O módulo de Homologação e Ferramentas de Teste provê recursos para que equipes de implantação, homologação e clientes em fase de testes validem a jornada completa de pátio (criação de agendamentos, simulação de geofence, disparos de check-in e validação de tickets digitais) sem depender de:

1. Emissão de SMS de produção (OTP).
2. Validação presencial de CNH junto aos órgãos de trânsito.
3. Restrições físicas de posicionamento GPS real.

1.1 Diagrama do Fluxo de Testes com Staging Password e Motorista Fake

sequenceDiagram
    autonumber
    actor A as Admin / Q.A. (Web App)
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL
    actor M as Motorista de Teste (App Mobile)

    A->>S: POST /admin/system/staging-passwords (company_id, password)
    S->>DB: Faz hash da senha e salva em staging_passwords
    A->>S: POST /admin/system/create-fake-driver (tax_id, name, cnh_number)
    S->>DB: Insere em drivers com flag is_fake = True
    S-->>A: Motorista Fake pronto para homologação!
    
    note over M, S: Autenticação Mobile com Senha de Staging
    M->>S: POST /mobile/auth/login (CPF fake + Senha de Staging)
    S->>DB: Valida senha na tabela staging_passwords
    S->>S: Bypassa trava de dispositivo (validated_device)
    S->>DB: Fetch geofence e coordenadas do Terminal associado
    S-->>M: Retorna JWT + objeto company_location (permite Fake GPS e Check-in no app)

---

2. Estruturas de Dados e Schemas Explícitos

2.1 Modelo Relacional no Banco de Dados (staging_passwords)

Coluna	Tipo SQL	Constraints	Descrição / Regra
id	UUID	PRIMARY KEY, Default gen_random_uuid()	Identificador único interno
company_id	UUID	FOREIGN KEY (companies.id), NOT NULL	Terminal detentor da senha mestre de teste
password_hash	VARCHAR(255)	NOT NULL	Hash seguro bcrypt da senha de homologação
created_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp de criação da credencial

2.2 Schemas de Requisição e Resposta

Payload de Criação de Senha de Staging (CreateStagingPasswordPayload):

{
  "company_id": "c9x8v7b6",
  "password": "SenhaHomologacao2026!"
}

Payload de Criação de Motorista Fake (CreateFakeDriverPayload):

{
  "tax_id": "98765432100",
  "name": "Motorista Fake Homologação",
  "phone": "+5511999990000",
  "cnh_number": "12345678900",
  "company_id": "c9x8v7b6"
}

---

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

RN-HOM-001: Trava de Segurança Contra Execução em Produção

Todas as rotas do módulo de homologação (/admin/system/staging-passwords e /admin/system/create-fake-driver) inspecionam incondicionalmente a variável global de ambiente settings.should_use_staging_logic:

• Se should_use_staging_logic == False (ambiente de production), o servidor rejeita imediatamente qualquer chamada com HTTP 403 (STAGING_DISABLED_IN_PRODUCTION).

RN-HOM-002: Isolamento de Senhas Mestre por Terminal

Uma StagingPassword cadastrada para o Terminal A não autoriza o login em agendamentos ou operações do Terminal B. O backend valida estritamente a associação entre o company_id da senha de staging e a empresa responsável pela operação.

RN-HOM-003: Identificação e Expulso de Dados Fake (is_fake = True)

Todo motorista criado pela ferramenta de teste recebe a flag booleana drivers.is_fake = True. Essa marcação permite que rotinas automáticas de limpeza (data cleanup jobs) expurguem registros fictícios sem risco de deletar dados reais de motoristas cadastrados em produção.

RN-HOM-004: Injeção de Coordenadas de Teste (company_location)

Quando um motorista autentica utilizando uma senha de staging válida, o retorno do endpoint de login injeta um nó especial chamado company_location no JSON da resposta. O aplicativo mobile utiliza esse nó para inicializar o mapa diretamente sobre as coordenadas do terminal de teste, facilitando a execução do check-in simulado.

---

4. Detalhamento de Endpoints (app/api/admin/system.py)

4.1 POST /admin/system/staging-passwords

Cadastra uma nova senha mestre de teste para um terminal específico.

4.2 GET /admin/system/staging-passwords/{company_id}

Lista as senhas de staging ativas para o terminal informado.

4.3 POST /admin/system/create-fake-driver

Cria um motorista fictício na tabela drivers (com is_fake = True) ignorando checagens externas.

---

5. Regras de Segurança e Tabela de Erros

Código HTTP	Código Interno	Causa Raiz	Ação no Web App
403 Forbidden	STAGING_DISABLED_IN_PRODUCTION	Tentativa de acionar rotas de teste no ambiente de Produção	Ocultar aba de Homologação no menu do Web App
400 Bad Request	INVALID_CPF_FORMAT	Dígitos verificadores do CPF do motorista fake são inválidos	Informar CPF válido (Módulo 11)
404 Not Found	COMPANY_NOT_FOUND	company_id informado para a senha de staging não existe	Selecionar um terminal válido na lista