> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Trip Events

> TripEvent: tipos de eventos operacionais, eventos globais vs escopados a parada.

O **TripEvent** registra ocorrências operacionais durante o ciclo de vida de uma viagem. Eventos podem ser **globais** (afetam toda a viagem) ou **escopados a uma parada** (TripStop) específica.

## Campos

| Campo         | Tipo              | Descrição                                              |
| ------------- | ----------------- | ------------------------------------------------------ |
| `tripEventId` | UUID              | Identificador único                                    |
| `tripId`      | UUID              | Viagem à qual o evento pertence                        |
| `tripStopId`  | UUID (nullable)   | Parada específica (null = evento global)               |
| `type`        | TripEventType     | Tipo do evento                                         |
| `description` | string (nullable) | Descrição adicional do evento                          |
| `metadata`    | JSON (nullable)   | Dados adicionais estruturados                          |
| `createdBy`   | UUID?             | Usuário que criou o registro, quando aplicável         |
| `createdAt`   | datetime          | Data/hora do registro                                  |
| `updatedBy`   | UUID?             | Usuário que fez a última atualização, quando aplicável |
| `updatedAt`   | datetime          | Data de última atualização                             |

## Tipos de Evento

### TripEventType

| Tipo                 | Escopo           | Descrição                                                 |
| -------------------- | ---------------- | --------------------------------------------------------- |
| `DRIVER_CHANGED`     | Global           | Motorista foi substituído durante a viagem                |
| `VEHICLE_CHANGED`    | Global           | Veículo foi substituído                                   |
| `DEPARTURE_DELAYED`  | Global ou Parada | Partida atrasada                                          |
| `ARRIVAL_DELAYED`    | Global ou Parada | Chegada atrasada                                          |
| `BOARDING_STARTED`   | Parada           | Embarque iniciado em um ponto de parada                   |
| `BOARDING_COMPLETED` | Parada           | Embarque concluído em um ponto de parada                  |
| `INCIDENT`           | Global ou Parada | Incidente operacional (acidente, problema mecânico, etc.) |

## Eventos Globais vs Escopados

### Evento Global (`tripStopId = null`)

Afeta a viagem inteira. Exemplos:

* Troca de motorista — impacta todos os passageiros.
* Troca de veículo — impacta todos os passageiros.
* Atraso na partida da viagem — afeta todas as paradas.

### Evento Escopado a Parada

Afeta apenas passageiros que embarcam ou desembarcam em uma parada específica. Exemplos:

* Embarque iniciado na parada de Volta Redonda — relevante apenas para passageiros que embarcam ou desembarcam ali.
* Atraso de chegada em Juiz de Fora — impacta apenas itinerários que passam por esse ponto.

```mermaid theme={null}
flowchart TD
    T[Trip SP → Rio]

    T --> E1[TripEvent GLOBAL<br/>DRIVER_CHANGED<br/>Affects all passengers]
    T --> E2[TripEvent GLOBAL<br/>DEPARTURE_DELAYED<br/>Affects all passengers]

    S1[TripStop<br/>São Paulo]
    S2[TripStop<br/>Volta Redonda]

    S1 --> E3[TripEvent SCOPED<br/>BOARDING_COMPLETED<br/>Boarding at SP completed]
    S2 --> E4[TripEvent SCOPED<br/>ARRIVAL_DELAYED<br/>Arrival at VR delayed]
```

## Dados Adicionais (metadata)

O campo `metadata` armazena dados estruturados específicos do tipo de evento (união discriminada por `type`):

| Tipo                                    | Campos de metadata                                                                                                                                                            |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DRIVER_CHANGED`                        | `previousDriverId`, `previousDriverName`, `previousDriverLicenseNumber`, `newDriverId`, `newDriverName`, `newDriverLicenseNumber`                                             |
| `VEHICLE_CHANGED`                       | `previousVehicleId`, `previousVehicleLicensePlate`, `previousVehicleModel`, `newVehicleId`, `newVehicleLicensePlate`, `newVehicleModel`                                       |
| `DEPARTURE_DELAYED` / `ARRIVAL_DELAYED` | `delayMinutes`, `newEstimatedTime?`, `reason?`                                                                                                                                |
| `BOARDING_STARTED`                      | `expectedPassengers?`, `stopName?` (metadata opcional)                                                                                                                        |
| `BOARDING_COMPLETED`                    | `totalPassengers`, `noShowCount?`, `stopName?`                                                                                                                                |
| `INCIDENT`                              | `severity` (`LOW`/`MEDIUM`/`HIGH`/`CRITICAL`), `category` (`MECHANICAL`/`ACCIDENT`/`WEATHER`/`PASSENGER`/`ROAD_BLOCK`/`OTHER`), `affectedPassengers?`, `requiresReplacement?` |

## Efeitos do registro

Registrar uma ocorrência cria um `TripEvent` vinculado à viagem. Quando o tipo é `BOARDING_COMPLETED`, o registro representa a conclusão de embarque daquela viagem/parada.

<Warning>
  Registrar um evento **não** altera o status da viagem. Em particular, `BOARDING_COMPLETED` não move a viagem para `IN_PROGRESS`.
</Warning>

<Info>
  TripEvents não recebem edição de conteúdo no fluxo de negócio. Eles formam um histórico operacional da viagem.
</Info>