Cadastro de Entregadores
Visão Geral
O módulo drivers (W14) introduz um schema independente de usuário para entregadores próprios da operação. Um entregador autentica-se com shortCode + PIN e obtém um JWT de curta duração (role: 'driver') para usar a PWA de entrega.
Schema: Driver
backend/src/drivers/schemas/driver.schema.ts
| Campo | Tipo | Descrição |
|---|---|---|
tenant | ObjectId | Tenant pai |
shortCode | string | Código curto de login (ex: DRV01) — único por tenant |
pinHash | string | PIN hasheado (bcrypt) |
name | string | Nome do entregador |
phone | string? | Telefone |
email | string? | |
vehicle.type | enum | motorcycle | bicycle | car | van | on_foot |
vehicle.plate | string? | Placa do veículo |
vehicle.model | string? | Modelo |
vehicle.color | string? | Cor |
documents.cpf | string? | CPF |
documents.cnh | string? | Habilitação |
documents.cnhExpiry | Date? | Validade da CNH |
status | enum | available | on_route | offline (default offline) |
assignedBranchIds | ObjectId[] | Filiais autorizadas para auto-atribuição |
lastKnownLocation.lng | number? | Longitude mais recente |
lastKnownLocation.lat | number? | Latitude mais recente |
lastKnownLocation.updatedAt | Date? | Timestamp da posição |
active | boolean | Cadastro ativo (default true) |
Índices:
{ shortCode: 1, tenant: 1 }— unique{ tenant: 1, status: 1 }— lookup rápido de disponíveis{ 'lastKnownLocation.lat': 1, 'lastKnownLocation.lng': 1 }— geo queries
API Routes
Admin (requer orders.manage.status)
Prefixo: POST /t/:slug/admin/drivers
| Método | Rota | Descrição |
|---|---|---|
GET | / | Listar todos os entregadores do tenant |
GET | /available?branchId= | Entregadores disponíveis (opcionalmente por filial) |
GET | /:id | Detalhe do entregador |
POST | / | Criar entregador |
PUT | /:id | Atualizar |
DELETE | /:id | Desativar (soft delete) |
POST | /:id/assign/:orderId | Atribuição manual de entregador a um pedido |
POST | /auto-assign/:orderId?strategy=nearest | Auto-atribuição (nearest | round-robin) |
PWA do Entregador
Prefixo: /t/:slug/driver
| Método | Rota | Auth | Descrição |
|---|---|---|---|
POST | /login | Público | shortCode + PIN → JWT 24h (role:driver) |
GET | /orders/pending | Driver JWT | Pedidos pendentes para este entregador |
PATCH | /location | Driver JWT | Atualizar posição GPS |
PATCH | /status | Driver JWT | Atualizar status (available/on_route/offline) |
Rate limit: /login → 10 req/60s (Throttle).
Autenticação do Entregador
O entregador faz login com:
POST /t/:slug/driver/login
{ "shortCode": "DRV01", "pin": "1234" }Resposta:
{
"access_token": "<jwt 24h>",
"driver": { "name": "...", "status": "available", ... }
}O payload do JWT inclui { sub: driverId, role: "driver", tenantId }. Endpoints /t/:slug/driver/* validam com JwtAuthGuard + TenantGuard.
Serviço de Atribuição
backend/src/drivers/driver-assignment.service.ts
| Método | Parâmetros | Comportamento |
|---|---|---|
manualAssign(tenantId, orderId, driverId) | — | Valida status do driver; lança se on_route sem pedidos pendentes |
autoAssign(tenantId, orderId, strategy) | nearest | round-robin | nearest — seleciona driver disponível com menor distância haversine até a filial do pedido; round-robin — distribui em fila circular |
Após atribuição, o pedido recebe assignedDriverId e o status do driver muda para on_route.
Prova de Entrega (POD)
Ao entregar o pedido, a PWA chama PATCH /orders/:id/status com status delivered. O backend registra deliveredAt e reverte o driver.status para available.
Permissões
| Permissão | O que protege |
|---|---|
orders.view.all | GET admin drivers |
orders.manage.status | POST/PUT/DELETE + assign |