Roteirização Inteligente (IA) - Treinamento eMerchan

O que é a Roteirização Inteligente?

É uma ferramenta que analisa todos os dados do setor — promotores, lojas, indústrias, frequências de visita e distâncias reais entre pontos — e gera um plano otimizado de roteirização usando inteligência artificial.

Em vez de o gestor reorganizar manualmente dezenas ou centenas de agendamentos, a IA faz isso em segundos, considerando:

Fator	O que a IA faz
Distâncias reais	Calcula distâncias por rota real (OSRM) entre a casa do promotor e cada loja — não linha reta
Proximidade entre lojas	Agrupa lojas próximas no mesmo dia para reduzir deslocamento
Carga de trabalho	Distribui atendimentos de forma equilibrada entre todos os promotores
Regras de negócio	Respeita promotor exclusivo, frequência quinzenal/diária, dias não consecutivos
Dimensionamento	Identifica se há promotores demais (ociosos) ou de menos (demanda não atendida)

⭐

Exclusivo eMerchan: Roteirização automática por IA com distâncias reais por rota (OSRM) — só no eMerchan.

Fluxo em 4 Etapas

Etapa	Ação	Quem faz
1. Selecionar Setor	Escolher o setor a otimizar	Gestor
2. Analisar Dados	Coletar promotores, lojas, indústrias e calcular matriz de distâncias	Sistema (automático)
3. Gerar Plano	Processar dados e retornar plano otimizado com comparativo Antes x Depois	IA
4. Aplicar ou Descartar	Revisar, aprovar e aplicar — ou descartar se não concordar	Gestor

Etapa 1 — Selecionar Setor

Lista de setores ativos — selecione o setor e clique em "Analisar Setor"

Acesse o menu Roteiro Planejamento → Roteirização IA.
A tela lista todos os setores ativos da empresa.
Setores já roteirizados pela IA mostram um badge "IA" em azul.
Selecione o setor desejado (radio button).
Clique no botão "Analisar Setor".

Setor selecionado — botão "Analisar Setor" fica ativo (verde)

💡

Histórico: Se o setor já foi roteirizado anteriormente, você pode ver o histórico de snapshots e reverter para a versão anterior a qualquer momento.

Etapa 2 — Preview dos Dados (Análise)

Antes de gerar o plano, o sistema mostra um resumo completo dos dados que serão enviados à IA.

Preview do setor badybassit — 2 promotores, 6 lojas, 3 indústrias, 18 agendamentos. Estimativa de 6.900 tokens

Informações exibidas

Informação	Descrição
Métricas resumidas	Quantidade de promotores, lojas, indústrias e agendamentos do setor
Tokens estimados	Quantidade de tokens que a geração do plano consumirá
Tokens usados (mês)	Total de tokens já consumidos no mês corrente
Limite mensal	Cota máxima de tokens por mês da empresa
Disponíveis	Saldo de tokens disponível para uso
Cache distâncias	Se a matriz foi calculada do cache (CACHE_HIT) ou recalculada
Promotores	Lista expansível com nome e cidade de cada promotor
Estabelecimentos	Lista expansível de lojas com cidade
Indústrias	Lista com tempo de atendimento, se é exclusiva, frequências e total

⚠️

Cota de tokens: Se o saldo de tokens for insuficiente, o botão "Gerar Plano com IA" fica desabilitado. A cota é renovada automaticamente todo mês e pode ser ajustada pelo suporte eMerchan.

Após conferir os dados, clique no botão "Gerar Plano com IA" para iniciar o processamento.

Etapa 3 — Plano Gerado (Comparativo)

Após a IA processar, a tela exibe o comparativo completo entre o roteiro atual e o proposto.

A) Resumo e Justificativas

A IA explica em 2-3 frases o que alterou e apresenta uma lista de justificativas para cada mudança (ex: "Promotor X estava sobrecarregado", "Lojas Y e Z ficam a 2km de distância").

B) Sugestões de Promotores

A IA analisa se a equipe está dimensionada corretamente:

Sugestão	Quando aparece	Visual
Retirar promotor	Promotor ficou ocioso ou com carga muito baixa	Card vermelho com nome e motivo
Adicionar promotor	Demanda excede a capacidade dos promotores atuais	Card azul com sugestão e motivo

💡

Apenas sugestões: A IA não remove nem adiciona promotores automaticamente. O gestor decide se aceita ou não cada recomendação.

C) Métricas Comparativas

Agendamentos alterados — ex: "8 de 14"
Promotores ativos — antes vs depois
Promotores ociosos — antes vs depois
Ocupação média — percentual da equipe

D) KM Total — Redução de Quilometragem

O sistema calcula o KM total da rota atual (OSRM) e compara com o KM estimado da nova rota:

KM antes → KM depois (ex: 125.3 km → 98.7 km)
Badge com a redução em km e percentual (ex: -26.6 km / 21%)
Verde = reduziu KM. Vermelho = aumentou KM

💰

Economia real: A redução de KM representa economia direta de combustível e tempo de deslocamento para a operação.

E) Grade por Promotor (Antes x Depois)

Tabela detalhada para cada promotor, dia a dia (Seg a Sáb), com os atendimentos atuais vs os propostos pela IA.

Grade por promotor — João Flores (14 → 8, -8) e Ricardo promotor Bady (0 → 5, +5) com legenda de cores

Legenda de Cores

Cor	Significado
Verde	Mantido — atendimento sem alteração
Laranja	Alterado — mudou de dia ou de promotor
Vermelho	Removido — saiu deste promotor
Azul	Novo — veio de outro promotor

Cada promotor mostra o total de atendimentos antes → depois (com diferença: +2, -3, etc.). Promotores com mudanças vêm expandidos para facilitar a revisão.

Promotor vagner rosa (3 → 0, -3) — no final, botões "Descartar" e "Aplicar Plano"

F) Promotores Ociosos

Se algum promotor ficou sem nenhum agendamento (nem antes, nem depois), aparece uma seção com chips mostrando os nomes. Isso indica promotores que podem ser realocados para outros setores.

Etapa 4 — Aplicar ou Descartar

Após revisar o plano completo, o gestor tem duas opções:

Ação	O que acontece
Aplicar Plano	Os agendamentos são atualizados conforme o plano. Um snapshot é salvo automaticamente para permitir reversão futura.
Descartar	O plano é descartado e nenhuma alteração é feita nos agendamentos.

💡

Badge IA: Após aplicar, o setor recebe o badge "IA" indicando que foi roteirizado. O snapshot fica disponível por 30 dias para reversão.

⚠️

Reversão com cuidado: A reversão restaura os agendamentos exatamente como estavam antes da roteirização. Se você já fez alterações manuais após aplicar o plano, essas alterações serão perdidas ao reverter.

Regras de Negócio Respeitadas pela IA

A IA segue automaticamente todas estas regras ao gerar o plano:

Regra	Descrição
Jornada	Cada promotor trabalha de Seg a Sex, máximo 8h/dia (480 min)
Promotor exclusivo	Indústrias marcadas como "exclusivo" são sempre atendidas pelo mesmo promotor
Frequência quinzenal	O dia da semana NÃO pode ser alterado (dia fixo). Apenas o promotor pode mudar
Atendimento diário	Mantém todos os dias (Seg a Sex) obrigatoriamente. Apenas o promotor pode mudar
Dias não consecutivos	Indústrias com 2-3 visitas/semana: dias não podem ser consecutivos (Seg+Ter proibido, Seg+Qua permitido)
Distâncias reais	OSRM (como GPS), não linha reta. Lojas próximas agrupadas no mesmo dia
Equilíbrio de carga	Distribui os atendimentos de forma equilibrada entre todos os promotores

Como funciona por trás

Etapa Interna	Detalhes
1. Coleta de Dados	Busca promotores, lojas, indústrias e agendamentos ativos do setor no banco de dados
2. Matriz de Distâncias	Calcula distâncias reais (km por rota) entre todos os pontos via servidor OSRM. Cache de 30 dias
3. Processamento IA	Dados enviados à IA com regras de negócio. Retorna plano otimizado em JSON
4. Snapshot	Plano salvo como backup para aplicação, reversão e histórico

💡

Cache inteligente: A matriz de distâncias é calculada uma vez e cacheada por 30 dias. Em setores com muitas lojas, isso evita recálculos desnecessários e agiliza gerações futuras.

Perguntas Frequentes

A IA vai alterar meus agendamentos automaticamente?

Não. A IA apenas sugere. O gestor precisa revisar e clicar em "Aplicar Plano" para que as alterações sejam efetivadas.

Posso reverter depois de aplicar?

Sim. O sistema salva um snapshot com os agendamentos originais. Basta clicar no botão de reverter no setor. O snapshot expira após 30 dias.

A IA pode sugerir tirar ou colocar promotor?

Sim. Analisa a capacidade e sugere retirar promotores ociosos ou adicionar mais. São apenas sugestões — o gestor decide.

O que é "promotor exclusivo"?

Quando uma indústria exige que o mesmo promotor atenda sempre. A IA respeita essa regra e nunca troca o promotor de uma indústria exclusiva.

As distâncias são por linha reta?

Não. O eMerchan usa o OSRM (Open Source Routing Machine) para calcular distâncias reais por rota, como um GPS. Precisão muito maior que linha reta.

Quanto custa gerar um plano?

Cada geração consome tokens da cota mensal da empresa. A cota é renovada automaticamente todo mês. O gestor vê a estimativa antes de confirmar.

Posso roteirizar o mesmo setor várias vezes?

Sim. Cada geração cria um novo snapshot. Se o resultado anterior foi melhor, basta reverter e gerar novamente.

E se eu fizer alterações manuais depois?

As alterações manuais são preservadas normalmente. Porém, ao reverter, os agendamentos voltam ao estado original (antes da roteirização) e as alterações manuais feitas depois serão perdidas.

⚠️

Cuidado: Evite reverter o plano se já fez muitas alterações manuais após a aplicação. A reversão restaura o estado exato de antes da roteirização.

Dicas e Boas Práticas

💡

Setor ideal para demonstração: Use um setor com pelo menos 3 promotores e 5+ lojas para que as diferenças fiquem visíveis no comparativo.

💡

Revise as sugestões de equipe: Se a IA sugere retirar um promotor, analise se ele pode ser realocado para outro setor antes de tomar a decisão.

💡

Observe a redução de KM: O badge de KM mostra a economia real. Uma redução de 20-30% é comum em setores que nunca foram otimizados pela IA.

💡

Snapshot como segurança: Sempre pode reverter em até 30 dias. Aplique o plano com confiança e acompanhe os resultados na prática.

💡

Legenda de cores: Na grade Antes x Depois, foque nos itens laranja (alterados) e azul (novos) — eles mostram exatamente o que a IA moveu e para onde.