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

# Drivers

> Cadastro de motoristas via convite, vínculo N:N com empresas, dados de habilitação e status por empresa.

## Overview

O `Driver` representa o **perfil operacional** do motorista — está ligado 1:1 a um `User` e carrega os dados de habilitação do motorista. O vínculo com cada empresa vive em [DriverCompany](/data-modelling/fleet/driver-company), o que permite que o mesmo motorista atue em várias empresas simultaneamente, com status operacional independente em cada uma.

```mermaid theme={null}
erDiagram
    User ||--o| Driver : "1:1"
    Driver ||--o{ DriverCompany : "tem vínculos"
    Company ||--o{ DriverCompany : "tem motoristas"
    Driver ||--o{ Trip : "escalado em"
```

## Registration Flow

O cadastro de motorista ocorre **via convite**. O operador OPS dispara o convite, e o motorista (ou um User já existente com aquele email) o aceita informando os dados de habilitação se ainda não tiver Driver criado.

```mermaid theme={null}
flowchart TD
    OPS[OPS envia convite de motorista] --> CHECK[Organização possui Company<br/>e não há convite pendente]
    CHECK --> INVITE[Invite DRIVER disponível]
    INVITE --> NOTIFY[Notificação enviada por WhatsApp<br/>e email quando informado]
    NOTIFY --> ACCEPT[Motorista aceita o convite]
    ACCEPT --> USER[User identificado por telefone/email<br/>ou cadastrado no aceite]
    USER --> DRIVER{User já possui Driver?}
    DRIVER -->|Não| NEW_DRIVER[Driver recebe habilitação do aceite]
    DRIVER -->|Sim| EXISTING_DRIVER[Driver existente é reutilizado]
    NEW_DRIVER --> LINK[Vínculo DriverCompany ativo]
    EXISTING_DRIVER --> LINK
    LINK --> READY[Motorista pronto para operar na empresa]
```

## Cenários de aceite

| Estado prévio do User                | Estado prévio do Driver | Efeitos no aceite                                                                                                                 |
| ------------------------------------ | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Ausente                              | —                       | User cadastrado no aceite, Driver recebe dados de habilitação e vínculo com a empresa fica ativo                                  |
| Existe, sem Driver                   | Ausente                 | User é reutilizado, Driver recebe dados de habilitação e vínculo com a empresa fica ativo                                         |
| Existe, já é Driver em outra empresa | Existe                  | User e Driver são reutilizados; apenas o vínculo com a nova empresa fica ativo, e os dados de habilitação do aceite são ignorados |

<Info>
  A habilitação é informada **pelo motorista no aceite**, não pelo operador OPS na criação do convite. Quem tem os dados de habilitação em mãos é o motorista — o operador informa apenas o contato do motorista (telefone; email opcional).
</Info>

## Driver license validation

| Campo              | Tipo                  | Descrição                               |
| ------------------ | --------------------- | --------------------------------------- |
| `licenseNumber`    | string                | Número da licença/habilitação           |
| `licenseCategory`  | DriverLicenseCategory | Categoria da habilitação                |
| `licenseExpiresAt` | date                  | Data de validade da licença/habilitação |

### DriverLicenseCategory

| Valor | Descrição                                              |
| ----- | ------------------------------------------------------ |
| `D`   | Habilitação para veículos de transporte de passageiros |
| `E`   | Habilitação para veículos articulados/reboque          |

`licenseExpiresAt` representa a validade da licença/habilitação e pode ser usado para filtros e monitoramento operacional.

## Status por Empresa

O status operacional é **por empresa** ([DriverCompany.status](/data-modelling/fleet/driver-company#enums)) — não global. Desativar um motorista numa empresa não afeta os vínculos dele em outras.

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Convite aceito
    ACTIVE --> INACTIVE: Desativação na empresa
```

| `DriverCompany.status` | Semântica atual                    |
| ---------------------- | ---------------------------------- |
| `ACTIVE`               | Motorista ativo nesta empresa      |
| `INACTIVE`             | Motorista desativado nesta empresa |

## Capacidades OPS

| Capacidade            | Permissão       | Descrição                                                                |
| --------------------- | --------------- | ------------------------------------------------------------------------ |
| Listar motoristas     | `read:driver`   | Lista paginada de motoristas da organização                              |
| Convidar motorista    | `create:driver` | Cria o convite de motorista com telefone e email opcional                |
| Desvincular motorista | `update:driver` | Desativa o vínculo (`DriverCompany` → `INACTIVE`) na empresa do operador |

A listagem aceita filtro de texto (`licenseNumber`, `name`, `email`), filtros por `licenseCategory`, `companyStatus` ([DriverCompany.status](/data-modelling/fleet/driver-company#enums)), `status` (do User) e ranges de data (`licenseExpiresAt`, `createdAt`); ordenação por `createdAt` ou `licenseExpiresAt`.

## Business Rules

| Regra                       | Descrição                                                                                               |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| **Cadastro via convite**    | O Driver passa pelo fluxo de [convite tipo DRIVER](/domain/tenant/invitation-flow#flow--driver-invite). |
| **User 1:1 Driver**         | Cada User pode ter no máximo um Driver.                                                                 |
| **Vínculo N:N com Company** | Driver pode estar em várias empresas via DriverCompany.                                                 |
| **Status por empresa**      | `DriverCompany.status` é independente em cada empresa.                                                  |
| **Licença monitorável**     | `licenseExpiresAt` representa a validade da licença/habilitação.                                        |
| **Status por vínculo**      | `unlink` marca o `DriverCompany` como `INACTIVE`.                                                       |

<Tip>
  O vínculo Driver → User permite que o motorista acesse o sistema com sua própria conta (Driver API), visualizando viagens atribuídas ao seu `driverId`.
</Tip>