AI Returns Predictor: guia completo

O AI Returns Predictor analisa cada encomenda logo na validação e atribui-lhe uma pontuação de risco de devolução de 0 a 100, classificada em três níveis (Baixo, Médio, Elevado). A pontuação é apresentada diretamente na ficha da encomenda, com o detalhe dos fatores, e a sua logística é avisada por e-mail antes da expedição sempre que uma encomenda ultrapassa o limiar de risco elevado. Este guia cobre a instalação, a configuração, o funcionamento do motor de pontuação e a camada de IA opcional.

Instalação

1. Descarregue o ficheiro dfreturnspredictor.zip a partir da sua conta DataFirefly.
2. Back-office do PrestaShop → Módulos → Carregar um módulo → envie o ZIP.
3. Na instalação, o módulo cria a sua tabela df_return_risk, regista os seus hooks e acrescenta o separador Expedição → Returns Predictor.

Configuração geral

Vá a Módulos → AI Returns Predictor → Configurar.

Limiares de risco

Dois limiares determinam o nível atribuído a cada encomenda a partir da sua pontuação:

• Limiar Médio (40 por predefinição): pontuação a partir da qual uma encomenda passa a risco Médio.
• Limiar Elevado (70 por predefinição): pontuação a partir da qual uma encomenda passa a risco Elevado e despoleta o aviso à logística.

Abaixo do limiar Médio, a encomenda é classificada como Baixo. Os limiares têm de respeitar a regra 1 ≤ Médio < Elevado ≤ 100.

Categorias com elevada taxa de devolução

Indique a lista dos identificadores das categorias conhecidas pelas devoluções frequentes (moda, têxtil, calçado…), separados por vírgulas. Os produtos pertencentes a essas categorias aumentam a pontuação da encomenda.

Aviso à logística

• E-mail de aviso à logística: endereço notificado quando uma encomenda ultrapassa o limiar de risco elevado. Deixe o campo vazio para desativar os avisos por e-mail.

Camada de IA (opcional)

O módulo funciona sem IA graças ao seu motor heurístico. Pode ativar uma camada de IA opcional para afinar a pontuação e gerar uma explicação curta.

• Ativar o afinamento por IA: se estiver desativado, não é feita qualquer chamada externa.
• Chave de API da Mistral: guardada do lado do servidor, nunca exposta ao front-office.
• Modelo Mistral: por exemplo, mistral-small-latest.

Como é calculada a pontuação

O motor heurístico combina seis fatores explicáveis, cada um com um número máximo de pontos. O total é limitado entre 0 e 100.

• Histórico de devoluções do cliente (0–30): relação entre o número de devoluções anteriores e o número de encomendas válidas do cliente.
• Encomenda de vários tamanhos ou variantes (0–25): mesmo produto encomendado em várias combinações (tamanhos, cores), sinal de uma intenção de experimentar.
• Valor do carrinho (0–15): montante da encomenda face ao carrinho médio da loja.
• Categorias de risco (0–20): presença de produtos nas categorias que declarou.
• Cliente novo (0–8): ausência de histórico de compra utilizável.
• Dimensão do carrinho (0–10): número de artigos distintos na encomenda.

O painel de risco na encomenda

Em cada ficha de encomenda (hook displayAdminOrderSide), um painel «Risco de devolução» apresenta:

• a pontuação em 100 e o nível com cor (Baixo / Médio / Elevado);
• o detalhe dos fatores que contribuem, com os respetivos pontos;
• a explicação da IA, quando existe;
• um botão Recalcular que relança a pontuação por AJAX sem recarregar a página.

A pontuação é calculada automaticamente na validação da encomenda (hook actionValidateOrder) e atualizada nas mudanças de estado (hook actionOrderStatusPostUpdate).

O painel logístico

O separador Expedição → Returns Predictor lista todas as encomendas pontuadas, ordenadas por pontuação decrescente. Encontra aí a referência, o cliente, o estado, a pontuação, o nível e o indicador de aviso. Filtre por nível para isolar as encomendas de risco elevado antes da preparação das embalagens. A ação «Ver» abre diretamente a ficha da encomenda em causa.

O aviso por e-mail

Quando uma encomenda ultrapassa o limiar de risco elevado no momento da criação, parte um e-mail de resumo para o endereço logístico configurado: referência da encomenda, pontuação, nível, cliente, fatores contributivos e eventual nota da IA. Os modelos de e-mail são fornecidos em francês e em inglês, e o envio tem em conta o idioma do cliente e a loja de origem da encomenda.

Compatibilidade e notas técnicas

• PrestaShop 8.0 a 9.x, multiloja e multilingue.
• Controlador de administração legacy (sem controlador Symfony) para a compatibilidade PS8/PS9.
• Endpoint AJAX do back-office através do 4.º argumento de getAdminLink(); resposta JSON produzida por um método dedicado.
• Tabela df_return_risk: um registo por encomenda, com pontuação, nível, fatores (JSON) e indicador de aviso.
• Camada de IA opcional: só os dados necessários ao cálculo são transmitidos à Mistral; recurso automático à heurística.

FAQ e resolução de problemas

O painel de risco não aparece na ficha da encomenda. Verifique se o módulo está mesmo ligado ao hook displayAdminOrderSide e se a encomenda foi criada depois da instalação. Utilize o botão «Recalcular» para forçar a pontuação.

Não recebo nenhum aviso por e-mail. Verifique se o endereço de aviso está preenchido e é válido e se a encomenda ultrapassa efetivamente o limiar Elevado. O aviso só é enviado uma vez por encomenda.

A IA não devolve qualquer explicação. Verifique a chave de API e o nome do modelo Mistral. O módulo passa de qualquer forma para a pontuação heurística; nenhuma pontuação se perde.

Todos os clientes novos são considerados de risco? Não. A ausência de histórico acrescenta apenas um ligeiro agravamento; a pontuação depende sobretudo dos outros fatores (várias variantes, categorias, valor do carrinho).