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

# Routes

> Route: pares fixos de origem-destino referenciando Points do catálogo global, definidos por empresa.

Uma **Route** representa um par fixo de origem-destino definido por uma empresa de transporte. Rotas são reutilizáveis — a mesma rota pode ser usada em múltiplas viagens. Origem e destino são referências ao catálogo global de [Points](/domain/operations/points).

## Campos

| Campo               | Tipo        | Descrição                                                   |
| ------------------- | ----------- | ----------------------------------------------------------- |
| `routeId`           | UUID        | Identificador único                                         |
| `companyId`         | UUID        | Empresa dona da rota                                        |
| `originId`          | UUID        | Referência ao Point de origem                               |
| `destinationId`     | UUID        | Referência ao Point de destino                              |
| `distanceKm`        | decimal     | Distância em quilômetros                                    |
| `estimatedDuration` | integer     | Duração estimada do trajeto em **minutos**                  |
| `status`            | RouteStatus | Status da rota (`PENDING_APPROVAL`, `ACTIVE` ou `INACTIVE`) |
| `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                                             |

## Regras de Negócio

* Uma Route pertence a exatamente uma **Company** (resolvida a partir da organização autenticada na criação).
* A rota define apenas os pontos extremos (origem e destino) via `originId` e `destinationId`. Os pontos intermediários são representados pelos **TripStops** das viagens; **TripItineraries** criam os pares compráveis entre essas paradas.
* `originId` e `destinationId` apontam para entradas do catálogo global de **Point** — nome e coordenadas vêm da entidade Point, não são duplicados em Route. A criação valida que ambos os Points existem.
* A distância (`distanceKm`) e a duração estimada (`estimatedDuration`, em minutos) são informadas pela empresa e servem como referência para precificação e planejamento — não são calculadas pelo route preview.
* A rota nasce com `status = PENDING_APPROVAL`.
* A rota só deve virar `ACTIVE` por aprovação registrada em [RouteApproval](/data-modelling/operations/route-approval).
* Rotas `ACTIVE` podem ser usadas em trips e vendas. Rotas `INACTIVE` ficam fora de novas operações.
* Uma rota com viagens ativas (`SCHEDULED` ou `IN_PROGRESS`) **não pode ser excluída**: a exclusão é bloqueada com `has_active_trips`.
* O acesso é escopado por organização; uma rota de outra organização retorna 404.

## Aprovação

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING_APPROVAL
    PENDING_APPROVAL --> ACTIVE: aprovação
    PENDING_APPROVAL --> PENDING_APPROVAL: rejeição registrada
    ACTIVE --> INACTIVE: inativação
    INACTIVE --> PENDING_APPROVAL: revisão
```

| Etapa     | Ator               | Efeito                                                                                  |
| --------- | ------------------ | --------------------------------------------------------------------------------------- |
| Criação   | Company            | Route nasce `PENDING_APPROVAL` com origem, destino, distância e duração estimada.       |
| Análise   | Usuário autorizado | Dados da rota são revisados.                                                            |
| Aprovação | Usuário autorizado | RouteApproval registra decisão e Route vira `ACTIVE`.                                   |
| Rejeição  | Usuário autorizado | RouteApproval registra motivo e a Route permanece `PENDING_APPROVAL`, fora de operação. |

<Info>
  A permission de aprovar fica no domínio de Authorization. O domínio de Operations registra o fluxo operacional e o efeito sobre a Route.
</Info>

## Relação com Point, Trip e TripItinerary

```mermaid theme={null}
flowchart TD
    P1[Point<br/>São Paulo] -->|originId| R[Route<br/>São Paulo → Rio de Janeiro]
    P2[Point<br/>Rio de Janeiro] -->|destinationId| R

    R --> T[Trip<br/>15/04 08:00]
    R --> T2[Trip<br/>16/04 08:00]

    T --> S1[TripStop<br/>São Paulo]
    T --> S2[TripStop<br/>Volta Redonda]
    T --> STOP3[TripStop<br/>Rio de Janeiro]

    S1 & STOP3 --> I1[TripItinerary<br/>SP → Rio]
    S1 & S2 --> I2[TripItinerary<br/>SP → VR]
    S2 & STOP3 --> I3[TripItinerary<br/>VR → Rio]
```

A rota define o trajeto macro (São Paulo → Rio de Janeiro) através de Points do catálogo global. Uma viagem possui TripStops (paradas físicas) e oferece múltiplos TripItineraries (trechos parciais compráveis) que referenciam pares de paradas.

<Tip>
  Rotas são entidades de referência — elas não mudam a cada viagem. Se uma empresa opera a mesma linha todo dia, ela cria a rota uma vez (referenciando dois Points existentes) e agenda múltiplas viagens para ela.
</Tip>