Pular para o conteúdo principal

Modelagem Conceitual e Arquitetura do Banco de Dados

Pilar: 04 — Banco de Dados e Eventos
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
SGBD: PostgreSQL 15+ (Engine SQLAlchemy Async/Sync + Alembic)
Módulos Conectados: gatein-server (app/core/database.py, app/core/active.py, app/models.py)

1. Visão Geral da Modelagem ER​

O banco de dados do Gatein foi projetado para alta escalabilidade multi-tenant, suporte a layouts dinâmicos via campos JSONB, herança polimórfica de empresas e desacoplamento entre identificadores físicos de banco (BigInteger) e identificadores externos expostos em APIs (Sqids).

erDiagram
    COMPANIES ||--o{ TERMINALS : "polimorfismo (type=terminal)"
    COMPANIES ||--o{ TRUCKING_COMPANIES : "polimorfismo (type=trucking_company)"
    COMPANIES ||--o{ COMPANIES_USERS : "possui operadores"
    COMPANIES ||--o{ COMPANY_SERVICES : "disponibiliza serviços"
    COMPANIES ||--o{ ANNOUNCEMENTS : "publica comunicados"
    
    TERMINALS ||--o{ APPOINTMENTS : "gerencia agendamentos"
    TERMINALS ||--o{ APPOINTMENTS_LAYOUTS : "possui layouts card"
    TERMINALS ||--o{ TICKETS_LAYOUTS : "possui layouts ticket"
    
    TRUCKING_COMPANIES ||--o{ TRIPS : "gerencia viagens"
    TRUCKING_COMPANIES ||--o{ TRIPS_LAYOUTS : "possui layouts viagens"
    
    DRIVERS ||--o{ USERS : "vinculado a conta de acesso"
    DRIVERS ||--o{ APPOINTMENTS : "atendido em"
    DRIVERS ||--o{ TRIPS : "executa frete"
    
    USERS ||--o{ USER_FCM_TOKENS : "possui dispositivos push (1:N)"
    
    APPOINTMENTS ||--o{ TICKETS : "gera comprovante"
    APPOINTMENTS ||--o{ APPOINTMENTS_LOGS : "registra auditoria"
    TRIPS ||--o{ TRIPS_LOGS : "registra auditoria"

2. Padrões de Herança e Mixins Globais​

2.1 Mixin de Exclusão Lógica e Ativação (ActiveModelMixin)​

Todas as tabelas do sistema herdam da classe ActiveModelMixin (app/core/active.py), que injeta obrigatoriamente a coluna is_active (Boolean, default True, index=True).

  • Nenhuma rota de cliente executa a instrução SQL DELETE FROM table.
  • A exclusão é realizada definindo is_active = False ou deleted_at = now().
  • Todas as consultas ORM padrão incluem a instrução implícita: .filter(Model.is_active == True).

2.2 Herança Polimórfica de Empresas (Company)​

A tabela base companies armazena dados cadastrais comuns de clientes. O SQLAlchemy gerencia a herança polimórfica baseada na coluna type:

  • type = 'terminal': Mapeia para a classe e tabela Terminal, que adiciona suporte a geofence, appointment_layouts e ticket_layouts.
  • type = 'trucking_company': Mapeia para a classe e tabela TruckingCompany, que adiciona suporte a trip_layouts.

3. Identificadores Primários vs. Identificadores Públicos (Sqids)​

Para prevenir ataques de varredura sequencial de URLs (enumeration attacks), o banco de dados adota uma camada dupla de identificação:

CamadaTipo de IDExemploUso Interno / Externo
Física de BancoBigInteger (64-bit autoincrement)109482Usado exclusivamente em PRIMARY KEY, FOREIGN KEY e consultas SQL internas
Camada de API / MobileSqid (String alfanumérica ofuscada)"w8x9k2m1"Retornado em todos os payloads JSON e aceito nas URLs REST públicas
# app/core/sqids.py
def encode_id(internal_id: int) -> str:
    return sqids.encode([internal_id])

def decode_id(sqid_str: str) -> int:
    decoded = sqids.decode(sqid_str)
    if not decoded:
        raise HTTPException(status_code=400, detail={"code": "INVALID_SQID"})
    return decoded[0]

4. Otimização de Busca Textual (Índices GIN Trigram)​

Para suportar busca de alto desempenho em autocompletar e filtros de nome de empresa/filial sem causar table scan, a tabela companies inclui um índice GIN Trigram com suporte a remoção de acentos (f_unaccent):

CREATE INDEX idx_company_trgm_search ON companies 
USING gin (f_unaccent(name || ' ' || COALESCE(branch_name, '')) gin_trgm_ops);

5. Estratégia de Migrações (Alembic)​

  1. Versionamento Estrito: Todo script de migração em alembic/versions/ possui um hash hexadecimal sequencial e deve implementar obrigatoriamente as funções upgrade() e downgrade().
  2. Execução de Migrações em Deploy: Em ambientes de homologação e produção, o container executa alembic upgrade head antes de iniciar os workers do Uvicorn.