DfPreorder SW: kompletny przewodnik

Shopware nie oferuje natywnie żadnej funkcji “Powiadom mnie, gdy produkt wróci do magazynu”. DfPreorder SW wypełnia tę lukę: na każdej karcie produktu niedostępnego pojawia się automatycznie formularz zapisu, a klient otrzymuje alert e-mailem, w swoim własnym języku, gdy tylko produkt wróci. Plugin dodaje też lekki tryb przedsprzedaży (plakietka i przewidywana data wysyłki) oraz moduł administracji do śledzenia zapisów. Jeden i ten sam ZIP instaluje się na Shopware 6.5, 6.6 i 6.7. Ten przewodnik obejmuje instalację, kompilację zasobów, workera i zadanie cykliczne, konfigurację, użytkowanie w storefroncie, tryb przedsprzedaży, e-maile, Store API, zgodność z RODO i rozwiązywanie problemów.

Jak działa wykrywanie powrotu do magazynu

DfPreorder wykrywa uzupełnienia zapasów na dwa uzupełniające się sposoby, zbiegające się w tym samym idempotentnym przetwarzaniu, więc Twoi klienci są zawsze powiadamiani, nigdy dwukrotnie:

• W czasie rzeczywistym: subscriber nasłuchuje zapisu produktów i reaguje, gdy tylko zmienia się stan magazynowy lub stan dostępny.
• Zaplanowane skanowanie: zadanie cykliczne wykonuje się co 15 minut i nadrabia aktualizacje stanów wykonane bezpośrednio w SQL, typowo dekrementację stanu dostępnego przy złożeniu zamówienia albo import z ERP, które nie wyzwalają zdarzenia aplikacyjnego.

Formularz listy oczekujących wyświetla się na karcie produktu, gdy spełnione są dwa warunki: produkt jest w trybie “wyczerpany ukrywa dostępność” (closeout) oraz jego stan dostępny spadł do zera.

Instalacja

1. Pobierz archiwum DfPreorder-v1.0.0.zip ze swojego konta DataFirefly.
2. Skopiuj rozpakowany katalog DfPreorder do custom/plugins/ albo zainstaluj ZIP przez Administracja → Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie.
3. Zainstaluj i aktywuj plugin:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfPreorder

4. Skompiluj zasoby storefrontu i administracji (krok niezbędny, żaden dist nie jest dostarczany):

   ./bin/build-storefront.sh
   ./bin/build-administration.sh

5. Wyczyść cache:

   bin/console cache:clear

Przy instalacji plugin tworzy tabelę df_stock_notification, zestaw pól niestandardowych df_preorder na encji produktu, dwa szablony e-mail i zadanie cykliczne. Przy odinstalowaniu bez zachowania danych wszystko jest usuwane.

Worker i zadanie cykliczne

Aby e-maile rzeczywiście wychodziły, muszą działać dwa mechanizmy, co w produkcji zwykle jest już zapewnione przez admin-workera, systemd albo cron:

• Worker Messengera, który konsumuje asynchroniczną wiadomość o uzupełnieniu zapasu i wysyła e-maile;
• Planer zadań, który uruchamia skanowanie zabezpieczające co 15 minut.

bin/console messenger:consume async --time-limit=60
bin/console scheduled-task:run

Konfiguracja

Otwórz Rozszerzenia → Moje rozszerzenia → DataFirefly Przedsprzedaż i Lista Oczekujących → ⋯ → Konfiguruj. Wszystkie opcje można ustawiać per kanał sprzedaży dzięki natywnemu selektorowi u góry strony.

• Włącz listę oczekujących: główny przełącznik. Wyświetla formularz na kartach produktów niedostępnych.
• Double opt-in: wymaga potwierdzenia e-mailem przed aktywacją zapisu (zalecane pod RODO). Domyślnie wyłączone.
• Zezwól gościom: po wyłączeniu zapisać mogą się wyłącznie zalogowani klienci.
• Usuń zapis po powiadomieniu: minimalizacja danych, adres e-mail jest kasowany po wysłaniu alertu. Po wyłączeniu zapis jest zachowywany ze statusem “powiadomiony”.
• Powiadomienia partiami: maksymalna liczba e-maili wysyłanych na jedno wykonanie (worker lub skanowanie). Domyślnie 100.
• Pokaż plakietkę przedsprzedaży: włącza wyświetlanie plakietki i daty wysyłki na produktach skonfigurowanych jako przedsprzedaż.

Lista oczekujących w storefroncie

Gdy produkt jest niedostępny (closeout + stan dostępny równy zero), formularz “Powiadom mnie o powrocie do magazynu” wyświetla się automatycznie pod przyciskiem zakupu. Klient wpisuje swój e-mail (uzupełniony wstępnie, jeśli jest zalogowany) i zatwierdza.

• Wysłanie odbywa się przez AJAX z pełnym fallbackiem bez JavaScriptu (komunikat flash + przekierowanie).
• Niewidoczne pole honeypot filtruje boty.
• Przy włączonym double opt-in wysyłany jest e-mail potwierdzający; zapis staje się aktywny dopiero po kliknięciu w link potwierdzający.
• Każdy e-mail może zawierać link wypisu jednym kliknięciem.

Tryb przedsprzedaży

Plugin tworzy grupę pól niestandardowych Przedsprzedaż na encji produktu. Otwórz produkt w Katalogi → Produkty, zakładka Specyfikacje → Pola niestandardowe, grupa Przedsprzedaż:

• Włącz przedsprzedaż: przełącznik aktywacji dla tego produktu.
• Przewidywana data wysyłki: data wyświetlana w plakietce.
• Notatka przedsprzedaży: dowolny tekst wyświetlany pod plakietką.

Gdy przedsprzedaż jest włączona, a plakietka dozwolona w konfiguracji, nad przyciskiem zakupu wyświetla się bursztynowa plakietka z przewidywaną datą wysyłki. Rendering jest wydzielony w szablonie buy-widgetu i pozostaje nadpisywalny.

E-maile i tłumaczenia

Przy instalacji tworzone są dwa szablony e-mail, przetłumaczone na pięć języków: francuski, angielski, niemiecki, hiszpański i włoski:

• Powrót do magazynu (df_preorder.back_in_stock): zmienne productName, productUrl i pełny obiekt product.
• Potwierdzenie zapisu (df_preorder.double_opt_in): dodaje zmienną confirmUrl.

Każdy klient jest powiadamiany w języku sklepu z chwili swojego zapisu: plugin odtwarza kontekst języka właściwy dla subskrybenta, aby rozwiązać przetłumaczoną nazwę produktu i właściwy szablon. Adres URL produktu jest rozwiązywany przez kanoniczny URL SEO danego kanału i języka.

Szablony pozostają w pełni edytowalne w Ustawienia → E-maile → Szablony e-mail. Wyszukaj “powrót do magazynu” albo “back in stock”, aby je odnaleźć.

Moduł administracji

Menu Marketing → Lista Oczekujących i Przedsprzedaż wyświetla wszystkie zapisy: adres e-mail, produkt, status (oczekujący / potwierdzony / powiadomiony), datę zapisu i datę powiadomienia. Dostępne jest usuwanie masowe, przydatne do ręcznego czyszczenia starych zapisów.

Store API (headless / mobile)

Dla sklepów headless i aplikacji mobilnych punkt wejścia Store API pozwala zapisać klienta na listę oczekujących:

POST /store-api/df-waitlist/subscribe
Content-Type: application/json
sw-access-key: <your-access-key>

{
  "productId": "0189a1b2c3d4...",
  "email": "client@example.com"
}

Poprawne żądanie zwraca odpowiedź sukcesu; nieprawidłowy identyfikator produktu lub e-mail zwraca błąd 400. Obowiązują te same reguły konfiguracji (double opt-in, zezwolenie dla gości itd.).

Zgodność z RODO

• Adresy e-mail są zbierane wyłącznie na potrzeby zamówionego powiadomienia.
• Opcjonalny double opt-in rejestruje wyraźną zgodę.
• Domyślne zachowanie usuwa dane osobowe zaraz po wysłaniu alertu.
• Link wypisu jednym kliknięciem można wstawić w szablonach e-mail.
• Odinstalowanie z usunięciem danych kasuje tabelę, szablony, pola niestandardowe i konfigurację.

Zgodność 6.5 → 6.7 i rozwiązywanie problemów

Formularz nie wyświetla się na niedostępnym produkcie. Sprawdź, czy opcja “Włącz listę oczekujących” jest zaznaczona dla właściwego kanału sprzedaży, czy produkt jest w trybie closeout i czy jego stan dostępny wynosi zero. Wyczyść cache po każdej zmianie konfiguracji.

Zapisy są rejestrowane, ale żaden e-mail nie wychodzi. Worker Messengera i/lub planer zadań nie działają. Uruchom je ręcznie w celu testu (patrz sekcja Worker), a następnie zapewnij ich ciągłe działanie w produkcji.

Błąd serwisu mail przy aktywacji na Shopware 6.7. Abstrakcyjna klasa serwisu mail została zastąpiona klasą konkretną w 6.7. Plugin obsługuje tę różnicę automatycznie przez compiler pass tworzący odpowiedni alias; zwykłe cache:clear przekompilowuje kontener, jeśli błąd utrzymuje się po aktualizacji.

E-mail wychodzi w złym języku. Przyjmowany jest język kanału sprzedaży z momentu zapisu. Sprawdź, czy dany kanał ma oczekiwany język i czy szablon e-maila ma tłumaczenie dla tego języka.

E-maile wyglądają na wysłane podwójnie. To nie powinno się zdarzać: przetwarzanie jest idempotentne i oznacza (albo usuwa) każdy zapis po wysyłce. Jeśli to obserwujesz, sprawdź, czy nie uruchamiasz kilku równoległych workerów bez odpowiedniej konfiguracji transportu.

Co dzieje się przy odinstalowaniu? Z opcją usunięcia danych tabela df_stock_notification, dwa szablony e-mail, zestaw pól df_preorder, zadanie cykliczne i konfiguracja są usuwane. Bez tej opcji wszystko jest zachowywane na potrzeby późniejszej ponownej instalacji.