Pular para o conteúdo principal

Eventos e Ciclo de Vida de Viagens (Trips)

Pilar: 04 — Banco de Dados e Eventos / Eventos
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/api/public/trips.py, app/core/firebase.py), gatein-app (src/screens/Activity)

1. Visão Geral dos Eventos de Viagem​

A gestão de viagens operadas por empresas transportadoras dispara eventos síncronos e assíncronos no servidor. Todo evento gera um registro auditável na tabela trip_logs e, quando aplicável, despacha uma notificação push FCM para o dispositivo mobile do motorista vinculado.

sequenceDiagram
    autonumber
    actor ERP as ERP / Transportador (API Key)
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL
    participant FCM as Firebase Messaging
    actor M as Motorista (Mobile App)

    ERP->>S: POST /public/trips (Ref, Driver TaxID, Layout, Origem/Destino)
    S->>DB: Auto-upsert do Driver + Insere Trip (Status: PLANNED/ACTIVE)
    S->>DB: Registra TripLog (event: TRIP_CREATED)
    S->>FCM: notify_user_by_tax_id(type: TRIP_ASSIGNED)
    FCM-->>M: Notificação Push: "Nova Viagem Atribuída!"
    M->>S: GET /mobile/activities (Carrega Viagem com Layout Dinâmico)
    M->>S: POST /mobile/activities/log-events (Visualizou / Clicou no Card)
    S->>DB: Registra TripLog (event: VIEWED / CLICKED)
    ERP->>S: POST /public/trips/update (Status: COMPLETED)
    S->>DB: Atualiza Trip + Registra TripLog (event: TRIP_UPDATED)

2. Detalhamento dos Eventos de Domínio (TripEvent)​

2.1 Evento TRIP_CREATED (trip.assigned)​

Trigger: Invocação da rota pública POST /public/trips via API Key de Transportadora ou ação manual no Web App.

Sequência de Execução:​

  1. Validação Fail-Fast de Duplicidade: Garante que o atributo ref não existe previamente para a trucking_company_id. Se existir, aborta com HTTP 409 (DUPLICATE_KEY).
  2. Validação Fail-Fast de Layout: Garante que o layout_ref informado existe na tabela trip_layouts. Se ausente, aborta com HTTP 400 (INVALID_LAYOUT_REF).
  3. Auto-Upsert de Motorista: Se o CPF (driver.tax_id) não existir no banco, cria o registro automaticamente em drivers preenchendo a CNH. Se já existir, atualiza a CNH e a data de modifcação.
  4. Inserção da Viagem: Persiste o registro em trips preenchendo todos os atributos de origem e destino.
  5. Gravação de Log: Grava entrada em trip_logs com event = 'TRIP_CREATED'.
  6. Notificação Push FCM: Dispara notificação imediata para o motorista:
    • Título: "Nova Viagem Atribuída"
    • Corpo: "Você recebeu a viagem REF: MANIFESTO-2026-8812 de Santos para Campinas."
    • Payload data: {"type": "TRIP_ASSIGNED", "trip_id": "encoded_sqid"}

2.2 Evento TRIP_UPDATED (trip.updated)​

Trigger: Invocação da rota POST /public/trips/update ou edição no Web App.

Sequência de Execução:​

  1. Localiza a viagem pelo par (trucking_company_id, ref).
  2. Aplica atualizações parciais nos campos permitidos (placa, datas de janela, dados customizados, status).
  3. Grava entrada em trip_logs com event = 'TRIP_UPDATED' contendo os campos alterados no JSON.
  4. Se o status for alterado para IN_PROGRESS, PAUSED ou COMPLETED, dispara notificação Push FCM de atualização para o motorista com data.type = "TRIP_UPDATED".

2.3 Eventos VIEWED e CLICKED (Telemetria Mobile)​

Trigger: Chamada via POST /mobile/activities/log-events pelo aplicativo mobile ao exibir ou expandir o card da viagem.

Sequência de Execução:​

  1. Decodifica o trip_id via Sqids.
  2. Confirma se o driver_id da viagem pertence ao motorista autenticado.
  3. Insere registro em trip_logs com event = 'VIEWED' ou 'CLICKED', salvando o nível de bateria ou fonte da tela enviada pelo cliente.

3. Regras de Negócio e Validações (RN-TRIP-XXX)​

RN-TRIP-001: Auto-Upsert Transacional de Motoristas​

A API pública de criação de viagens (POST /public/trips) permite o auto-cadastro de motoristas não registrados previamente. Se o CPF do motorista não existir, ele é criado e associado à transportadora emissora (validated_by = company.id), permitindo que o motorista faça o onboarding mobile e visualize a viagem imediatamente.

RN-TRIP-002: Suporte a Requisições em Lote (Batch Ingestion)​

O endpoint POST /public/trips aceita tanto um objeto individual quanto um array JSON de até 100 viagens por requisição. A transação é atômica: se qualquer viagem do lote falhar na validação de layout ou duplicidade, nenhuma viagem do lote é salva no banco.

RN-TRIP-003: Fail-Fast para Layouts Inválidos​

Se uma viagem enviada por API possuir layout_ref não cadastrado no painel da transportadora, a API rejeita a requisição com HTTP 400 (INVALID_LAYOUT_REF), especificando na resposta exatamente quais missing_layouts causaram a rejeição.

RN-TRIP-004: Serialização Obrigatória com Sqids​

Na rota GET /mobile/activities e nas respostas de logs públicos, todos os atributos de identificação (id, trucking_company_id, driver_id) são obrigatoriamente convertidos via Sqids, ocultando as chaves primárias internas.