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ór | Znaczenie |
|---|---|
| Szablon | Jakie pola zawiera plik, w jakiej kolejności i w jakim formacie (XML, CSV, TSV). |
| Kanał sprzedaży | Który katalog publikuje feed. Od kanału zależą też ceny i linki. |
| Język | W którym tłumaczeniu zapisywane są nazwy, opisy i ścieżki kategorii. |
| Nazwa | Po 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
- Przejdź do Sales channels → Product feeds i kliknij New feed.
- 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).
- Zapisz, a następnie kliknij Generate now na stronie feedu.
- 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.
| Szablon | Format | Szczegółowość | Stan |
|---|---|---|---|
| Google Merchant Center | XML (RSS 2.0 + g:) | Dla każdego wariantu | Gotowy do użycia |
| Katalog Meta | XML | Dla każdego wariantu | Gotowy do użycia |
| Plik płaski Amazon | TSV | Dla każdego produktu | Punkt wyjścia |
| eBay | CSV | Dla każdego produktu | Punkt wyjścia |
| Allegro | CSV | Dla każdego produktu | Punkt 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↑/↓lubAlt+↑/↓, upuść klawiszemSpace, anuluj klawiszemEscape. 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) orazg:unit_pricing_measureig:unit_pricing_base_measure(oba100ctdla 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 samog: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):
| Ustawienie | Działanie |
|---|---|
| Check for new taxonomy revisions | Główny przełącznik. Domyślnie wyłączony. |
| When to check | Wyraż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 provider | Ile 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ód | Znaczenie |
|---|---|
transport | Ten 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_found | Dostawca 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_status | Dostawca odpowiedział błędem. Zwykle jest to chwilowy problem po jego stronie; następne sprawdzenie spróbuje ponownie. |
not_taxonomy | Pod 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_large | Pobrany plik był pusty, niekompletny albo większy, niż platforma akceptuje. Nic nie zostało zainstalowane. |
no_nodes / implausible | Plik 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_languages | Plik 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.
Link i jego wymiana
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_KEYoraz 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: privatei obsługujeIf-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ód | Znaczenie |
|---|---|
missing_price | Pole 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_image | Produkt nie ma publicznie dostępnego zdjęcia. |
private_image_asset | Zdjęcia istnieją, ale nie są publiczne, więc nie można było opublikować stałego adresu URL. |
missing_required_field | Pole wymagane przez dostawcę okazało się puste i nie miało wartości zastępczej — pozycja została pominięta. |
missing_translation | Tylko 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_link | Kanał nie ma skonfigurowanego adresu URL storefrontu. |
unmapped_provider_category | Nie zastosowano żadnego mapowania kategorii; pole zostało pominięte. |
stale_provider_category_mapping | Zmapowany węzeł nie istnieje w zainstalowanej wersji taksonomii. |
zero_tax_rate_on_gross_feed | Feed z cenami brutto nie znalazł reguły podatkowej dla swojego kraju opodatkowania. |
sub_cent_price_without_pack_field | Cena 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_limit | Cena 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łąd | Znaczenie |
|---|---|
channel_unavailable | Kanał feedu nie istnieje lub jest wyłączony. Nic nie zostaje opublikowane — feed nigdy nie rozszerza się na cały katalog. |
unbound_template_fields | Szablon ma pola niepowiązane z żadnym źródłem (zwykle po imporcie). |
unknown_attribute | Kryteria wskazują atrybut, który już nie istnieje. |
skip_threshold_exceeded | Pominięto ponad połowę rozważonych pozycji, więc dobry plik nie został zastąpiony złym. |
storage_unavailable | Magazyn plików odrzucił plik. |
worker_lost | Worker 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
| Kod | Daje dostęp do |
|---|---|
product_feeds:read | Przeglądania feedów, szablonów, historii generowań, problemów i mapowań kategorii. |
product_feeds:write | Tworzenia 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:
| Ustawienie | Wartość domyślna | Działanie |
|---|---|---|
| Generated files kept per feed | 3 | Starsze pliki są usuwane po udanym generowaniu; opublikowany plik jest zawsze zachowywany. |
| Maximum concurrent feed generations | 2 | Na proces workera. |
| Skipped-item share that fails a run | 0.5 | Powyżej tego udziału generowanie kończy się błędem zamiast publikacji. |
| Stale run timeout (minutes) | 30 | Generowanie, które przez ten czas nie dało znaku życia, jest uznawane za utracone. |
| Recorded issues per run | 1000 | Limit zapisanych problemów z pozycjami; nadmiar jest zgłaszany. |
| Public feed requests per minute | 60 | Limit żądań do anonimowego adresu URL. |
| Category-mapping tree limit | 1000 | Powyż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łanie | Pola |
|---|---|---|
| SFTP | Przesyła plik przez SSH. Zalecany wybór. | Host, port, użytkownik, hasło lub klucz prywatny, katalog |
| FTP | Przesyła plik przez FTP, najpierw próbując FTPS. | Host, port, użytkownik, hasło, katalog |
| HTTP Server / API / GraphQL | Wysył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ę odhttps://. - Adresy prywatne i wewnętrzne są odrzucane, w tym
169.254.169.254i 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żka | Kod | Kiedy | details |
|---|---|---|---|
POST /api/v1/admin/product-feeds, PATCH …/:id | 400 PRODUCT_FEED_LANGUAGE_INACTIVE | Język istnieje, ale jest wyłączony | field: "languageCode", languageCode |
POST /api/v1/admin/product-feeds, PATCH …/:id | 400 PRODUCT_FEED_CURRENCY_NOT_OFFERED | Kanał sprzedaży feedu nie oferuje tej waluty | field: "currencyCode", currencyCode, salesChannelId, allowed (rozdzielone przecinkami) |
POST /api/v1/admin/product-feeds, PATCH …/:id, POST …/:id/duplicate | 400 PRODUCT_FEED_SLUG_TAKEN | Inny 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, aem.clear()jest wywoływane po każdej partii — zarówno w pętli selekcji, jak i w pętli hydratacji, boemFactory()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 generowaniewithdrawn— feedu przypiętego, którego cennik nie obowiązuje (Wycena niżej) — które ustawia wskaźnik nanulltym samym zapytaniem co stan końcowy. - Nakładające się generowania są odrzucane, a nie kolejkowane. Przejęcie generowania to
warunkowy
UPDATEnaproduct_feeds.current_run_id; przegrany zapisujeskipped(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.