Configuração de Serviços e Domínios (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/Services, src/screens/admin/AllowedDomains), gatein-server (app/api/web/services.py, app/models.py), gatein-app (src/screens/ServiceWebView)

---

1. Visão Geral e Integração com o App Mobile

O módulo de Configuração de Serviços e Domínios permite que Administradores de Terminais configurem atalhos e portais web que serão disponibilizados no aplicativo mobile dos motoristas.

Para impedir ataques de phishing e navegações maliciosas em ambientes terceiros dentro do aplicativo mobile, toda URL cadastrada passa por uma validação estrita contra a Whitelist de Domínios Permitidos (allowed_domains) configurada pela empresa no Web App.

1.1 Diagrama de Sequência de Cadastro e Consumo Mobile

sequenceDiagram
    autonumber
    actor A as Admin da Empresa (Web App)
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL
    actor M as Motorista (App Mobile)

    A->>S: POST /web/services/allowed-domains (domain: "terminal.com.br")
    S->>DB: Registra domínio na tabela allowed_domains
    A->>S: POST /web/services (title, url: "https://patios.terminal.com.br/triagem", type: "webview")
    S->>DB: Extrai host da URL ("patios.terminal.com.br")
    S->>DB: Valida se host pertence a allowed_domains ativos
    S->>DB: Insere em company_services (is_active = True)
    S-->>A: HTTP 201 (Serviço criado com sucesso)
    
    M->>S: GET /mobile/companies/{company_id}/services
    S->>DB: Retorna apenas serviços ativos com domínios autorizados
    S-->>M: Renderiza os cards de serviços no aplicativo

---

2. Estruturas de Dados e Schemas Explícitos

2.1 Modelo Relacional no Banco de Dados (company_services e allowed_domains)

Tabela company_services:

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	Empresa proprietária
domain_id	UUID	FOREIGN KEY (allowed_domains.id), NOT NULL	Domínio autorizado vinculado
title	VARCHAR(255)	NOT NULL	Nome do serviço exibido no app mobile
description	TEXT	NULLABLE	Descrição opcional do serviço
url	VARCHAR(512)	NOT NULL	URL completa de destino HTTP/HTTPS
icon_url	VARCHAR(512)	NULLABLE	URL do ícone customizado
is_active	BOOLEAN	NOT NULL, Default True	Status de exibição no app
order	INTEGER	NOT NULL, Default 0	Posição de ordenação no card do mobile

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

Payload de Criação de Serviço (CreateServicePayload):

{
  "title": "Fila de Triagem em Tempo Real",
  "description": "Acompanhe a sua posição na fila de espera do pátio",
  "url": "https://patios.terminal.com.br/triagem",
  "icon_url": "https://cdn.gatein.app/icons/queue.png",
  "is_active": true,
  "order": 1
}

Payload de Domínio Permitido (CreateAllowedDomainPayload):

{
  "domain": "terminal.com.br"
}

---

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

RN-SVC-WEB-001: Validação Estrita de Whitelist de Domínios

Ao cadastrar ou atualizar um serviço via POST /web/services ou PUT /web/services/{id}, o servidor parseia a URL fornecida, extrai o hostname (FQDN) e verifica se ele coincide com um domínio ativo na tabela allowed_domains daquela empresa:

• Suporta domínios exatos (terminal.com.br) e subdomínios (patios.terminal.com.br).
• Se a URL pertencer a um domínio não cadastrado ou inativo, o servidor lança HTTP 400 (DOMAIN_NOT_ALLOWED).

RN-SVC-WEB-002: URL Obrigatória para Serviços do Tipo WebView

Serviços configurados com o modo de exibição type = "webview" exigem obrigatoriamente uma URL no formato válido https://. URLs com protocolo inseguro http:// são rejeitadas em ambiente de produção (HTTP 400 HTTPS_REQUIRED).

RN-SVC-WEB-003: Reordenação Automática de Sequência (order)

Se o Administrador alterar o campo order de um serviço para um valor que já existe em outro registro da empresa, o backend reordena automaticamente os demais serviços ativos da empresa para evitar colisões no aplicativo mobile.

RN-SVC-WEB-004: Impacto da Desativação de um Domínio

Se um domínio na tabela allowed_domains for marcado como is_active = False ou deletado pelo Administrador, todos os serviços associados a ele em company_services deixam instantaneamente de ser retornados pela API mobile (GET /mobile/companies/{company_id}/services).

---

4. Detalhamento de Endpoints

4.1 GET /web/services

Lista todos os serviços configurados pela empresa do administrador.

4.2 POST /web/services

Valida o domínio e cria um novo serviço para exibição mobile.

4.3 PUT /web/services/{id}

Atualiza campos de título, URL, ícone, ordem e status de ativação.

4.4 GET /web/services/allowed-domains

Lista os domínios autorizados cadastrados para a empresa.

4.5 POST /web/services/allowed-domains

Cadastra um novo domínio na whitelist da empresa.

---

5. Regras de Segurança e Tabela de Erros

Código HTTP	Código Interno	Causa Raiz	Ação no Web App
400 Bad Request	DOMAIN_NOT_ALLOWED	URL do serviço pertence a um domínio fora da whitelist	Exibir mensagem para cadastrar o domínio primeiro
400 Bad Request	INVALID_URL_FORMAT	URL malformada ou sem esquema HTTPS	Exibir erro de validação de URL
400 Bad Request	DOMAIN_ALREADY_EXISTS	Domínio já cadastrado na whitelist da empresa	Informar que o domínio já está ativo