Mapeamento de Banco de Dados — company_services e allowed_domains
Pilar: 04 — Banco de Dados / Tabelas
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados:gatein-server(app/models.py,app/api/mobile/services.py,app/api/web/services.py)
1. Visão Geral da Modelagem de Serviços Personalizados
O módulo de serviços permite que cada empresa cadastrada no ecossistema (Terminal ou Transportadora) ofereça aos seus motoristas links para utilitários externos em WebView (ex: consulta de fila de pátio, agendamento de restaurante, formulários de segurança) ou atalhos para funcionalidades nativas.
Por questões de segurança cibernética e contenção de vazamento de credenciais, toda URL de serviço cadastrada no servidor precisa estar vinculada a um domínio previamente autorizado na tabela allowed_domains.
2. Atributos Físicos da Tabela allowed_domains
| Coluna | Tipo SQL | Constraints | Descrição / Regra |
|---|---|---|---|
id | Integer | PRIMARY KEY, autoincrement=True | Identificador do domínio permitido |
domain | VARCHAR(255) | NOT NULL, UNIQUE, INDEX | FQDN do domínio permitido (ex: "terminal-santos.com.br") |
is_active | BOOLEAN | NOT NULL, Default true, INDEX | Flag de ativação do domínio |
created_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp de inclusão |
updated_at | TIMESTAMPTZ | NOT NULL, Default now() | Timestamp de modificação |
3. Atributos Físicos da Tabela company_services
| Coluna | Tipo SQL | Constraints | Descrição / Regra |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | Identificador do serviço |
company_id | BigInteger | FOREIGN KEY (companies.id), NOT NULL, INDEX | Empresa proprietária do serviço (Tenant Guard) |
domain_id | Integer | FOREIGN KEY (allowed_domains.id), NOT NULL, INDEX | Referência ao domínio autorizado |
title | VARCHAR(100) | NOT NULL | Título legível do serviço exibido na lista mobile |
description | TEXT | NULLABLE | Descrição informativa breve |
url | VARCHAR(500) | NOT NULL | URL completa do serviço (deve pertencer ao allowed_domain) |
icon_url | VARCHAR(500) | NULLABLE | URL do ícone SVG/PNG do serviço |
is_active | BOOLEAN | NOT NULL, Default true, INDEX | Flag de exibição do serviço no aplicativo |
created_at | TIMESTAMPTZ | NOT NULL, Default now() | Data de criação |
updated_at | TIMESTAMPTZ | NOT NULL, Default now() | Data de alteração |
4. Índices e Performance
idx_company_services_lookup: Índice composto(company_id, is_active)otimizado para a listagem rápida de serviços na rotaGET /mobile/services.idx_allowed_domains_lookup: Índice composto(domain, is_active)utilizado na validação pré-inserção de URLs no Web App.
5. Regras de Negócio de Segurança (RN-SVC-DB-XXX)
RN-SVC-DB-001: Validação de Domínio Autorizado (domain_id)
O backend rejeita qualquer tentativa de cadastrar ou atualizar um serviço em company_services se o domínio da url informada não corresponder exatamente ao atributo domain da tabela allowed_domains associada ao domain_id.
RN-SVC-DB-002: Injeção de Token JWT em WebViews do App
Quando o motorista toca em um serviço na lista do aplicativo mobile, o app abre o componente ServiceWebView injetando o Bearer Token do motorista no header HTTP Authorization da requisição para o domínio do terminal.