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

# Points

> Point: catálogo global de localidades reutilizáveis com nome, descrição e coordenadas.

Um **Point** representa uma localidade do catálogo **global** do DEVMOB — um terminal, cidade, ponto de embarque ou local de referência identificado por nome, coordenadas e uma descrição opcional. Pontos são compartilhados entre todas as empresas para padronizar filtros e buscas no app do passageiro.

## Campos

| Campo         | Tipo      | Descrição                                              |
| ------------- | --------- | ------------------------------------------------------ |
| `pointId`     | UUID      | Identificador único                                    |
| `name`        | string    | Nome do local                                          |
| `description` | string?   | Descrição complementar (opcional)                      |
| `lat`         | decimal?  | Latitude (opcional, entre -90 e 90)                    |
| `lng`         | decimal?  | Longitude (opcional, entre -180 e 180)                 |
| `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

* O catálogo de Points é **global** — não pertence a nenhuma Organization, Cooperative ou Company.
* Pontos são gerenciados pelo BackOffice e consumidos por todas as empresas como referência única.
* O nome é único (case-insensitive) — criar ou renomear um Point para um nome já usado retorna conflito.
* Uma Route referencia exatamente dois Points: um como **origem** (`originId`) e outro como **destino** (`destinationId`).
* O mesmo Point pode ser reutilizado em quantas rotas forem necessárias — esse é o ganho central do catálogo.
* As coordenadas (`lat`/`lng`) são **opcionais**. Um Point sem coordenadas é válido como parada e pode ser enviado ao [route preview](/domain/operations/routing), mas qualquer par consecutivo que envolva Point sem coordenadas vira um segmento `GAP` com `reason: MISSING_COORDINATES`.

## Origem das coordenadas (Place lookup)

As coordenadas de um Point normalmente vêm de um [Place](/domain/operations/places). O fluxo de cadastro no BackOffice usa autocomplete para encontrar o local e resolver `{ name, description, lat, lng }`, que alimenta a criação do Point.

## Relação com Route

```mermaid theme={null}
flowchart LR
    P1[Point<br/>São Paulo] -->|originId| R1[Route<br/>SP → Rio]
    P2[Point<br/>Rio de Janeiro] -->|destinationId| R1
    P1 -->|originId| R2[Route<br/>SP → BH]
    P3[Point<br/>Belo Horizonte] -->|destinationId| R2
    P2 -->|originId| R3[Route<br/>Rio → SP]
    P1 -->|destinationId| R3
```

Cada Route aponta para dois Points (origem e destino). Um único Point como "São Paulo" pode ser origem de N rotas e destino de M rotas — sem duplicação de nome ou coordenadas.

<Tip>
  Pontos formam a base do filtro padronizado de busca no app do passageiro: como o catálogo é global, o usuário consegue filtrar viagens por origem/destino de forma consistente entre todas as empresas operadoras.
</Tip>