Dokumentacja DfStreamCategoryTree dla Shopware 6

DfStreamCategoryTree dodaje pole Category (including subcategories) do kreatora warunków dynamicznych grup produktów Shopware 6. Filtrowanie po kategorii nadrzędnej obejmuje wtedy wszystkie produkty przypisane do jej podkategorii, niezależnie od głębokości.

Problem, który rozwiązuje wtyczka

Natywny kreator warunków udostępnia pole Categories, które odpytuje asocjację product.categoriesRo. Ta asocjacja zawiera wyłącznie kategorie, do których produkt został jawnie przypisany w swojej zakładce Categories.

Poprawnie zorganizowany katalog przypisuje produkty do kategorii liści. Model sneakersów znajduje się w Mężczyźni / Obuwie / Sneakersy, a nie w Mężczyźni. Filtr na Mężczyźni zwraca zatem tylko nieliczne produkty przypisane bezpośrednio na tym poziomie, często żadnego.

Natywne obejście polega na ręcznym zaznaczeniu każdej podkategorii i ponownym otwieraniu konfiguracji strumienia przy każdej zmianie drzewa. Ta wtyczka usuwa tę pracę utrzymaniową.

Jak to działa

Shopware utrzymuje już dla każdego produktu pole JSON o nazwie categoryTree, zawierające identyfikatory wszystkich kategorii ścieżki, od korzenia aż po kategorię przypisania. Natywny CategoryIndexer przelicza je przy każdym przeniesieniu kategorii i każdej zmianie przypisania produktu.

Filtr equalsAny na tym polu z identyfikatorem kategorii nadrzędnej zwraca więc wszystkie produkty, których ścieżka przez nią przebiega. Pole istnieje i działa bez zarzutu w DAL, ale administracja nie udostępnia go w selektorze kreatora warunków: nie występuje na liście dozwolonych pól usługi productStreamConditionService.

Wtyczka dodaje jeden wpis do tej listy i dostarcza odpowiadające mu przetłumaczone etykiety. Nie wprowadza żadnego dekoratora usługi, żadnego nasłuchiwacza zdarzeń produktu, żadnej tabeli ani żadnej migracji.

Wymagania

• Shopware 6.7.x we własnym hostingu
• PHP 8.2 lub nowszy
• Dostęp do wiersza poleceń lub pipeline wdrożeniowy zdolny przebudować administrację

Wtyczka nie działa na Shopware Cloud, ponieważ wersja SaaS hostowana przez Shopware nie pozwala instalować wtyczek serwerowych.

Instalacja

Przez wgranie ZIP

1. W administracji otwórz Extensions, a następnie My extensions
2. Kliknij Wgraj rozszerzenie i wybierz archiwum DfStreamCategoryTree-1.0.0.zip
3. Zainstaluj i aktywuj wtyczkę
4. Przebuduj administrację (patrz następna sekcja)

Przez wgranie katalogu

Rozpakuj archiwum do katalogu własnych wtyczek swojej instancji, a następnie wykonaj:

bin/console plugin:refresh
bin/console plugin:install --activate DfStreamCategoryTree
bin/console cache:clear

Przebudowa administracji

Wtyczka zmienia zachowanie interfejsu administracyjnego. Po instalacji konieczna jest jednorazowa przebudowa bundla admin, bez niej nowe pole nie pojawi się w selektorze warunków.

bin/console bundle:dump
./bin/build-administration.sh
bin/console cache:clear

W środowisku produkcyjnym zarządzanym przez pipeline wdrożeniowy ten krok zwykle jest już częścią standardowego procesu. Następnie wyczyść pamięć podręczną przeglądarki lub otwórz administrację w oknie prywatnym, aby mieć pewność wczytania zaktualizowanego bundla.

Użycie

Tworzenie rekurencyjnej grupy dynamicznej

1. Otwórz Katalogi, a następnie Dynamic product groups
2. Utwórz nową grupę lub otwórz istniejącą
3. W kreatorze warunków rozwiń selektor pola
4. Wybierz Category (including subcategories), tuż nad oryginalnym wpisem Categories
5. Wybierz operator Is equal to any of
6. Wskaż jedną lub kilka kategorii nadrzędnych w polu wartości
7. Zapisz, a następnie otwórz zakładkę Preview, aby sprawdzić liczbę zwróconych produktów

Dostępne operatory

• Is equal to any of: produkt należy do poddrzewa co najmniej jednej z wybranych kategorii
• Is not equal to any of: produkt nie należy do żadnego z wybranych poddrzew, przydatne do wykluczenia całego działu z akcji promocyjnej

Łączenie z innymi warunkami

Pole zachowuje się jak każdy inny warunek strumienia. Łączy się swobodnie z producentem, ceną, stanem magazynowym, właściwościami i tagami oraz działa w zagnieżdżonych grupach AND i OR kreatora.

Typowa konfiguracja wyprzedaży: Category (including subcategories) is equal to any of Mężczyźni, ORAZ Stock is greater than 0, ORAZ Price is greater than 50.

Gdzie można wykorzystać grupę

• Strony kategorii nawigacyjnych zasilane grupą dynamiczną
• Bloki produktowe w Shopping Experiences
• Warunki reguł promocyjnych
• Automatyczny cross-selling na karcie produktu
• Każda integracja konsumująca product stream przez Admin API lub Store API

Użycie przez Admin API

Ponieważ pole jest natywne dla DAL, warunek wysłany bezpośrednio przez API działa nawet bez wtyczki. Wtyczka służy do udostępnienia filtra w interfejsie i umożliwienia jego edycji, co ma znaczenie, gdy zespół marketingu zarządza grupami bez korzystania z API.

POST /api/product-stream
{
  "name": "Caly dzial Mezczyzni",
  "filters": [
    {
      "type": "equalsAny",
      "field": "product.categoryTree",
      "value": "01920f7c8a3d71c2b4e5f6a7b8c9d0e1"
    }
  ]
}

Bez zainstalowanej wtyczki strumień zawierający ten filtr nadal działa na poziomie DAL, ale jego pole nie może zostać wyświetlone w kreatorze warunków.

Rozwiązywanie problemów

Pole nie pojawia się w selektorze

W zdecydowanej większości przypadków administracja nie została przebudowana po instalacji. Wykonaj ponownie sekwencję bundle:dump, build-administration i cache:clear, a następnie przeładuj administrację z wyczyszczoną pamięcią podręczną przeglądarki. Sprawdź też w Extensions i My extensions, czy wtyczka jest aktywna.

Grupa nadal zwraca niewłaściwe produkty

Upewnij się, że wybrano nowe pole, a nie oryginalny wpis Categories, ponieważ oba współistnieją w selektorze. Następnie otwórz oczekiwany produkt i sprawdź, czy jest przypisany do podkategorii wybranej kategorii nadrzędnej oraz czy jest aktywny i widoczny w danym kanale sprzedaży.

Niedawno przeniesiony produkt nie pojawia się

Pole categoryTree jest przeliczane przez natywny CategoryIndexer. Jeśli kolejka wiadomości ma opóźnienie lub indeksowanie zostało wstrzymane, wymuś ponowne indeksowanie:

bin/console dal:refresh:index --only=product.indexer,category.indexer

Reset po aktualizacji Shopware

Po podniesieniu wersji pomocniczej Shopware przebuduj administrację, aby wtyczka ponownie zarejestrowała swój wpis na liście dozwolonych pól. Nic więcej nie jest potrzebne, ponieważ wtyczka nie przechowuje żadnych danych.

Odinstalowanie

Dezaktywuj, a następnie odinstaluj wtyczkę z poziomu Extensions lub wiersza poleceń. Wtyczka nie tworzy żadnej tabeli i nie zapisuje konfiguracji, więc odinstalowanie jest całkowicie neutralne.

bin/console plugin:deactivate DfStreamCategoryTree
bin/console plugin:uninstall DfStreamCategoryTree

Grupy dynamiczne skonfigurowane już z tym filtrem działają dalej: warunek jest zapisany jako standardowy filtr DAL i pozostaje przetwarzany przez natywny silnik. Znika jedynie wyświetlanie pola w kreatorze warunków, przez co filtr nie jest edytowalny z poziomu interfejsu do czasu ponownej aktywacji wtyczki. Żadne dane nie zostają utracone.

Znane ograniczenia

• Wtyczka nie dotyczy filtrów listingu w storefront ani nawigacji fasetowej, które opierają się na odrębnym mechanizmie
• Nie zmienia algorytmu indeksowania kategorii, korzysta z pola, które Shopware i tak wytwarza
• Nie działa na Shopware Cloud