Mapeamento de Banco de Dados — trips

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/public/trips.py, app/api/mobile/activities.py), gatein-app (src/screens/Activity)

---

1. Visão Geral da Modelagem de Viagens (trips)

A tabela trips no PostgreSQL armazena a entidade física de Viagem de Frete atribuída por uma Empresa Transportadora (trucking_company_id) a um motorista (driver_id). A viagem engloba o trecho logístico completo entre um ponto de origem e um ponto de destino, contendo dados de geolocalização estruturados, dados customizados de carga e prazos operacionais.

---

2. Atributos Físicos da Tabela trips

Coluna	Tipo SQL	Constraints	Descrição / Regra de Negócio
id	UUID	PRIMARY KEY, Default gen_random_uuid()	Identificador único interno no banco de dados
trucking_company_id	UUID	FOREIGN KEY (companies.id), NOT NULL, INDEX	Empresa transportadora detentora da viagem (Tenant Guard)
driver_id	UUID	FOREIGN KEY (drivers.id), NOT NULL, INDEX	Motorista escalado para a viagem
ref	VARCHAR(64)	NOT NULL, INDEX	Referência única externa do frete/manifesto (ex: MANIFESTO-2026-8812)
layout_ref	VARCHAR(64)	NULLABLE	Referência do layout dinâmico JSON de renderização no app
license_plate	VARCHAR(10)	NULLABLE	Placa do veículo associado (Cavalo/Carreta)
status	VARCHAR(32)	NOT NULL, Default 'PLANNED', INDEX	Estado atual da viagem (ver Máquina de Estados)
summary	TEXT	NULLABLE	Descrição resumida ou observações sobre a viagem
window_start	TIMESTAMPTZ	NULLABLE	Data/hora prevista de início da viagem
window_end	TIMESTAMPTZ	NULLABLE	Data/hora prevista de término da viagem
start_tolerance	INTEGER	NOT NULL, Default 0	Tolerância de início em minutos
end_tolerance	INTEGER	NOT NULL, Default 0	Tolerância de término em minutos
custom_data	JSONB	NULLABLE	Chave-valor arbitrária para preenchimento de campos customizados do layout
from_location	VARCHAR(255)	NULLABLE	Descrição amigável do local de partida (ex: "Terminal Retroportuário A")
to_location	VARCHAR(255)	NULLABLE	Descrição amigável do local de chegada (ex: "Armazém Geral B")
origin_street	VARCHAR(255)	NULLABLE	Logradouro de origem
origin_number	VARCHAR(32)	NULLABLE	Número do endereço de origem
origin_city	VARCHAR(128)	NULLABLE	Cidade de origem
origin_state	VARCHAR(64)	NULLABLE	Estado (UF) de origem
origin_country	VARCHAR(64)	NULLABLE	País de origem
origin_zip	VARCHAR(32)	NULLABLE	CEP de origem
origin_lat	DOUBLE PRECISION	NULLABLE	Latitude exata do ponto de origem
origin_lng	DOUBLE PRECISION	NULLABLE	Longitude exata do ponto de origem
destiny_street	VARCHAR(255)	NULLABLE	Logradouro de destino
destiny_number	VARCHAR(32)	NULLABLE	Número do endereço de destino
destiny_city	VARCHAR(128)	NULLABLE	Cidade de destino
destiny_state	VARCHAR(64)	NULLABLE	Estado (UF) de destino
destiny_country	VARCHAR(64)	NULLABLE	País de destino
destiny_zip	VARCHAR(32)	NULLABLE	CEP de destino
destiny_lat	DOUBLE PRECISION	NULLABLE	Latitude exata do ponto de destino
destiny_lng	DOUBLE PRECISION	NULLABLE	Longitude exata do ponto de destino
created_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp de criação
updated_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp da última modificação

---

3. Máquina de Estados de Viagem

Estado (status)	Descrição Operacional	Transições Permitidas
PLANNED	Viagem criada e agendada no sistema, aguardando horário	-> ACTIVE, CANCELLED, DELETED
ACTIVE	Viagem liberada para o motorista no aplicativo mobile	-> IN_PROGRESS, PAUSED, CANCELLED
IN_PROGRESS	Motorista iniciou o deslocamento/frete no aplicativo	-> PAUSED, COMPLETED, CANCELLED
PAUSED	Viagem interrompida temporariamente por descanso ou parada	-> IN_PROGRESS, CANCELLED
COMPLETED	Viagem concluída e entregue no destino	Estado Final (Imutável)
CANCELLED	Viagem cancelada pela transportadora	Estado Final (Imutável)
DELETED	Soft-delete lógico (ocultado de todas as APIs)	Estado Final (Imutável)

---

4. Índices e Regras de Performance

• idx_trips_company_ref: Unique Index composto (trucking_company_id, ref) impedindo duplicidade de código de referência por transportadora.
• idx_trips_driver_status: Índice composto (driver_id, status) otimizado para a rota GET /mobile/activities do aplicativo.
• idx_trips_window_start: Índice em window_start para acelerar varreduras de relatórios de frete.

---

5. Diagrama de Entidades Relacionadas (ER)

erDiagram
    COMPANIES ||--o{ TRIPS : "contrata/transporta"
    DRIVERS ||--o{ TRIPS : "executa"
    TRIPS ||--o{ TRIP_LOGS : "gera histórico"
    TRIP_LAYOUTS ||--o{ TRIPS : "formata card"

    TRIPS {
        uuid id PK
        uuid trucking_company_id FK
        uuid driver_id FK
        string ref "Único por Empresa"
        string layout_ref
        string status
        double origin_lat
        double origin_lng
        double destiny_lat
        double destiny_lng
        jsonb custom_data
    }