AI Returns Predictor: kompletny przewodnik

AI Returns Predictor analizuje każde zamówienie od razu po jego zatwierdzeniu i przypisuje mu wynik ryzyka zwrotu od 0 do 100, sklasyfikowany na trzech poziomach (Niski, Średni, Wysoki). Wynik jest widoczny bezpośrednio na karcie zamówienia, wraz ze szczegółami czynników, a Twoja logistyka otrzymuje e-mail przed wysyłką, gdy zamówienie przekroczy próg wysokiego ryzyka. Ten przewodnik obejmuje instalację, konfigurację, działanie silnika scoringu i opcjonalną warstwę AI.

Instalacja

1. Pobierz archiwum dfreturnspredictor.zip ze swojego konta DataFirefly.
2. Panel administracyjny PrestaShop → Moduły → Wgraj moduł → wyślij plik ZIP.
3. Przy instalacji moduł tworzy tabelę df_return_risk, rejestruje hooki i dodaje zakładkę Wysyłka → Returns Predictor.

Konfiguracja ogólna

Przejdź do Moduły → AI Returns Predictor → Konfiguruj.

Progi ryzyka

Dwa progi decydują o poziomie przypisanym zamówieniu na podstawie jego wyniku:

• Próg Średni (domyślnie 40): wynik, od którego zamówienie przechodzi na poziom ryzyka Średni.
• Próg Wysoki (domyślnie 70): wynik, od którego zamówienie przechodzi na poziom ryzyka Wysoki i uruchamia alert logistyczny.

Poniżej progu Średni zamówienie jest klasyfikowane jako Niskie. Progi muszą spełniać regułę 1 ≤ Średni < Wysoki ≤ 100.

Kategorie o wysokim współczynniku zwrotów

Wpisz listę identyfikatorów kategorii znanych z częstych zwrotów (moda, tekstylia, obuwie i podobne), oddzielonych przecinkami. Produkty należące do tych kategorii podnoszą wynik zamówienia.

Alert logistyczny

• E-mail alertu logistycznego: adres powiadamiany, gdy zamówienie przekroczy próg wysokiego ryzyka. Pozostaw pole puste, aby wyłączyć alerty e-mail.

Warstwa AI (opcjonalna)

Moduł działa bez AI dzięki silnikowi heurystycznemu. Możesz włączyć opcjonalną warstwę AI, aby doprecyzować wynik i wygenerować krótkie wyjaśnienie.

• Włącz doprecyzowanie AI: gdy jest wyłączone, nie jest wykonywane żadne zewnętrzne wywołanie.
• Klucz API Mistral: przechowywany po stronie serwera, nigdy nie jest udostępniany w front office.
• Model Mistral: na przykład mistral-small-latest.

Jak liczony jest wynik

Silnik heurystyczny łączy sześć wyjaśnialnych czynników, z których każdy wnosi ograniczoną liczbę punktów. Suma mieści się w przedziale od 0 do 100.

• Historia zwrotów klienta (0 do 30): stosunek liczby wcześniejszych zwrotów do liczby ważnych zamówień klienta.
• Bracketing rozmiarów i wariantów (0 do 25): ten sam produkt zamówiony w kilku wariantach (rozmiary, kolory), co wskazuje na zamiar przymiarki.
• Wartość koszyka (0 do 15): kwota zamówienia odniesiona do średniego koszyka sklepu.
• Kategorie ryzyka (0 do 20): obecność produktów z kategorii zadeklarowanych przez Ciebie.
• Nowy klient (0 do 8): brak użytecznej historii zakupów.
• Wielkość koszyka (0 do 10): liczba różnych artykułów w zamówieniu.

Panel ryzyka na zamówieniu

Na każdej karcie zamówienia (hook displayAdminOrderSide) panel ryzyka zwrotu pokazuje:

• wynik w skali 100 i kolorowy poziom (Niski, Średni, Wysoki);
• szczegóły czynników składowych wraz z ich punktami;
• wyjaśnienie AI, jeśli jest dostępne;
• przycisk Przelicz, który uruchamia scoring ponownie przez AJAX, bez przeładowania strony.

Wynik jest liczony automatycznie przy zatwierdzeniu zamówienia (hook actionValidateOrder) i odświeżany przy zmianach statusu (hook actionOrderStatusPostUpdate).

Pulpit logistyczny

Zakładka Wysyłka → Returns Predictor wymienia wszystkie ocenione zamówienia, posortowane według malejącego wyniku. Znajdziesz tam numer zamówienia, klienta, status, wynik, poziom i wskaźnik alertu. Filtruj po poziomie, aby wyodrębnić zamówienia wysokiego ryzyka przed przygotowaniem paczek. Akcja podglądu otwiera bezpośrednio kartę danego zamówienia.

Alert e-mail

Gdy zamówienie przekroczy przy tworzeniu próg wysokiego ryzyka, na skonfigurowany adres logistyki wysyłane jest podsumowanie: numer zamówienia, wynik, poziom, klient, czynniki składowe i ewentualna notatka AI. Szablony wiadomości są dostarczone w języku francuskim i angielskim, a wysyłka uwzględnia język klienta oraz sklep, z którego pochodzi zamówienie.

Zgodność i uwagi techniczne

• PrestaShop 8.0 do 9.x, multisklep i wielojęzyczność.
• Kontroler administracyjny legacy (bez kontrolera Symfony) dla zgodności z PS8 i PS9.
• Endpoint AJAX w panelu administracyjnym przez czwarty argument getAdminLink(); renderowanie JSON dedykowaną metodą.
• Tabela df_return_risk: jeden rekord na zamówienie, z wynikiem, poziomem, czynnikami (JSON) i wskaźnikiem alertu.
• Opcjonalna warstwa AI: do Mistral przekazywane są wyłącznie dane niezbędne do obliczenia; automatyczny powrót do heurystyki.

FAQ i rozwiązywanie problemów

Panel ryzyka nie pojawia się na karcie zamówienia. Sprawdź, czy moduł jest podpięty do hooka displayAdminOrderSide i czy zamówienie powstało po instalacji. Użyj przycisku przeliczenia, aby wymusić scoring.

Nie przychodzi żaden alert e-mail. Sprawdź, czy adres alertu jest uzupełniony i prawidłowy oraz czy zamówienie faktycznie przekracza próg Wysoki. Alert jest wysyłany tylko raz na zamówienie.

AI nie zwraca wyjaśnienia. Sprawdź klucz API i nazwę modelu Mistral. Moduł i tak przełącza się na wynik heurystyczny, żaden wynik nie zostaje utracony.

Czy wszyscy nowi klienci są traktowani jako ryzykowni? Nie. Brak historii dodaje tylko niewielki narzut; wynik zależy przede wszystkim od pozostałych czynników (bracketing, kategorie, wartość koszyka).