AI Returns Predictor — Guida completa

AI Returns Predictor analizza ogni ordine nel momento della convalida e gli assegna un punteggio di rischio di reso da 0 a 100, classificato in tre livelli (Basso, Medio, Alto). Il punteggio appare direttamente nella scheda dell’ordine, con il dettaglio dei fattori, e il tuo team logistico riceve un avviso via email prima della spedizione quando un ordine supera la soglia di rischio elevato. Questa guida copre l’installazione, la configurazione, il funzionamento del motore di scoring e il livello IA opzionale.

Installazione

1. Scarica l’archivio dfreturnspredictor.zip dal tuo account DataFirefly.
2. Back office di PrestaShop → Moduli → Carica un modulo → invia lo ZIP.
3. All’installazione, il modulo crea la sua tabella df_return_risk, registra i suoi hook e aggiunge la scheda Spedizione → Returns Predictor.

Configurazione generale

Vai in Moduli → AI Returns Predictor → Configura.

Soglie di rischio

Due soglie determinano il livello assegnato a ogni ordine in base al suo punteggio:

• Soglia Media (predefinita 40): punteggio a partire dal quale un ordine passa a rischio Medio.
• Soglia Alta (predefinita 70): punteggio a partire dal quale un ordine passa a rischio Alto e attiva l’avviso logistico.

Al di sotto della soglia Media, l’ordine è classificato come Basso. Le soglie devono rispettare la regola 1 ≤ Media < Alta ≤ 100.

Categorie ad alto tasso di reso

Inserisci l’elenco degli identificatori delle categorie note per i resi frequenti (moda, abbigliamento, calzature…), separati da virgole. I prodotti che appartengono a queste categorie aumentano il punteggio dell’ordine.

Avviso logistico

• Email di avviso logistico: indirizzo notificato quando un ordine supera la soglia di rischio elevato. Lascia il campo vuoto per disattivare gli avvisi via email.

Livello IA (opzionale)

Il modulo funziona senza IA grazie al suo motore euristico. Puoi attivare un livello IA opzionale per affinare il punteggio e generare una spiegazione breve.

• Attiva l’affinamento IA: se disattivato, non viene effettuata alcuna chiamata esterna.
• Chiave API Mistral: memorizzata lato server, mai esposta al front office.
• Modello Mistral: per esempio mistral-small-latest.

Come viene calcolato il punteggio

Il motore euristico combina sei fattori spiegabili, ciascuno con un contributo in punti limitato. Il totale è compreso tra 0 e 100.

• Cronologia resi del cliente (0–30): rapporto tra il numero di resi passati e gli ordini validi del cliente.
• Bracketing taglie / varianti (0–25): stesso prodotto ordinato in più varianti (taglie, colori), segno di intenzione di prova.
• Valore del carrello (0–15): importo dell’ordine rispetto al carrello medio del negozio.
• Categorie ad alto tasso di reso (0–20): presenza di prodotti nelle categorie che hai dichiarato.
• Nuovo cliente (0–8): nessuna cronologia d’acquisto utilizzabile.
• Dimensione del carrello (0–10): numero di articoli distinti nell’ordine.

Il pannello di rischio sull’ordine

Su ogni scheda dell’ordine (hook displayAdminOrderSide), un pannello «Rischio di reso» mostra:

• il punteggio su 100 e il livello con codice colore (Basso / Medio / Alto);
• il dettaglio dei fattori contribuenti con i loro punti;
• la spiegazione dell’IA, se applicabile;
• un pulsante Ricalcola che riavvia lo scoring via AJAX senza ricaricare la pagina.

Il punteggio viene calcolato automaticamente alla convalida dell’ordine (hook actionValidateOrder) e aggiornato ai cambi di stato (hook actionOrderStatusPostUpdate).

La dashboard logistica

La scheda Spedizione → Returns Predictor elenca tutti gli ordini valutati, ordinati per punteggio decrescente. Vi trovi il riferimento, il cliente, lo stato, il punteggio, il livello e l’indicatore di avviso. Filtra per livello per isolare gli ordini a rischio elevato prima di preparare i pacchi. L’azione «Visualizza» apre direttamente la scheda dell’ordine interessato.

L’avviso via email

Quando un ordine supera la soglia di rischio elevato alla sua creazione, viene inviata una email di riepilogo all’indirizzo logistico configurato: riferimento dell’ordine, punteggio, livello, cliente, fattori contribuenti ed eventuale nota dell’IA. I modelli di email sono forniti in francese e inglese, e l’invio tiene conto della lingua del cliente e del negozio di origine dell’ordine.

Compatibilità e note tecniche

• PrestaShop 8.0 a 9.x, multistore e multilingua.
• Controller di amministrazione legacy (nessun controller Symfony) per la compatibilità PS8/PS9.
• Endpoint AJAX di back office tramite il 4° argomento di getAdminLink(); JSON renderizzato da un metodo dedicato.
• Tabella df_return_risk: un record per ordine, con punteggio, livello, fattori (JSON) e flag di avviso.
• Livello IA opzionale: vengono inviati a Mistral solo i dati necessari al calcolo; ripiego automatico sull’euristica.

FAQ e risoluzione dei problemi

Il pannello di rischio non appare nella scheda dell’ordine. Verifica che il modulo sia agganciato all’hook displayAdminOrderSide e che l’ordine sia stato creato dopo l’installazione. Usa il pulsante «Ricalcola» per forzare lo scoring.

Non si riceve alcun avviso via email. Verifica che l’indirizzo di avviso sia compilato e valido, e che l’ordine superi effettivamente la soglia Alta. L’avviso viene inviato una sola volta per ordine.

L’IA non restituisce alcuna spiegazione. Verifica la chiave API e il nome del modello Mistral. Il modulo ripiega comunque sul punteggio euristico; nessun punteggio viene perso.

Tutti i nuovi clienti sono considerati a rischio? No. L’assenza di cronologia aggiunge solo un piccolo incremento; il punteggio dipende soprattutto dagli altri fattori (bracketing, categorie, valore del carrello).