AI Returns Predictor — Guide complet

AI Returns Predictor analyse chaque commande dès sa validation et lui attribue un score de risque de retour de 0 à 100, classé en trois niveaux (Faible, Moyen, Élevé). Le score s’affiche directement sur la fiche commande, avec le détail des facteurs, et votre logistique est alertée par email avant l’expédition lorsqu’une commande dépasse le seuil de risque élevé. Ce guide couvre l’installation, la configuration, le fonctionnement du moteur de scoring et la couche IA optionnelle.

Installation

1. Téléchargez l’archive dfreturnspredictor.zip depuis votre compte DataFirefly.
2. Back-office PrestaShop → Modules → Téléverser un module → envoyez le ZIP.
3. À l’installation, le module crée sa table df_return_risk, enregistre ses hooks et ajoute l’onglet Expédition → Returns Predictor.

Configuration générale

Rendez-vous dans Modules → AI Returns Predictor → Configurer.

Seuils de risque

Deux seuils déterminent le niveau attribué à chaque commande à partir de son score :

• Seuil Moyen (par défaut 40) : score à partir duquel une commande passe en risque Moyen.
• Seuil Élevé (par défaut 70) : score à partir duquel une commande passe en risque Élevé et déclenche l’alerte logistique.

En dessous du seuil Moyen, la commande est classée Faible. Les seuils doivent respecter la règle 1 ≤ Moyen < Élevé ≤ 100.

Catégories à fort taux de retour

Renseignez la liste des identifiants de catégories réputées pour leurs retours fréquents (mode, textile, chaussures…), séparés par des virgules. Les produits appartenant à ces catégories augmentent le score de la commande.

Alerte logistique

• Email d’alerte logistique : adresse notifiée lorsqu’une commande franchit le seuil de risque élevé. Laissez le champ vide pour désactiver les alertes email.

Couche IA (optionnelle)

Le module fonctionne sans IA grâce à son moteur heuristique. Vous pouvez activer une couche IA optionnelle pour affiner le score et générer une explication courte.

• Activer l’affinage IA : si désactivé, aucun appel externe n’est effectué.
• Clé API Mistral : stockée côté serveur, jamais exposée au front-office.
• Modèle Mistral : par exemple mistral-small-latest.

Comment le score est calculé

Le moteur heuristique combine six facteurs explicables, chacun apportant un nombre de points plafonné. Le total est borné entre 0 et 100.

• Historique de retours du client (0–30) : rapport entre le nombre de retours passés et le nombre de commandes valides du client.
• Bracketing tailles / variantes (0–25) : même produit commandé en plusieurs déclinaisons (tailles, couleurs), signe d’une intention d’essayage.
• Valeur du panier (0–15) : montant de la commande rapporté au panier moyen de la boutique.
• Catégories à risque (0–20) : présence de produits dans les catégories que vous avez déclarées.
• Nouveau client (0–8) : absence d’historique d’achat exploitable.
• Taille du panier (0–10) : nombre d’articles distincts dans la commande.

Le panneau de risque sur la commande

Sur chaque fiche commande (hook displayAdminOrderSide), un panneau « Risque de retour » affiche :

• le score sur 100 et le niveau coloré (Faible / Moyen / Élevé) ;
• le détail des facteurs contributifs avec leurs points ;
• l’explication de l’IA, le cas échéant ;
• un bouton Recalculer qui relance le scoring en AJAX sans recharger la page.

Le score est calculé automatiquement à la validation de la commande (hook actionValidateOrder) et rafraîchi lors des changements de statut (hook actionOrderStatusPostUpdate).

Le tableau de bord logistique

L’onglet Expédition → Returns Predictor liste toutes les commandes scorées, triées par score décroissant. Vous y retrouvez la référence, le client, le statut, le score, le niveau et l’indicateur d’alerte. Filtrez par niveau pour isoler les commandes à risque élevé avant la préparation des colis. L’action « Voir » ouvre directement la fiche commande concernée.

L’alerte email

Lorsqu’une commande franchit le seuil de risque élevé à sa création, un email récapitulatif part vers l’adresse logistique configurée : référence de commande, score, niveau, client, facteurs contributifs et note IA éventuelle. Les modèles d’email sont fournis en français et en anglais, et l’envoi tient compte de la langue du client et de la boutique d’origine de la commande.

Compatibilité et notes techniques

• PrestaShop 8.0 à 9.x, multiboutique et multilingue.
• Contrôleur d’administration legacy (pas de contrôleur Symfony) pour la compatibilité PS8/PS9.
• Endpoint AJAX back-office via le 4ᵉ argument de getAdminLink() ; rendu JSON par une méthode dédiée.
• Table df_return_risk : un enregistrement par commande, avec score, niveau, facteurs (JSON) et indicateur d’alerte.
• Couche IA optionnelle : seules les données nécessaires au calcul sont transmises à Mistral ; repli automatique sur l’heuristique.

FAQ et dépannage

Le panneau de risque n’apparaît pas sur la fiche commande. Vérifiez que le module est bien greffé sur le hook displayAdminOrderSide et que la commande a été créée après l’installation. Utilisez le bouton « Recalculer » pour forcer le scoring.

Aucune alerte email n’est reçue. Vérifiez que l’adresse d’alerte est renseignée et valide, et que la commande dépasse réellement le seuil Élevé. L’alerte n’est envoyée qu’une fois par commande.

L’IA ne renvoie pas d’explication. Vérifiez la clé API et le nom du modèle Mistral. Le module bascule de toute façon sur le score heuristique ; aucun score n’est perdu.

Tous les nouveaux clients sont-ils considérés à risque ? Non. L’absence d’historique ajoute seulement une légère majoration ; le score dépend surtout des autres facteurs (bracketing, catégories, valeur du panier).