Przejdź do głównej zawartości

Feedy produktowe

Moduł product_feeds zamienia katalog jednego kanału sprzedaży w plik feedu w formacie dostawcy — dokument XML dla Google Merchant Center, katalog Meta, plik płaski dla marketplace'u — publikuje go pod stałym adresem URL z tokenem, który dostawca pobiera anonimowo, i generuje go ponownie według harmonogramu ustawionego osobno dla każdego feedu.

Feedy opuszczają platformę na dwa sposoby. Pobieranie (pull) jest sposobem pierwotnym i nadal domyślnym: dostawca pobiera adres URL z tokenem albo administrator pobiera plik. Wysyłka (push) pojawiła się później — każde udane generowanie może też wysłać plik na serwer partnera przez SFTP, FTP lub HTTP. Oba sposoby są od siebie niezależne, więc feed może korzystać z obu.

Dla operatorów​

Z czego składa się feed​

Przy tworzeniu feed to cztery wybory i nic więcej:

WybórZnaczenie
SzablonJakie pola zawiera plik, w jakiej kolejności i w jakim formacie (XML, CSV, TSV).
Kanał sprzedażyKtóry katalog publikuje feed. Od kanału zależą też ceny i linki.
JęzykW którym tłumaczeniu zapisywane są nazwy, opisy i ścieżki kategorii.
NazwaPo czym rozpoznasz feed. Publiczny adres URL wynika z feedu, a nie z nazwy.

Wszystko inne — kryteria, harmonogram, sposób prezentacji ceny, cennik, kraj opodatkowania — ma działającą wartość domyślną i można to zmienić później na karcie Settings feedu.

Tworzenie pierwszego feedu​

  1. Przejdź do Sales channels → Product feeds i kliknij New feed.
  2. Wybierz szablon Google Merchant Center, kanał, w którym sprzedajesz ten katalog, oraz język. W trakcie wybierania ekran pokazuje ustawienia, które z tego wynikają (walutę, sposób prezentacji ceny).
  3. Zapisz, a następnie kliknij Generate now na stronie feedu.
  4. Gdy generowanie się zakończy, karta Feed link pokaże adres URL. Wklej go w Merchant Center jako zaplanowane pobieranie.

Do pierwszego udanego generowania celowo nie ma na ekranie adresu URL: link, który odpowiada 404, jest gorszy niż brak linku.

Pięć dostarczanych szablonów​

Nie są równoważne, a różnicę widać, zanim wybierzesz któryś z nich.

SzablonFormatSzczegółowośćStan
Google Merchant CenterXML (RSS 2.0 + g:)Dla każdego wariantuGotowy do użycia
Katalog MetaXMLDla każdego wariantuGotowy do użycia
Plik płaski AmazonTSVDla każdego produktuPunkt wyjścia
eBayCSVDla każdego produktuPunkt wyjścia
AllegroCSVDla każdego produktuPunkt wyjścia

„Gotowy do użycia” oznacza, że lista pól obejmuje cały zestaw pól wymaganych przez danego dostawcę. „Punkt wyjścia” oznacza, że szablon zawiera tylko identyfikator, cenę, dostępność, link i zdjęcie — pola potrzebne każdemu marketplace'owi — a atrybuty specyficzne dla danego marketplace'u należy dodać samodzielnie w edytorze szablonu. Trzy szablony marketplace'ów są dostarczane jako szkielety, bo ta wersja nie ma integracji z ich API, więc dokładny zestaw wymaganych pól zależy od konta.

Szablonów systemowych nie można edytować. Użyj Duplicate i edytuj kopię; oryginał pozostaje taki, jakim dostarczyła go platforma, a usunięty szablon systemowy zostaje przywrócony przy następnym uruchomieniu.

Tworzenie i edycja szablonu​

Sales channels → Feed templates → New template albo Duplicate. Edytor to wizualna lista pól wyjściowych: każdy wiersz ma postać nazwa wyjściowa ← źródło, z opcjonalną wartością zastępczą i flagą „wymagane przez dostawcę”.

  • Powiązania się wybiera, a nie wpisuje. Lista źródeł pokazuje to, co istnieje w tej instalacji — pola produktu, atrybuty i pola niestandardowe, zdjęcia, ceny, ścieżki kategorii, kategorię dostawcy. Źródło, którego bieżący format wyjściowy nie potrafi wyrazić, jest pokazywane jako nieaktywne wraz z powodem, a nie ukrywane.
  • Kolejność można zmieniać samą klawiaturą. Chwyć wiersz klawiszem Space, przesuń go strzałkami ↑/↓ lub Alt+↑/↓, upuść klawiszem Space, anuluj klawiszem Escape. Każde przesunięcie jest ogłaszane czytnikowi ekranu. Na urządzeniach dotykowych każdy wiersz ma osobne przyciski przesuwania, a długie listy oferują ⋮ → Move to position….
  • Podgląd ocenia wersję roboczą. Wybierz przykładowy produkt i zobacz dla każdego pola wartość, którą zawierałby plik, jej pochodzenie (źródło lub wartość zastępcza) oraz to, czy pozycja zostałaby wysłana, czy pominięta. Podgląd niczego nie zapisuje — ani generowania, ani wpisu w dzienniku audytu.
  • Problemy są pokazywane na bieżąco, na pasku nad listą. Przycisk Save nigdy nie jest wyłączany z powodu błędu walidacji; zamiast tego mówi, co jest nie tak.
  • Usunięcie pola wymaganego przez dostawcę wymaga jednego potwierdzenia, w którym podana jest konsekwencja. Taka zmiana nie jest ani po cichu akceptowana, ani blokowana.

Szablony przenosi się między instalacjami jako JSON: Export… przy szablonie, Import na liście szablonów. Dokument nie zawiera identyfikatorów, znaczników czasu, tokenów ani powiązań z feedami, więc dwukrotny eksport niezmienionego szablonu daje pliki identyczne co do bajtu. Pole, którego źródło nie istnieje w docelowej instalacji, jest importowane jako niepowiązane i zgłaszane; generowanie feedu opartego na szablonie z niepowiązanymi polami kończy się błędem, który wymienia każde z nich, zamiast publikować plik z lukami.

Zawężanie feedu do części katalogu​

Sekcja Criteria na karcie Settings to ten sam kreator reguł, którego używają promocje. Pusta reguła oznacza „każdy kwalifikujący się produkt tego kanału”. Kryterium kategorii obejmuje całe jej poddrzewo.

Podczas edycji panel pokazuje bieżącą liczbę dopasowań. Jest ona liczona na podstawie tych samych cen i tego samego zawężenia do kanału, których użyje następne generowanie, więc to liczba pozycji, które generowanie weźmie pod uwagę — a nie szacunek.

Dwóch rzeczy reguła nigdy nie zrobi:

  • nie poszerzy feedu. Produkt aktywny, niezarchiwizowany, należący do kanału tego feedu i widoczny dla anonimowego odwiedzającego — to minimum, którego żadne kryterium nie obniży. „Widoczny dla anonimowego odwiedzającego” to pełny warunek, a nie tylko przełącznik public: produkt publiczny, ale zarezerwowany dla wskazanych organizacji, nie trafia do feedu, bo plik pobiera Google, a link, którego nikt spoza tych organizacji nie otworzy, reklamuje stronę 404 — i zdradza istnienie asortymentu, który ktoś inny dostał na wyłączność;
  • nie dopasuje po cichu wszystkiego. Kryterium wskazujące atrybut, który został w międzyczasie usunięty, kończy generowanie błędem konfiguracji, zamiast po cichu dopasować cały katalog.

Jeśli reguła nic nie dopasuje, generowanie kończy się stanem empty, a wcześniej opublikowany plik jest nadal udostępniany. Panel ostrzega o tym przed zapisem, a nie po nim.

Ceny w feedzie​

Feed publikuje ceny, które w jego kanale sprzedaży zobaczyłby każdy — feed pobiera dostawca, który nie jest niczyim kupującym, więc żadna cena kontraktowa organizacji ani grupy klientów nigdy do niego nie trafia. Każdy produkt jest wyceniany dla ilości 1, w walucie feedu, przez cenniki (moduł price_lists): jego cena bazowa albo cena z cennika katalogowego dla wszystkich w kanale, albo cena promocyjna, gdy jest niższa. Produkt bez ceny w walucie feedu jest pomijany z powodem missing_price. Pozycje feedu to produkty: produkt z wariantami jest publikowany w cenie samego produktu, a nie osobno dla każdego wariantu.

Cena jest zapisywana z dwoma miejscami po przecinku. Feed brutto — domyślna prezentacja — dolicza do ceny netto stawkę podatku kraju podatkowego feedu i zaokrągla dokładny wynik połówkowo w górę: 29,50 przy 23 % trafia do pliku jako 36.29, ta sama cena brutto, którą storefront pokazuje obok tej samej ceny netto. Cena z więcej niż dwoma miejscami po przecinku nigdy nie jest zaokrąglana — zob. Cena poniżej jednego grosza niżej.

Cena poniżej jednego grosza​

Cennik przechowuje do czterech miejsc po przecinku, więc wkręt może kosztować 0,0125 zł. Feed nie potrafi tego wyrazić: Google Merchant Center przyjmuje najwyżej dwa miejsca po przecinku i sam zaokrągla dłuższą cenę, więc 0,0125 zł trafiłoby do reklamy jako 0,01 zł, podczas gdy strona produktu pokazuje 0,0125 zł — niezgodność ceny, za którą Google odrzuca produkty. Dlatego feed publikuje taki produkt jako opakowanie:

  • cena jest ceną N sztuk, gdzie N to najmniejsza z liczb 10, 100, 1 000 i 10 000, przy której cena jest dokładna co do grosza — 0,0125 zł trafia do pliku jako 100 sztuk za 1,25 zł, 9,045 zł jako 10 sztuk za 90,45 zł. Po drodze nic nie jest zaokrąglane;
  • feed brutto dolicza podatek do ceny netto opakowania, tak jak naliczana jest pozycja koszyka z tyloma sztukami: 1,25 zł przy 23 % trafia do pliku jako 1,54 zł;
  • cena i cena przed obniżką jednego produktu dotyczą tego samego opakowania — większego z tych, których wymaga każda z nich;
  • wielkość opakowania trafia do pól opakowania szablonu. Szablon Google Merchant Center ma ich trzy: g:multipack (N) oraz g:unit_pricing_measure i g:unit_pricing_base_measure (oba 100ct dla opakowania 100 sztuk), więc Google pokazuje cenę jednostkową jako 1,25 zł / 100 ct — dokładną cenę opakowania — a nie zaokrągloną cenę za sztukę. Opakowanie 1 000 albo 10 000 sztuk, którego wymaga tylko cena z pięcioma albo sześcioma miejscami po przecinku, ma samo g:multipack: podstawa ceny jednostkowej w Google przyjmuje 1, 10 albo 100 sztuk;
  • każde pole opakowania jest puste, więc pomijane w pliku, dla produktu, którego cena ma dwa miejsca po przecinku. Takie produkty są publikowane dokładnie tak jak wcześniej.

Szablon bez pola powiązanego ze źródłem Wielkość opakowania (ceny poniżej grosza) nie potrafi powiedzieć, czego ceną jest taka cena, więc produkt jest pomijany w tym feedzie, a wynik generowania wymienia go pod sub_cent_price_without_pack_field, podając cenę i potrzebne opakowanie. Dotyczy to szablonu katalogu Meta i trzech punktów wyjścia dla marketplace'ów — ta wersja nie publikuje do tych dostawców opakowań zbiorczych — oraz kopii szablonu Google zrobionej przed 0.109.0. Aby publikować takie produkty we własnym szablonie, dodaj w edytorze szablonu pole ze źródłem Wielkość opakowania (ceny poniżej grosza) z grupy Cena i stan magazynowy — oraz dwa źródła opakowania jako liczby sztuk, jeśli dostawca przyjmuje pola ceny jednostkowej Google. Cena, która wymagałaby opakowania większego niż 10 000 sztuk, jest pomijana z sub_cent_price_beyond_pack_limit; cztery miejsca po przecinku z cennika nigdy go nie wymagają.

Dotyczy to każdego feedu; nie ma na to ustawienia. Strona produktu w storefroncie pokazuje cenę jednej sztuki; zasady Google dla opakowań zbiorczych wymagają, by strona docelowa pokazywała też cenę opakowania, więc obserwuj diagnostykę Merchant Center dla produktów publikowanych w ten sposób.

Feed można zamiast tego przypiąć do jednego cennika: wybierz go w polu Cennik w sekcji Ceny na karcie Ustawienia feedu albo ustaw pole priceListId feedu przez API administracyjne (POST /api/v1/admin/product-feeds, PATCH /api/v1/admin/product-feeds/:id). Lista podpowiada cenniki w walucie feedu; te, które nie publikowałyby teraz dla feedu, są wyszarzone, z powodem obok nazwy, a Bez cennika odpina feed. Cennik, do którego feed jest już przypięty, pozostaje do wyboru niezależnie od swojego stanu. Wybór cennika wymaga uprawnienia do przeglądania cenników oraz do edycji feedów produktowych; bez niego pole wyboru jest wyłączone i mówi, którego uprawnienia brakuje. Pole wyboru odczytuje GET /api/v1/admin/product-feeds/:id/price-book-options (product_feeds:read i price_lists:read): każdy cennik w walucie feedu, a także przypięty cennik niezależnie od waluty, każdy z unpublishableReason (null, gdy by publikował). Przypięty feed publikuje wtedy własne linie tego cennika — ceny stałe oraz procenty i korekty liczone od ceny katalogowej, jaką kanał naliczałby bez tego cennika — a produkt, którego cennik nie wycenia, nie trafia do feedu. Cennik cen bazowych publikuje swoje ceny bazowe. Przypięty cennik jest publikowany tylko wtedy, gdy w chwili generowania obowiązuje kogokolwiek w kanale feedu:

  • ma status Aktywny albo Zaplanowany, a generowanie przypada między jego datą początku i końca;
  • jest przypisany do kanału sprzedaży feedu, a kanał sprzedaje w walucie feedu (cennik cen bazowych nie potrzebuje kanału);
  • jest dla wszystkich — cennik dla wybranych organizacji albo grup klientów nigdy nie jest publikowany, z tego samego powodu, dla którego cena organizacji nigdy nie trafia do feedu nieprzypiętego;
  • jest w walucie feedu i nadal istnieje.

Dopóki któryś z tych warunków nie jest spełniony, strona feedu pokazuje ostrzeżenie, które go nazywa, a feed nie publikuje żadnych cen z tego cennika. Gdy generowanie stwierdzi, że przypięty cennik nie obowiązuje, wycofuje opublikowany plik feedu zamiast wygenerować nowy: generowanie kończy się stanem Wycofany, z powodem na swojej stronie, a najpóźniej po minucie link feedu odpowiada tak jak dla feedu, który nigdy nie został wygenerowany — dopóki cennik znów nie zacznie obowiązywać i kolejne generowanie nie opublikuje nowego pliku. Nie jest to generowanie zakończone błędem — nie ma powiadomienia o błędzie, nic nie jest dostarczane — a ostatni poprawny plik celowo nie jest dalej udostępniany. Wycofany plik nie jest usuwany: nadal można go pobrać z generowania, które go utworzyło, a zwykła retencja usuwa go po następnej publikacji. Dopóki ostatnim generowaniem feedu jest wycofanie, strona feedu informuje, że plik został wycofany. Liczba dopasowań w Criteria i kryterium zakresu cen korzystają z tych samych cen, które opublikuje następne generowanie.

Mapowanie kategorii (Google i Meta)​

Obaj dostawcy posługują się własną taksonomią produktów. Platforma dostarcza te taksonomie (5 595 kategorii Google i 2 967 kategorii Meta, każdą po angielsku i po polsku), więc generowanie feedu nigdy nie zależy od połączenia z Google ani Meta.

Ekran mapowania otworzysz z palety poleceń (⌘K / CTRL+K → Feed category mapping). Zmapuj kategorię sklepu na węzeł dostawcy, a każda kategoria podrzędna to odziedziczy, chyba że ma własne mapowanie; gdy zastosowanie ma kilka przypisanych kategorii, wygrywa — deterministycznie — najgłębsza zmapowana. Pasek pokrycia pokazuje, ile kategorii jest zmapowanych, ile dziedziczy mapowanie, a ile nie ma go wcale.

  • Kategoria bez mapowania nie jest błędem: pole jest pomijane, a pozycja i tak trafia do pliku, z ostrzeżeniem w generowaniu, żebyś mógł ją odnaleźć.
  • Gdy zacznie obowiązywać nowsza wersja taksonomii, a zmapowany przez Ciebie węzeł już nie istnieje, mapowanie zostaje zachowane i oznaczone jako nieaktualne — nigdy nie jest zastępowane zgadywaniem ani usuwane. Ekran wyświetla nieaktualne mapowania do przejrzenia. Wersja zaczyna obowiązywać dopiero wtedy, gdy zatwierdzisz ją na ekranie Aktualizacje taksonomii; sama instalacja wersji niczego nie zmienia.
  • Powyżej 1 000 kategorii sklepu ekran zamiast drzewa pokazuje stronicowaną płaską listę pogrupowaną według kategorii nadrzędnej, z tymi samymi wierszami i tym samym paskiem pokrycia.

Aktualizacje taksonomii​

Google i Meta reorganizują swoje listy kategorii raz lub dwa razy w roku. Platforma potrafi sprawdzić, czy jest nowsza lista, i ją zainstalować — a zainstalowanie jej niczego nie zmienia, dopóki tego nie zatwierdzisz.

Domyślnie sprawdzanie jest wyłączone, a stan wyłączony jest w pełni obsługiwany. Przy wyłączonym przełączniku platforma nie wysyła żadnych żądań na zewnątrz: nie ma sprawdzania według harmonogramu, sprawdzania ręcznego ani próby połączenia przy starcie. Wiele instalacji celowo działa w ten sposób, a instalacja odcięta od sieci (air-gapped) musi tak działać. Włączenie to jedno ustawienie na ekranie, który przed przełączeniem podaje dokładne adresy, z którymi platforma będzie się łączyć.

Włączanie. Settings → Taxonomy updates (product_feeds_taxonomy):

UstawienieDziałanie
Check for new taxonomy revisionsGłówny przełącznik. Domyślnie wyłączony.
When to checkWyrażenie cron interpretowane w strefie UTC. Domyślnie poniedziałek, 04:00. Te listy zmieniają się raz lub dwa razy w roku, więc częstsze sprawdzanie nic nie daje.
Google / Meta category list (English, Polish)Cztery adresy, z których pobierane są pliki. Jeśli platforma nie może połączyć się z dostawcami bezpośrednio, wskaż wewnętrzną kopię lub serwer proxy — to obsługiwane rozwiązanie dla wdrożenia za serwerem proxy. Tylko https.
Category lists kept per providerIle wersji przechowywać. Lista używana, najnowsza lista, o której nikt jeszcze nie zdecydował, oraz każda lista zawierająca kategorię, na którą wskazuje któreś z Twoich mapowań, nigdy nie są usuwane, niezależnie od tej wartości.

Co robi sprawdzenie. Pobiera oba pliki językowe dostawcy, sprawdza, czy rzeczywiście są listą kategorii, i porównuje je z tym, co już masz. Jeśli lista faktycznie się różni, zostaje zainstalowana jako nieaktywna: Twoje feedy nadal korzystają z dotychczasowej listy, status żadnego mapowania się nie zmienia, a jedynym widocznym skutkiem jest nowy wiersz na ekranie Product feeds → Taxonomy updates (⌘K / CTRL+K → Taxonomy updates). Jeśli plik się nie zmienił, nic nie powstaje.

Jak czytać wynik sprawdzenia. Ekran wyświetla każde sprawdzenie z jego wynikiem, a gdy coś poszło nie tak — z powodem sformułowanym tak, by było jasne, po czyjej stronie leży problem:

PowódZnaczenie
transportTen serwer nie mógł połączyć się z dostawcą — zwykle z powodu braku dostępu do internetu, serwera proxy lub zapory sieciowej. Wskaż jako adres źródła serwer proxy lub wewnętrzną kopię pliku.
not_foundDostawca nie publikuje już pliku pod tym adresem. Znajdź aktualny adres w jego dokumentacji i zaktualizuj ustawienie. To jedyny błąd, który wywołuje powiadomienie — raz przy przejściu w stan błędu, a nie przy każdym sprawdzeniu.
http_statusDostawca odpowiedział błędem. Zwykle jest to chwilowy problem po jego stronie; następne sprawdzenie spróbuje ponownie.
not_taxonomyPod adresem jest strona internetowa — często ekran logowania albo komunikat serwera proxy. Otwórz adres w przeglądarce, żeby zobaczyć, co faktycznie zwraca.
empty / truncated / too_largePobrany plik był pusty, niekompletny albo większy, niż platforma akceptuje. Nic nie zostało zainstalowane.
no_nodes / implausiblePlik został pobrany, ale nie udało się odczytać z niego żadnych kategorii albo odczytano ich zdecydowanie za mało. Nic nie zostało zainstalowane.
incomplete_languagesPlik w jednym języku został pobrany, a w drugim nie. Lista jest instalowana tylko wtedy, gdy oba pliki są kompletne.

W każdym z tych przypadków feedy pozostają nienaruszone i nadal korzystają z już zainstalowanej listy. Nieudane sprawdzenie nigdy nie powoduje błędu generowania ani startu i nigdy nie ponawia prób lawinowo — ponowną próbą jest następne zaplanowane sprawdzenie, a przycisk Check now jest dla niecierpliwych.

Zatwierdzanie. Wersja zaczyna obowiązywać dopiero po zatwierdzeniu, a do przycisku zatwierdzenia można dojść wyłącznie przez podgląd skutków. Podgląd jest liczony na Twoich rzeczywistych danych i mówi to, co naprawdę musisz wiedzieć: ile Twoich mapowań wymagałoby wskazania nowej kategorii, ile znowu zaczęłoby działać i — co najważniejsze — ile kategorii sklepu w ogóle przestałoby wysyłać kategorię dostawcy, łącznie z tymi, które dziedziczą mapowanie po kategorii nadrzędnej. Zatwierdzenie jest audytowane, atomowe i odwracalne: powrót do wcześniejszej listy to ta sama akcja wykonana na wcześniejszym wierszu.

Żądanie przenosi liczby, które zobaczyłeś w podglądzie, więc jeśli ktoś inny zmieni mapowania, gdy Twój podgląd jest otwarty, zatwierdzenie zostanie odrzucone, a liczby przeliczone. W tym mechanizmie nic nie może zmienić zawartości feedu bez tego, by ktoś przeczytał ten ekran i kliknął przycisk.

Harmonogram​

Na karcie Settings wybierz gotowe ustawienie (co godzinę, co 4 godziny, codziennie…) albo Custom z pięciopolowym wyrażeniem cron i strefą czasową IANA. Własne wyrażenie jest powtarzane prostym językiem („Co 4 godziny, w minucie 0”), a najbliższe uruchomienie jest zawsze widoczne.

  • Uruchomienie, które przypada, gdy poprzednie generowanie wciąż trwa, jest pomijane z podaniem powodu — nigdy nie trafia do kolejki za nim. Pominięte uruchomienia są wyszarzone na liście generowań.
  • Panel ostrzega, gdy średni czas generowania feedu zbliża się do odstępu między uruchomieniami.
  • Wyłączenie feedu zatrzymuje zarówno harmonogram, jak i publiczny adres URL.
  • Źródłem prawdy o harmonogramach jest Postgres; kolejka to indeks pochodny odbudowywany przy starcie, więc wyczyszczenie Redisa niczego nie traci.

Publiczny adres URL zawiera losowy token. Karta Feed link pokazuje go w całości, gdy tylko feed ma ważny token, razem z przyciskiem kopiowania, żebyś mógł skopiować go ponownie przy każdej zmianie konfiguracji u dostawcy.

Przechowywane są dwie rzeczy: skrót (hash) tokena, który jako jedyny jest porównywany przez publiczny endpoint, oraz sam token, zaszyfrowany kluczem SETTINGS_SECRET_ENCRYPTION_KEY — tym samym, którego używają już sekrety ustawień i dane uwierzytelniające. Zaszyfrowana kopia jest odczytywana tylko wtedy, gdy administrator otwiera feed, nigdy przy publicznym żądaniu.

Każdy, kto ma link, może odczytać plik, a plik zawiera Twoje ceny. Traktuj link jak dane uwierzytelniające: udostępnij go dostawcy, który go potrzebuje, i wymień go, jeśli wycieknie.

  • We wdrożeniu bez SETTINGS_SECRET_ENCRYPTION_KEY oraz w przypadku linków wydanych przed tą wersją platformy karta pokazuje tylko początek tokena. Wymień link, żeby dostać taki, który można skopiować.
  • Rotate wydaje nowy adres URL i unieważnia stary natychmiast, bez okresu przejściowego. Dostawca, który wciąż ma skonfigurowany stary adres, przestaje dostawać aktualizacje, dopóki nie wkleisz nowego.
  • Revoke zostawia feed bez publicznego adresu URL i usuwa przechowywaną kopię tokena razem z jego skrótem. Pobieranie pliku przez administratora nadal działa.
  • Adres URL zwraca nagłówek Cache-Control: private i obsługuje If-None-Match, więc ponowna weryfikacja po stronie dostawcy jest tania.
  • Endpoint ma limit żądań (domyślnie 60 na minutę); dostawcy pobierają plik kilka razy dziennie.

Pobranie wygenerowanego pliku w panelu administracyjnym wymaga uprawnienia Manage product feeds, a nie tylko View product feeds — plik zawiera Twoje ceny.

Jak czytać wynik generowania​

Każde generowanie tworzy wiersz z licznikami: rozważone, wysłane, pominięte, ostrzeżenia. Otwórz go, żeby zobaczyć problemy z poszczególnymi pozycjami, pogrupowane według powodu, z SKU każdej pozycji, której dotyczą, i eksportem pełnej listy do CSV.

PowódZnaczenie
missing_pricePole ceny wymagane przez szablon jest puste — żaden cennik nie wycenia produktu w kanale feedu w walucie feedu albo przypięty cennik feedu go nie wycenia. Pozycja została pominięta.
missing_imageProdukt nie ma publicznie dostępnego zdjęcia.
private_image_assetZdjęcia istnieją, ale nie są publiczne, więc nie można było opublikować stałego adresu URL.
missing_required_fieldPole wymagane przez dostawcę okazało się puste i nie miało wartości zastępczej — pozycja została pominięta.
missing_translationTylko przebiegi sprzed funkcji 174: brak wartości w języku feedu, użyto języka zastępczego. Tekst Global produktu obowiązuje teraz w każdym kanale i języku, więc nowe przebiegi go nie zapisują.
unresolvable_linkKanał nie ma skonfigurowanego adresu URL storefrontu.
unmapped_provider_categoryNie zastosowano żadnego mapowania kategorii; pole zostało pominięte.
stale_provider_category_mappingZmapowany węzeł nie istnieje w zainstalowanej wersji taksonomii.
zero_tax_rate_on_gross_feedFeed z cenami brutto nie znalazł reguły podatkowej dla swojego kraju opodatkowania.
sub_cent_price_without_pack_fieldCena ma więcej niż dwa miejsca po przecinku, a szablon nie ma pola wielkości opakowania, by opublikować ją jako cenę opakowania. Pozycja została pominięta (Cena poniżej jednego grosza).
sub_cent_price_beyond_pack_limitCena ma tyle miejsc po przecinku, że żadne opakowanie do 10 000 sztuk nie czyni jej dokładną co do grosza. Pozycja została pominięta.

Błędy generowania to coś innego niż problemy z pozycjami: kończą generowanie i niczego nie publikują, a wcześniej opublikowany plik jest nadal udostępniany.

BłądZnaczenie
channel_unavailableKanał feedu nie istnieje lub jest wyłączony. Nic nie zostaje opublikowane — feed nigdy nie rozszerza się na cały katalog.
unbound_template_fieldsSzablon ma pola niepowiązane z żadnym źródłem (zwykle po imporcie).
unknown_attributeKryteria wskazują atrybut, który już nie istnieje.
skip_threshold_exceededPominięto ponad połowę rozważonych pozycji, więc dobry plik nie został zastąpiony złym.
storage_unavailableMagazyn plików odrzucił plik.
worker_lostWorker przestał działać w trakcie generowania; blokada została zwolniona, a częściowy plik usunięty.

Generowanie może też zakończyć się stanem wycofany (withdrawn): przypięty cennik feedu nie obowiązywał (Ceny w feedzie wyżej), więc generowanie usunęło opublikowany plik zamiast utworzyć nowy. Nie ma ono kodu błędu; jego powodem jest powód przypiętego cennika (not_found, currency_mismatch, not_active, outside_schedule, not_on_channel, audience_restricted) i nie wywołuje ono powiadomienia.

Gdy generowanie kończy się błędem, administrator dostaje powiadomienie — raz przy przejściu w stan błędu, a nie przy każdym uruchomieniu, więc feed zepsuty od doby nie zapełnia listy powiadomień.

Uprawnienia​

KodDaje dostęp do
product_feeds:readPrzeglądania feedów, szablonów, historii generowań, problemów i mapowań kategorii.
product_feeds:writeTworzenia i edycji feedów i szablonów, generowania, wymiany lub unieważniania linku, mapowania kategorii i pobierania wygenerowanych plików.

Administrator z dostępem tylko do odczytu widzi każdy ekran, a kontrolki zapisu są widoczne, ale nieaktywne i każda wyjaśnia dlaczego — nigdy nie są ukrywane.

Ustawienia​

W Settings → Product feeds:

UstawienieWartość domyślnaDziałanie
Generated files kept per feed3Starsze pliki są usuwane po udanym generowaniu; opublikowany plik jest zawsze zachowywany.
Maximum concurrent feed generations2Na proces workera.
Skipped-item share that fails a run0.5Powyżej tego udziału generowanie kończy się błędem zamiast publikacji.
Stale run timeout (minutes)30Generowanie, które przez ten czas nie dało znaku życia, jest uznawane za utracone.
Recorded issues per run1000Limit zapisanych problemów z pozycjami; nadmiar jest zgłaszany.
Public feed requests per minute60Limit żądań do anonimowego adresu URL.
Category-mapping tree limit1000Powyżej tej liczby ekran mapowania używa stronicowanej płaskiej listy.

Dostarczanie feedu na serwer partnera​

Google i Meta same pobierają link, więc większość feedów nie wymaga tu żadnych ustawień. Marketplace'y i integracje z systemami ERP zwykle oczekują czegoś odwrotnego: pliku umieszczonego na serwerze, który regularnie sprawdzają. Właśnie to konfiguruje karta Delivery feedu.

Feed ma najwyżej jeden serwer docelowy, a dostarczanie włącza się i wyłącza niezależnie od jego konfiguracji — możesz więc skonfigurować partnera teraz i zacząć wysyłkę w przyszłym tygodniu albo wstrzymać wysyłkę bez utraty ustawień.

ProtokółDziałaniePola
SFTPPrzesyła plik przez SSH. Zalecany wybór.Host, port, użytkownik, hasło lub klucz prywatny, katalog
FTPPrzesyła plik przez FTP, najpierw próbując FTPS.Host, port, użytkownik, hasło, katalog
HTTP Server / API / GraphQLWysyła plik metodą POST pod adres URL.Adres URL żądania, nagłówki

Trzy ostatnie to jeden mechanizm pod trzema nazwami. Dokumentacja partnera może nazywać jego endpoint API albo endpointem GraphQL; platforma i tak wysyła to samo żądanie, a wybór zmienia tylko etykietę na ekranie.

Kiedy następuje dostarczenie​

Po generowaniu, które zakończyło się udaną publikacją, i tylko wtedy. Generowanie zakończone błędem, puste, wycofane albo pominięte, bo poprzednie jeszcze trwało, niczego nie wysyła — plik, który partner już ma, jest nadal aktualny, a ponowne wysłanie zapowiadałoby zmianę, która nie nastąpiła.

Jeśli przesyłanie się nie powiedzie, generowanie pozostaje udane, a opublikowany link nadal działa. Dostarczenie jest ponawiane kilka razy z rosnącym odstępem; jeśli nadal się nie udaje, ponawianie ustaje, a administrator dostaje powiadomienie. Każda próba — udana czy nie — jest widoczna na liście pod kartą, razem z powodem.

Sekrety​

Hasła, klucze prywatne i każdy nagłówek, którego nazwa wskazuje, że zawiera token (Authorization, X-Api-Key i podobne), są przechowywane w postaci zaszyfrowanej i nigdy nie są ponownie pokazywane. Zapisany sekret wyświetla się jako [redacted], a pozostawienie tej wartości bez zmian go zachowuje — dzięki temu zmiana ścieżki katalogu nie może po cichu skasować hasła.

Dwie odmowy, o których warto wiedzieć​

  • Dla protokołów HTTP adres http:// jest odrzucany. Nagłówek uwierzytelniający jest wysyłany razem z żądaniem, więc adres musi zaczynać się od https://.
  • Adresy prywatne i wewnętrzne są odrzucane, w tym 169.254.169.254 i wszystko w Twojej własnej sieci. Feed zawiera cały katalog z cenami; platforma wyśle go tylko tam, dokąd da się dotrzeć z publicznego internetu.

Sam protokół FTP z założenia przesyła dane bez szyfrowania. Platforma prosi każdy serwer FTP o TLS i wraca do zwykłego FTP tylko wtedy, gdy serwer odmówi, ale jeśli partner udostępnia SFTP, wybierz SFTP.

Test połączenia​

Test connection sprawdza, czy serwer docelowy jest osiągalny i czy dane uwierzytelniające działają, bez wysyłania feedu. W przypadku SFTP i FTP zapisuje i od razu usuwa jeden mały plik, bo katalog bez prawa zapisu to właśnie ten błąd, którego test samego połączenia by nie wykrył. Test ma limit wywołań dla każdego feedu.

Dla inżynierów​

Struktura​

packages/modules/product_feeds/src/backend/
├── entities/ 9 tables, all @GlobalEntity (no tenant column anywhere)
├── services/ selection, resolution, serializers, runs, tokens, taxonomies
├── commands/ feed / template / taxonomy-mapping Commands
├── workers/ generation consumer + stale-run reaper
├── seeds/ the five predefined templates
├── data/taxonomies/ bundled Google + Meta revisions (see PROVENANCE.md)
├── routes.admin.ts /api/v1/admin/product-feeds
├── routes.templates.ts /api/v1/admin/feed-templates, /feed-previews/*
├── routes.taxonomies.ts /api/v1/admin/feed-taxonomies
└── routes.public.ts GET /api/v1/public/product-feeds/:token

Kontrakty znajdują się w packages/contracts/src/product-feeds.ts; warstwa panelu administracyjnego — w packages/modules/product_feeds/src/admin/.

Odmowy formularza feedu​

Pole, które nie wskazuje niczego — szablon, kanał sprzedaży, cennik albo kod języka, za którym nie stoi żaden wiersz — oraz harmonogram, którego nie da się odczytać, dostają odpowiedź 400 VALIDATION_FAILED z details.field. Trzy odmowy dotyczą stanu instalacji, a nie samego żądania, i mają własne kody. Każda z nich również niesie details.field, więc formularz może umieścić komunikat pod polem, a operator czyta go we własnym języku:

ŚcieżkaKodKiedydetails
POST /api/v1/admin/product-feeds, PATCH …/:id400 PRODUCT_FEED_LANGUAGE_INACTIVEJęzyk istnieje, ale jest wyłączonyfield: "languageCode", languageCode
POST /api/v1/admin/product-feeds, PATCH …/:id400 PRODUCT_FEED_CURRENCY_NOT_OFFEREDKanał sprzedaży feedu nie oferuje tej walutyfield: "currencyCode", currencyCode, salesChannelId, allowed (rozdzielone przecinkami)
POST /api/v1/admin/product-feeds, PATCH …/:id, POST …/:id/duplicate400 PRODUCT_FEED_SLUG_TAKENInny feed używa już tego adresu (slug)field: "slug", slug

Do zgłoszenia #631 wszystkie trzy były odpowiedzią 400 VALIDATION_FAILED z angielskim tekstem pole: komunikat. Moduł sam deklaruje te trzy kody. Jego starsze kody PRODUCT_FEED_* deklaruje moduł catalog.

Potok generowania​

selection (ids only, keyset on products.id)
→ hydrate a batch of 500
→ resolve each item (pure)
→ serialize (one chunk per item)
→ artefactStore.put(stream)
→ publish by flipping ONE pointer, after put() resolves

Cztery właściwości, za które odpowiada ten potok:

  • Nic nie jest buforowane. Źródłem pozycji jest generator asynchroniczny, serializatory emitują jeden fragment na pozycję, adapter magazynu plików przyjmuje Readable, a em.clear() jest wywoływane po każdej partii — zarówno w pętli selekcji, jak i w pętli hydratacji, bo emFactory() tworzy fork, a EntityManager żyjący przez całe generowanie trzyma każdy wiersz, którego dotknął. Pomiar dla 100 000 produktów: 38 MB XML w 205 s, ze szczytowym zużyciem sterty +18,5 MB ponad poziom bazowy, rosnącym o około 107 bajtów na każdą kolejną pozycję (backend/test/perf/product_feeds/generation-100k.test.ts, PERF_RUN=true).
  • Problem z pojedynczą pozycją nigdy nie przerywa generowania. Pominięcia i ostrzeżenia są zapisywane dla każdej pozycji; generowanie kończy tylko błąd konfiguracji.
  • Publikacja to jedno przestawienie wskaźnika po skompletowaniu obiektu. Generowanie zakończone błędem, puste albo przekraczające próg pominięć nigdy nie zmienia published_artefact_id. Jedyne generowanie, które je czyści, to generowanie withdrawn — feedu przypiętego, którego cennik nie obowiązuje (Wycena niżej) — które ustawia wskaźnik na null tym samym zapytaniem co stan końcowy.
  • Nakładające się generowania są odrzucane, a nie kolejkowane. Przejęcie generowania to warunkowy UPDATE na product_feeds.current_run_id; przegrany zapisuje skipped(already_running).

Pozostały przyrost pamięci opisany wyżej nie pochodzi od pozycji: to lista identyfikatorów członków kanału, materializowana przed stronicowaniem (około 90 bajtów na produkt w kanale). To O(kanał), a nie O(feed).

Dostarczanie​

Dostarczanie to efekt uboczny po publikacji, podpięty w tym samym punkcie rozszerzenia co retencja i powiadomienie o nieudanym generowaniu: deliverArtefact to opcjonalny port w FeedGenerationDeps, wywoływany w gałęzi publikacji i nigdzie indziej. To umiejscowienie jest samym wymaganiem — generowanie, które niczego nie opublikowało, nie może niczego dostarczyć — i zarazem tym, co oddziela błąd dostarczenia od generowania, które w chwili próby przesłania już się zakończyło.

run publishes → deliverArtefact?(feedId, runId, artefactId) [port, optional]
→ enqueue on product_feeds.deliver
→ resolve config + secrets
→ adapter.send(stream, target) [transport SPI]
→ record attempt

Bez Redisa port dostarcza plik od razu, w tym samym procesie, zamiast umieszczać zadanie w kolejce. W przeciwnym razie wdrożenie jednoprocesowe pozwoliłoby operatorowi skonfigurować serwer docelowy, nie zobaczyć żadnego błędu i nigdy niczego nie dostarczyć.

Dwie tabele, obie należące do modułu: product_feed_deliveries (jeden wiersz na feed, wymuszony indeksem unikalnym) i product_feed_delivery_attempts (tylko dopisywanie, z limitem na feed).

Nie ma kolumny z sekretem. credential_code wskazuje konfigurację modułu credentials, który odpowiada za szyfrowanie danych w bazie i maskowanie przy odczycie; podział na nagłówki z sekretem i bez niego wykonuje isSecretDeliveryHeader w pakiecie kontraktów — celowo na podstawie reguły, a nie pola wyboru dla operatora. credentials jest więc w manifeście zależnością usługową, a nie wynikającą z klucza obcego.

Interfejs SPI transportu (services/delivery/delivery-adapter.interface.ts) przyjmuje Readable, nigdy Buffer, z tego samego powodu co serializatory — i jest punktem rozszerzenia dla modułu nakładkowego, który chce obsłużyć niestandardowy protokół partnera. HttpDeliveryAdapter korzysta z reguł adresów z taxonomy-source-url.ts, zamiast je kopiować: dwa zabezpieczenia przed SSRF w jednym module to jedno, które zostanie naprawione, i drugie, które nie zostanie.

Nic, co jest zapisywane przy próbie dostarczenia, nie jest daną uwierzytelniającą. target to postać do wyświetlenia z ukrytymi sekretami, a każdy komunikat o błędzie przechodzi przez delivery-redaction.ts, które działa na podstawie wartości — dostaje dokładnie te sekrety, których dotyczy operacja, i usuwa te ciągi znaków, zamiast zgadywać, jak wygląda hasło.

Środowisko testowe wstrzykuje adaptery, które odmawiają każdej wysyłki, z tego samego powodu, dla którego wstrzykuje moduł pobierania taksonomii niezdolny do pobierania: żaden test w tym repozytorium nie może nigdzie wysłać katalogu z cenami.

Wycena​

Generowanie nigdy nie czyta tabel innego modułu. Feed nieprzypięty wycenia każdą partię jednym wywołaniem resolveLinePrices portu pricingService modułu price_lists, jako gość (organization: null, customerGroupId: null), w kanale i walucie feedu, dla ilości 1, bez wariantu. Feed przypięty czyta namedListPrices({ priceListId, currencyCode, productIds, salesChannelId }) — wiersze cennika inne niż wiersze wariantów, przy ilości 1, liczone od ceny katalogowej gościa w kanale wyliczonej bez przypiętego cennika; produktu, którego cennik nie wycenia, nie ma w odpowiedzi (services/named-list-price-resolver.ts). Odpowiedź jest pusta, dopóki cennik nie jest publikowany: namedListPublishability({ priceListId, currencyCode, salesChannelId }) w tym samym FeedPricingPort (plugin.ts) mówi, czy jest, a jeśli nie — dlaczego, jednym z powodów pinnedPriceBookUnpublishableReasonSchema z @endora-commerce/contracts (not_found, currency_mismatch, not_active, outside_schedule, not_on_channel, audience_restricted), sprawdzanym w chwili wywołania, a nie przez aktualizację statusów modułu price_lists. ProductFeedService pyta o to dla każdego przypiętego feedu na liście i umieszcza powód w wierszu feedu w panelu jako pinnedPriceBookWarning (null, gdy feed nie jest przypięty albo cennik jest publikowany), a strona feedu pokazuje go jako ostrzeżenie (feeds.pinnedBook.<reason> w katalogu i18n/ modułu). Generowanie feedu przypiętego pyta namedListPublishability raz, po kontrolach konfiguracji (więc źle skonfigurowany feed nadal kończy się błędem i zachowuje ostatni poprawny plik) i przed przejściem katalogu. Gdy cennik nie obowiązuje, generowanie kończy się stanem withdrawn (feedRunStatusSchema) z powodem w withdrawalReason (kolumna product_feed_runs.withdrawal_reason), nie zapisuje pliku i czyści published_artefact_id, więc publiczny URL odpowiada 404 z jedyną treścią „niedostępny”, tak jak dla feedu nigdy niewygenerowanego. Nie wywołuje powiadomienia o błędzie ani dostarczenia. Wcześniejszy plik jest odłączany, a nie usuwany — jego wiersz i bajty zostają, do pobrania z jego własnego generowania, dopóki retencja po następnej publikacji ich nie usunie. Generowanie usuwa z pamięci podręcznej publiczne odpowiedzi dla feedu, które zapisał jego własny proces; pamięć podręczna jest w Redis, a indeks według feedu jest osobny w każdym procesie, więc wpis zapisany przez inny proces może udostępniać stary plik do wygaśnięcia jego TTL 60 s (services/feed-cache-invalidator.ts). Żadna ze ścieżek nie przechwytuje MODULE_DISABLED: gdy modułu price_lists nie ma, generowanie kończy się błędem zamiast publikować ceny, których platforma nie podaje.

Cenę jednostkową poniżej grosza (issue #430) rozstrzyga resolver pól pozycji, który pozostaje czysty: feedPackQuantity(net) z services/feed-pack.ts zwraca najmniejszą potęgę dziesięciu N, przy której net × N ma najwyżej dwa miejsca po przecinku — 1 dla ceny z dwoma znaczącymi miejscami, null powyżej MAX_FEED_PACK_QUANTITY (10 000) — odczytaną z dziesiętnego ciągu znaków, nigdy z liczby zmiennoprzecinkowej. resolveFeedItem bierze największe N, jakiego wymaga którakolwiek cena publikowana przez szablon (price, sale_price); przy N > 1 pomija pozycję jako sub_cent_price_without_pack_field, chyba że szablon wiąże pole pack_quantity, a jako sub_cent_price_beyond_pack_limit, gdy N to null. Pole ceny publikuje wtedy lineAmountHalfUp(net, N) — dokładne z racji wyboru N — a w feedzie brutto grossAmountHalfUp tej kwoty przy FeedItemPrice.taxRatePercent, stawce, przy której hydrator policzył cenę brutto jednostki (null w feedzie netto albo gdy żadna reguła podatkowa nie pasuje — wtedy publikowane jest netto). Trzy rodzaje źródeł pack_quantity, pack_unit_pricing_measure i pack_unit_pricing_base_measure (feedFieldSourceKindSchema) zwracają N, ${N}ct i ${N}ct (dwa ostatnie tylko dla N ≤ 100), a pusty ciąg — pominięte pole — gdy N to 1; to utrzymuje plik z ceną o dwóch miejscach bajt w bajt bez zmian (feed-two-place-output.test.ts przypina pliki wszystkich pięciu dostarczanych szablonów). To, czy szablon potrafi wyrazić opakowanie, rozstrzyga cały szablon: ResolveFeedItemInput.templateFields niesie go, gdy fields to jedno pole, jak w podglądzie edytora. Predefiniowany szablon Google wiąże te trzy źródła z g:multipack, g:unit_pricing_measure i g:unit_pricing_base_measure; rekoncyliator przy starcie nigdy nie edytuje zainstalowanego szablonu systemowego, więc migracja 20261025T145041_product_feeds_google_template_pack_fields dodaje je, po g:sale_price, do szablonu zainstalowanego przed 0.109.0.

Zawężenie do kanału​

Przynależność do kanału jest odczytywana wyłącznie przez wstrzyknięty port SalesChannelMembershipService.listEntityIdsForChannel; moduł nigdy nie odpytuje tabel łączących sales_channel_*. Minimalne warunki kwalifikacji, reguła operatora i kursor stronicowania (keyset) są łączone jawnym $and — nigdy rozwinięciem obiektu, które po cichu gubi zdublowany klucz id i kiedyś całkowicie wyłączyło zawężenie do kanału dla kryteriów kategorii.

Nie ma gałęzi, która przepuszczałaby w razie wątpliwości: kanał, którego nie da się ustalić albo który jest nieaktywny, zgłasza ChannelUnavailableError, a generowanie kończy się odmową. Zabezpieczeniem przed regresją jest backend/test/integration/product_feeds/channel-isolation.test.ts, który sprawdza też publiczny adres URL, bo ten endpoint nie wymaga uwierzytelnienia.

Audyt​

Każdy zapis wykonywany przez operatora jest poleceniem (Command): product_feeds.feed.create|update|delete|duplicate, product_feeds.token.rotate|revoke, product_feeds.run.start, product_feeds.template.create|update|duplicate|delete|import, product_feeds.taxonomy_mapping.set, product_feeds.taxonomy_revision.promote i product_feeds.taxonomy_check.start. Każde z nich zapisuje dokładnie jeden wpis w dzienniku audytu, przypisany do administratora, który je wykonał; cały import szablonu to jeden wpis, a nie jeden na pole.

Dwa ostatnie warto czytać razem. Zatwierdzenie wersji taksonomii to jedyny zapis w mechanizmie aktualizacji, który zmienia zawartość feedu, dlatego jest poleceniem; ręczne uruchomienie sprawdzenia jest audytowane, bo zapisuje, kto poprosił platformę o wysłanie żądania na zewnątrz — dokładnie tak, jak product_feeds.run.start zapisuje, kto zlecił generowanie.

Praca maszynowa — generowanie według harmonogramu, czyszczenie starych plików, zwalnianie porzuconych generowań, odwzorowanie harmonogramów w Redisie, instalacja taksonomii oraz sprawdzenie taksonomii według harmonogramu razem z nieaktywną wersją, którą może zainstalować — niczego nie zapisuje w dzienniku audytu, a każdy taki zapis ma znacznik command-coverage-ignore: <reason>, żeby kontrola statyczna pozostała rzetelna. Sprawdzenie według harmonogramu jest pracą maszynową właśnie dlatego, że nie może zmienić wyniku: wiersz audytu dla każdego cotygodniowego sprawdzenia w każdej instalacji zagrzebałby faktyczne decyzje operatora w szumie, a tabela historii sprawdzeń jest pełniejszym zapisem niż wpis w dzienniku audytu. Pilnuje tego backend/test/integration/product_feeds/command-coverage.test.ts.

Taksonomie dostawców​

Wersja taksonomii trafia do bazy danych dokładnie na dwa sposoby i oba tworzą ten sam rodzaj wiersza.

Dostarczana z platformą. Wersje są zapisane na dysku w data/taxonomies/<providerCode>/<revision>/<language>.txt i instaluje je przy starcie mechanizm uzgadniający, w jednej transakcji na wersję. Ta ścieżka nie otwiera żadnego połączenia sieciowego i nigdy nie otwierała. Instalacja bieżącego zestawu (8 562 węzły w czterech plikach) trwa około 2 sekund; potem pliki nie są już otwierane, bo najpierw sprawdzana jest baza danych. Dostarczona wersja jest oznaczana jako bieżąca tylko wtedy, gdy dostawca nie ma jeszcze bieżącej wersji — w świeżej bazie dotyczy to każdej pierwszej instalacji, a w długo działającej oznacza, że aktualizacja platformy nie może po cichu zastąpić wersji wybranej przez operatora.

Pobierana od dostawcy. Opcjonalne sprawdzenie, domyślnie wyłączone, pobiera pliki opublikowane przez dostawcę i instaluje zmienioną wersję jako nieaktywną (zobacz Aktualizacje taksonomii). Taka wersja nie może sama zacząć obowiązywać.

Generowanie nigdy nie zależy od połączenia z dostawcą. Generowanie odczytuje obowiązującą wersję z Postgresa i z nikim się nie łączy, więc dostawca niedostępny, powolny albo zwracający bzdury daje nieudane sprawdzenie, nigdy nieudane ani zmienione generowanie — a instalacja z wyłączonym przełącznikiem w ogóle nie wysyła żądań na zewnątrz.

Instalacja bez dostarczonych danych uruchamia się normalnie: ekran mapowania informuje, że nie zainstalowano żadnej taksonomii, a g:google_product_category jest traktowane jako niezmapowane, co pomija to pole, ale pozycja i tak trafia do pliku.

Pochodzenie dostarczanych plików dostawców, ich zmierzone rozmiary i otwarte pytanie o licencję opisuje packages/modules/product_feeds/src/backend/data/taxonomies/PROVENANCE.md. Wycofanie danych sprowadza się do usunięcia katalogu wersji danego dostawcy; kodu nie trzeba zmieniać.

Kolejki​

Dwa elementy BullMQ, rejestrowane tylko wtedy, gdy BACKEND_ROLE !== 'api':

  • product_feeds.generate — jedno zadanie na generowanie; worker je przejmuje, po każdej partii sygnalizuje, że działa, generuje plik, publikuje go, a następnie stosuje retencję. Zadanie jest idempotentne przy ponownym dostarczeniu.
  • wspólne dla modułu czyszczenie co 5 minut, które zwalnia przejęcia bez aktualnego sygnału życia, oznacza generowanie jako failed(worker_lost) i usuwa częściowy obiekt.

Harmonogramy poszczególnych feedów to BullMQ Job Schedulers o kluczach feed:<id>; mechanizm uzgadniający przy starcie tworzy lub aktualizuje harmonogram każdego włączonego feedu z harmonogramem i usuwa każdy harmonogram feed:*, który nie ma już odpowiednika.

Przechowywanie plików​

Pliki przechodzą przez adapter magazynu plików modułu Biblioteka mediów (Assets Library), ale pod własnym prefiksem tego modułu (product-feeds/…), zawsze jako prywatne i nigdy jako wiersze Asset: nie są mediami biblioteki, nie mogą pojawiać się w przeglądarce mediów i nie mogą być dostępne pod publicznym adresem URL zasobu. Publiczna trasa feedu przesyła strumieniowo sam obiekt — dzięki temu wymiana tokena rzeczywiście odbiera dostęp.

Testy​

pnpm --filter backend exec vitest run test/unit/product_feeds
pnpm --filter backend exec vitest run test/contract/product_feeds
pnpm --filter backend exec vitest run test/integration/product_feeds
PERF_RUN=true pnpm --filter backend exec vitest run test/perf/product_feeds

Wspólne środowisko testowe celowo łączy ten moduł bez Redisa i bez BullMQ — uruchamia się raz na plik testowy w jednym procesie potomnym, a połączenia z kolejką już wcześniej wyłączały w nim setki plików błędem „too many clients”. Testy wywołują bezpośrednio productFeeds.generation.generateNow(...). Środowisko testowe kieruje też mechanizm uzgadniający taksonomie do nieistniejącego katalogu, więc dostarczane pliki danych czyta wyłącznie taxonomy-bundled-data.test.ts.

Celowo poza zakresem tej wersji​

  • Dostarczanie e-mailem i API konkretnych marketplace'ów (Amazon SP-API, eBay, Allegro). Wysyłka obejmuje tylko SFTP, FTP i HTTP — zobacz Dostarczanie wyżej.
  • Feedy przyrostowe, uzupełniające lub różnicowe — każde generowanie tworzy cały plik od nowa.
  • Wiele krajów lub walut w jednym pliku; zamiast tego zduplikuj feed.
  • Automatyczne przyjęcie nowszej taksonomii. Opcjonalne sprawdzanie (zobacz Aktualizacje taksonomii) pobiera i instaluje zmienioną wersję jako nieaktywną; zaczyna ona obowiązywać dopiero po promocji wykonanej przez operatora.