AI Returns Predictor — Vollständige Anleitung

AI Returns Predictor analysiert jede Bestellung im Moment der Validierung und vergibt einen Retouren-Risikoscore von 0 bis 100, eingestuft in drei Stufen (Niedrig, Mittel, Hoch). Der Score erscheint direkt auf der Bestellseite, mit einer Faktor-Aufschlüsselung, und Ihr Logistikteam wird vor dem Versand per E-Mail benachrichtigt, sobald eine Bestellung die Schwelle für hohes Risiko überschreitet. Dieser Leitfaden behandelt Installation, Konfiguration, Funktionsweise der Scoring-Engine und die optionale KI-Schicht.

Installation

1. Laden Sie das Archiv dfreturnspredictor.zip aus Ihrem DataFirefly-Konto herunter.
2. PrestaShop-Backoffice → Module → Modul hochladen → senden Sie die ZIP-Datei.
3. Bei der Installation erstellt das Modul seine Tabelle df_return_risk, registriert seine Hooks und fügt den Tab Versand → Returns Predictor hinzu.

Allgemeine Konfiguration

Gehen Sie zu Module → AI Returns Predictor → Konfigurieren.

Risikoschwellen

Zwei Schwellen bestimmen die Stufe, die jeder Bestellung anhand ihres Scores zugewiesen wird:

• Schwelle Mittel (Standard 40): Score, ab dem eine Bestellung als Mittel-Risiko gilt.
• Schwelle Hoch (Standard 70): Score, ab dem eine Bestellung als Hoch-Risiko gilt und den Logistik-Alarm auslöst.

Unterhalb der Schwelle Mittel wird die Bestellung als Niedrig eingestuft. Die Schwellen müssen die Regel 1 ≤ Mittel < Hoch ≤ 100 erfüllen.

Kategorien mit hoher Retourenquote

Geben Sie die durch Kommas getrennte Liste der IDs von Kategorien an, die für häufige Retouren bekannt sind (Mode, Textil, Schuhe…). Produkte in diesen Kategorien erhöhen den Score der Bestellung.

Logistik-Alarm

• E-Mail für Logistik-Alarm: Adresse, die benachrichtigt wird, wenn eine Bestellung die Schwelle für hohes Risiko überschreitet. Lassen Sie das Feld leer, um E-Mail-Alarme zu deaktivieren.

KI-Schicht (optional)

Das Modul funktioniert dank seiner heuristischen Engine ohne KI. Sie können eine optionale KI-Schicht aktivieren, um den Score zu verfeinern und eine kurze Erklärung zu erzeugen.

• KI-Verfeinerung aktivieren: bei Deaktivierung wird kein externer Aufruf durchgeführt.
• Mistral-API-Schlüssel: serverseitig gespeichert, nie im Frontoffice offengelegt.
• Mistral-Modell: zum Beispiel mistral-small-latest.

Wie der Score berechnet wird

Die heuristische Engine kombiniert sechs erklärbare Faktoren, von denen jeder eine begrenzte Punktzahl beiträgt. Die Summe ist auf 0 bis 100 begrenzt.

• Retourenhistorie des Kunden (0–30): Verhältnis der vergangenen Retouren zu den gültigen Bestellungen des Kunden.
• Größen-/Varianten-Bracketing (0–25): dasselbe Produkt in mehreren Varianten (Größen, Farben) bestellt, ein Zeichen für Anprobeabsicht.
• Warenkorbwert (0–15): Bestellbetrag im Verhältnis zum Durchschnittswarenkorb des Shops.
• Kategorien mit hoher Retourenquote (0–20): Vorhandensein von Produkten in den von Ihnen deklarierten Kategorien.
• Neukunde (0–8): keine verwertbare Kaufhistorie.
• Warenkorbgröße (0–10): Anzahl der unterschiedlichen Artikel in der Bestellung.

Das Risiko-Panel auf der Bestellung

Auf jeder Bestellseite (Hook displayAdminOrderSide) zeigt ein Panel „Retourenrisiko“:

• den Score von 100 und die farblich gekennzeichnete Stufe (Niedrig / Mittel / Hoch);
• die Aufschlüsselung der beitragenden Faktoren mit ihren Punkten;
• die KI-Erklärung, sofern zutreffend;
• eine Schaltfläche Neu berechnen, die das Scoring per AJAX ohne Neuladen der Seite erneut ausführt.

Der Score wird automatisch bei der Validierung der Bestellung berechnet (Hook actionValidateOrder) und bei Statusänderungen aktualisiert (Hook actionOrderStatusPostUpdate).

Das Logistik-Dashboard

Der Tab Versand → Returns Predictor listet alle bewerteten Bestellungen auf, nach absteigendem Score sortiert. Sie finden dort die Referenz, den Kunden, den Status, den Score, die Stufe und den Alarm-Indikator. Filtern Sie nach Stufe, um Bestellungen mit hohem Risiko vor der Paketvorbereitung zu isolieren. Die Aktion „Anzeigen“ öffnet direkt die betreffende Bestellseite.

Der E-Mail-Alarm

Wenn eine Bestellung bei ihrer Erstellung die Schwelle für hohes Risiko überschreitet, wird eine Zusammenfassungs-E-Mail an die konfigurierte Logistikadresse gesendet: Bestellreferenz, Score, Stufe, Kunde, beitragende Faktoren und eventuelle KI-Notiz. E-Mail-Vorlagen werden auf Französisch und Englisch bereitgestellt, und der Versand berücksichtigt die Sprache des Kunden und den Ursprungsshop der Bestellung.

Kompatibilität und technische Hinweise

• PrestaShop 8.0 bis 9.x, Multishop und mehrsprachig.
• Legacy-Admin-Controller (kein Symfony-Controller) für die PS8/PS9-Kompatibilität.
• Backoffice-AJAX-Endpunkt über das 4. Argument von getAdminLink(); JSON durch eine dedizierte Methode gerendert.
• Tabelle df_return_risk: ein Datensatz pro Bestellung, mit Score, Stufe, Faktoren (JSON) und Alarm-Flag.
• Optionale KI-Schicht: nur die für die Berechnung erforderlichen Daten werden an Mistral gesendet; automatischer Rückgriff auf die Heuristik.

FAQ und Fehlerbehebung

Das Risiko-Panel erscheint nicht auf der Bestellseite. Prüfen Sie, ob das Modul am Hook displayAdminOrderSide eingehängt ist und ob die Bestellung nach der Installation erstellt wurde. Verwenden Sie die Schaltfläche „Neu berechnen“, um das Scoring zu erzwingen.

Es wird kein E-Mail-Alarm empfangen. Prüfen Sie, ob die Alarmadresse ausgefüllt und gültig ist und ob die Bestellung die Schwelle Hoch tatsächlich überschreitet. Der Alarm wird nur einmal pro Bestellung gesendet.

Die KI gibt keine Erklärung zurück. Prüfen Sie den Mistral-API-Schlüssel und den Modellnamen. Das Modul greift ohnehin auf den heuristischen Score zurück; kein Score geht verloren.

Gelten alle Neukunden als riskant? Nein. Das Fehlen einer Historie fügt nur einen kleinen Aufschlag hinzu; der Score hängt hauptsächlich von den anderen Faktoren ab (Bracketing, Kategorien, Warenkorbwert).