Mapeamento de Banco de Dados — companies
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/web/auth.py,app/api/admin/system.py)
1. Propósito da Tabela companies
A tabela companies é a entidade central multi-tenant do ecossistema Gatein. Ela armazena o cadastro básico de todas as empresas clientes (Terminais Marítimos/Retroportuários e Empresas Transportadoras de Carga). Atua como tabela pai para a herança polimórfica das tabelas terminals e trucking_companies.
2. Atributos Físicos da Tabela companies
| Coluna | Tipo SQL | Constraints | Descrição / Regra |
|---|---|---|---|
id | BigInteger | PRIMARY KEY, autoincrement=True | Chave primária física interna do banco |
type | VARCHAR(20) | NOT NULL, Discriminador Polimórfico | 'terminal' ou 'trucking_company' |
username | VARCHAR(50) | NOT NULL, UNIQUE | Identificador amigável de login/tenant |
name | VARCHAR(100) | NOT NULL | Razão Social ou Nome Fantasia principal |
branch_name | VARCHAR(100) | NULLABLE | Nome da Filial/Unidade (ex: "Terminal Macaé") |
unit_code | VARCHAR(50) | NULLABLE, INDEX | Código interno de unidade (ex: "MAC-01") |
tax_id | VARCHAR(20) | NOT NULL, UNIQUE | CNPJ da empresa (apenas números) |
phone | VARCHAR(20) | NOT NULL | Telefone principal de contato |
email | VARCHAR(100) | NOT NULL | E-mail corporativo principal |
api_key_hash | VARCHAR(255) | NULLABLE | Hash bcrypt da API Key Primária |
api_key_prefix | VARCHAR(50) | NULLABLE, UNIQUE, INDEX | Prefixo de 8 caracteres da API Key Primária |
api_key_secondary_hash | VARCHAR(255) | NULLABLE | Hash bcrypt da API Key Secundária |
api_key_secondary_prefix | VARCHAR(50) | NULLABLE, UNIQUE, INDEX | Prefixo de 8 caracteres da API Key Secundária |
config | JSONB | Default {} | Configurações customizadas da empresa (módulos ativos, URLs de formulários de segurança, etc.) |
address_street | VARCHAR(150) | NULLABLE | Logradouro da empresa |
address_number | VARCHAR(20) | NULLABLE | Número do endereço |
address_city | VARCHAR(100) | NULLABLE | Cidade |
address_state | VARCHAR(50) | NULLABLE | Estado (UF) |
address_country | VARCHAR(50) | NULLABLE | País |
address_zip | VARCHAR(20) | NULLABLE | CEP |
address_lat | FLOAT | NULLABLE | Latitude das instalações físicas |
address_lng | FLOAT | NULLABLE | Longitude das instalações físicas |
is_active | BOOLEAN | NOT NULL, Default true, INDEX | Flag de exclusão lógica/desativação de tenant |
created_at | TIMESTAMPTZ | NOT NULL, Default now() | Data de cadastro |
updated_at | TIMESTAMPTZ | NOT NULL, Default now() | Data de atualização |
3. Estrutura Polimórfica: terminals e trucking_companies
3.1 Tabela terminals (Herança de companies)
Armazena dados específicos para empresas do tipo terminal:
id:BigInteger,PRIMARY KEY,FOREIGN KEY (companies.id)geofence:JSONBcontendo o polígono/raio da zona virtual de check-in remoto.use_remote_checkin:Boolean, defaultFalse(habilita o check-in por GPS no app mobile).appointment_layouts/ticket_layouts:JSONBde configurações.
3.2 Tabela trucking_companies (Herança de companies)
Armazena dados específicos para transportadoras:
id:BigInteger,PRIMARY KEY,FOREIGN KEY (companies.id)trip_layouts:JSONBcontendo os templates de card de viagens.
4. Regras de Negócio de Empresa (RN-CO-XXX)
RN-CO-001: Unicidade de CNPJ e Username
Não podem existir duas empresas cadastradas com o mesmo tax_id (CNPJ) ou username. O banco de dados aplica UniqueConstraint em ambas as colunas.
RN-CO-002: Efeito Cascata da Desativação (is_active = False)
Se o campo companies.is_active for alterado para False, todos os operadores (CompanyUser), agendamentos ativos e chaves de API vinculados àquela empresa são automaticamente bloqueados nos middlewares de autorização do backend.