# 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…

- Strona: <https://www.datafirefly.com/pl/documentation/ai-returns-predictor/>
- Język: pl
- Zaktualizowano: 2026-07-31
- Inne języki: [fr](https://www.datafirefly.com/documentation/ai-returns-predictor/index.md), [en](https://www.datafirefly.com/en/documentation/ai-returns-predictor/index.md), [es](https://www.datafirefly.com/es/documentation/ai-returns-predictor/index.md), [de](https://www.datafirefly.com/de/documentation/ai-returns-predictor/index.md), [it](https://www.datafirefly.com/it/documentation/ai-returns-predictor/index.md), [nl](https://www.datafirefly.com/nl/documentation/ai-returns-predictor/index.md), [pt](https://www.datafirefly.com/pt/documentation/ai-returns-predictor/index.md)
- Indeks: <https://www.datafirefly.com/pl/documentation/llms.txt>

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**.

Zgodny z PrestaShop 8.0 do 9.x, na PHP 7.4 do 8.3. Bez override motywu i bez zależności Composera. Zgodny z multisklepem i wielojęzyczny.

## 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.

Alert jest wysyłany tylko raz na zamówienie, przy pierwszym wykryciu wysokiego ryzyka. Późniejsze przeliczenia nie generują kolejnego e-maila.

### 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`.

W razie błędu sieci, niedostępności API lub przekroczenia limitu czasu (8 s) moduł automatycznie wraca do wyniku heurystycznego. Scoring nigdy nie blokuje przygotowania zamówień.

## 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.

Każdy czynnik pokazuje swój wkład w punktach na karcie zamówienia, dzięki czemu wynik jest w pełni przejrzysty, bez czarnej skrzynki.

## 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.

Moduł informuje i ostrzega, ale nigdy nie zmienia statusu zamówienia ani nie wstrzymuje wysyłki. Decyzja końcowa pozostaje po stronie człowieka.

## 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).