> ## 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 Itineraries

> TripItinerary: segmentos compráveis dentro de uma viagem, referenciando TripStops com precificação independente.

Um **TripItinerary** representa um **segmento comprável** dentro de uma viagem (Trip). Enquanto a Route define o trajeto completo (origem-destino), os itinerários permitem que trechos parciais sejam vendidos separadamente com preços independentes.

## Campos

| Campo             | Tipo      | Descrição                                                 |
| ----------------- | --------- | --------------------------------------------------------- |
| `tripItineraryId` | UUID      | Identificador único                                       |
| `tripId`          | UUID      | Viagem à qual pertence                                    |
| `fromStopId`      | UUID      | Referência à parada de embarque relacionada a TripStop    |
| `toStopId`        | UUID      | Referência à parada de desembarque relacionada a TripStop |
| `price`           | integer   | Preço do itinerário em centavos                           |
| `createdBy`       | UUID?     | Usuário que criou o registro, quando aplicável            |
| `createdAt`       | datetime  | Data de criação                                           |
| `updatedBy`       | UUID?     | Usuário que fez a última atualização, quando aplicável    |
| `updatedAt`       | datetime  | Data de última atualização                                |
| `deletedBy`       | UUID?     | Usuário que removeu o registro, quando aplicável          |
| `deletedAt`       | datetime? | Data de remoção                                           |

## Relação com TripStop

Os campos `fromStopId` e `toStopId` referenciam **paradas físicas** (TripStop) da viagem. Cada TripStop possui um `stopOrder` que define sua posição na sequência. Os dados geográficos (nome, lat, lng) e temporais (arrivalAt, departureAt) são centralizados na TripStop.

### Exemplo

Considere uma viagem com 4 paradas:

| TripStop | stopOrder | name           |
| -------- | --------- | -------------- |
| stop-a   | 0         | São Paulo      |
| stop-b   | 1         | Volta Redonda  |
| stop-c   | 2         | Juiz de Fora   |
| stop-d   | 3         | Rio de Janeiro |

Os itinerários possíveis seriam:

| TripItinerary                  | fromStop   | toStop     | Segmentos ocupados |
| ------------------------------ | ---------- | ---------- | ------------------ |
| SP → Volta Redonda             | stop-a (0) | stop-b (1) | 0-1                |
| SP → Juiz de Fora              | stop-a (0) | stop-c (2) | 0-1, 1-2           |
| SP → Rio de Janeiro            | stop-a (0) | stop-d (3) | 0-1, 1-2, 2-3      |
| Volta Redonda → Juiz de Fora   | stop-b (1) | stop-c (2) | 1-2                |
| Volta Redonda → Rio de Janeiro | stop-b (1) | stop-d (3) | 1-2, 2-3           |
| Juiz de Fora → Rio de Janeiro  | stop-c (2) | stop-d (3) | 2-3                |

## Precificação Independente

Cada itinerário tem seu próprio preço, independente dos demais. O preço do trecho SP → Rio não precisa ser a soma de SP → VR + VR → JF + JF → Rio.

<Info>
  A precificação independente permite estratégias comerciais flexíveis. Por exemplo, o trecho completo pode ter desconto em relação à soma dos trechos parciais para incentivar viagens longas.
</Info>

## Relação com TripSeatSegment

Os segmentos ocupados por um itinerário são determinados pelo range de `stopOrder` entre as paradas referenciadas. Isso garante que assentos não sejam vendidos em duplicidade para trechos sobrepostos.

```mermaid theme={null}
flowchart LR
    I[TripItinerary<br/>SP → Rio<br/>stop-a → stop-d]
    I --> S1[Segmento 0-1<br/>SP → VR]
    I --> S2[Segmento 1-2<br/>VR → JF]
    I --> S3[Segmento 2-3<br/>JF → Rio]
```

<Warning>
  Se um passageiro compra SP → Rio (segmentos 0-1-2-3) no assento 5, ninguém mais pode comprar VR → JF no assento 5, pois o segmento 1-2 já está ocupado.
</Warning>