Rotas de Técnicos
As rotas de técnicos são a terceira capacidade do AI Ops. O solver pega dois tipos de paradas — trocas de bateria e movimentos de rebalanceamento — e os empacota em uma única rota ordenada por técnico por turno. O técnico segue a rota dentro da operator-app.
Esta funcionalidade só é habilitada quando o subaccount tem ai_ops_tier='enterprise'.
O que entra em uma rota
O construtor de rotas roda a cada 30 minutos durante o horário operacional (06:00-22:00, horário local). Para cada técnico em turno, ele reúne:
- Veículos com bateria baixa abaixo do limiar de troca — viram paradas swap.
- Recomendações de rebalanceamento aceitas — cada uma vira uma parada pickup e uma parada dropoff, pareadas (o mesmo veículo precisa ser pego e depois deixado).
- Local de início e fim do técnico para o turno.
- A janela do turno (início, fim).
- Capacidade do veículo — quantos veículos cabem na van do técnico de uma vez.
O solver minimiza o tempo total de deslocamento sujeito a: todas as paradas cabendo na janela do turno, todos os pares pickup → dropoff sendo respeitados em ordem e a capacidade nunca excedendo o limite da van.
Tipos de parada
| Tipo | Significado |
|---|---|
| swap | Troca de bateria no local. O técnico troca a bateria e segue. O veículo permanece no mesmo hex. |
| pickup | O técnico recolhe um veículo superabastecido e carrega na van. |
| dropoff | O técnico deixa um veículo previamente recolhido no destino de rebalanceamento. |
Uma rota alterna entre pickups e dropoffs conforme a van enche e esvazia. Paradas de swap podem ocorrer em qualquer ponto da sequência.
Solvers
O Levy AI Ops é entregue com três implementações de solver e escolhe em tempo de execução:
- OR-Tools — solver open-source do Google para roteamento de veículos, exposto como um microsserviço FastAPI. Respeita pares pickup/delivery, janelas de tempo, capacidade e usa a metaheurística GUIDED_LOCAL_SEARCH com limite de 5 segundos. Padrão se
ORTOOLS_SOLVER_ENDPOINTestiver configurado. - Routific — API paga, soluções de maior qualidade para rotas maiores. Usado quando
ROUTIFIC_API_TOKENestá definido. Melhor para rotas com 30+ paradas. - Solver de savings local — fallback puro TypeScript Clarke-Wright + 2-opt que roda no Node. Adequado para rotas de até ~30 paradas em menos de 100 ms. Usado quando nenhum solver remoto está configurado.
O solver ativo é registrado em rebalance_routes.solver_version para auditoria de qual execução usou qual engine.
A regra de auto-manutenção
Quando uma rota é construída, todo veículo associado a uma parada de pickup é automaticamente colocado em status maintenance. Isso impede que um passageiro pegue o veículo antes do técnico chegar.
O veículo permanece em maintenance até um destes eventos:
- O técnico conclui a parada de pickup (o veículo continua em
maintenanceenquanto está na van e volta aavailableno dropoff). - A rota é abandonada (o veículo volta imediatamente a
available). - O técnico conclui uma parada swap (o veículo volta a
availableassim que a troca é registrada).
Esta é a única ação do AI Ops que ocorre sem revisão do operador. É intencional e limitada à janela de pickup de uma rota ativa.
Tabela de rotas
Uma rota é armazenada em rebalance_routes com estes campos-chave:
| Campo | Significado |
|---|---|
subaccount_id | Escopo do RLS |
technician_id | Usuário atribuído à rota |
shift_start / shift_end | A janela respeitada pelo solver |
status | planned → in_progress → completed / abandoned |
solver_version | Engine que construiu a rota |
total_distance_m | Estimativa de distância do solver |
estimated_minutes | Estimativa de tempo do solver |
Cada parada fica em rebalance_route_stops:
| Campo | Significado |
|---|---|
sequence | Ordem indexada a partir de 0 ao longo da rota |
stop_type | pickup / dropoff / swap |
vehicle_uuid | Veículo sobre o qual a parada atua |
destination_h3 | Para dropoffs, o hex alvo |
eta | Chegada estimada pelo solver |
time_window_end | Última chegada aceitável |
completed_at | Quando o técnico marcou como concluída |
completion_note | Texto livre opcional |
Casos especiais
| Situação | O que acontece |
|---|---|
| Técnico não aceita a rota | Status fica em planned. A auto-manutenção não é aplicada até o técnico tocar em Accept. |
| Técnico toca em Abandon | Veículos em auto-manutenção voltam a available. Recomendações incompletas são reabertas. |
| Paradas demais para a janela do turno | O solver retorna o maior subconjunto viável. Paradas excedentes ficam como recomendações open para a próxima rota ou outro técnico. |
| Nenhum técnico em turno | Rotas não são geradas. Recomendações continuam acumulando no painel do operador. |
| Solver estoura tempo (>5s no OR-Tools) | O sistema cai para o solver de savings local naquela execução. Um aviso no Sentry é emitido. |
Medindo o ganho
A literatura acadêmica sobre roteamento conjunto de troca + rebalanceamento estima cerca de 50% de redução na distância percorrida versus rotas separadas de troca e rebalanceamento. Na prática, espere de 30 a 50% dependendo da densidade da frota e da duração do turno. O campo total_distance_m de cada rota é a medição: compare uma semana de rotas com AI Ops a uma semana de rotas planejadas manualmente para ver o delta.
Relacionado
- Rotas na operator-app — o que o técnico vê no app.
- Recomendações de rebalanceamento — entrada do construtor de rotas.
- Feature flags e níveis —
ai_ops_tier='enterprise'é obrigatório.