Konfiguracja i sterowanie

Konfiguracja mieszka w trzech warstwach, a wiedza o tym, która wygrywa, to różnica między przełącznikiem, który przestawisz w trakcie awarii, a ponownym wdrożeniem.

  zmienna środowiskowa   ->  twarde nadpisanie; dla zapisu potrafi tylko WYŁĄCZYĆ
  zapisana wartość       ->  to, co operator edytuje w Ustawienia -> Allegro
  medusa-config.ts       ->  wartość domyślna, z jaką wtyczkę zainstalowano

Opcje

Pięć jest wymaganych. Cała reszta ma wartość domyślną.

Opcje synchronizacji

Opcje wymuszające wyłączenie

Każda z nich potrafi wyłącznie wyłączyć zapis. Żadna niczego nie uzbraja.

Co wywala start i dlaczego

Każda opcja jest sprawdzana w loaderze modułu, więc błędna konfiguracja wywala się przy starcie z konkretnym komunikatem, zamiast wyjść później jako niezrozumiały błąd z Allegro. Trzy sprawdzenia warto znać, bo każde wyłapuje pomyłkę, która inaczej objawiłaby się jako po cichu bezczynna pętla.

Ciąg wyglądający na wartość logiczną na wyłączniku rzuca wyjątkiem. priceSyncDisabled: process.env.X daje "true", co test prawdziwości uzna, a test === true zignoruje - przełącznik czytałby się jako włączony, podczas gdy Ty byłbyś przekonany, że jest wyłączony.

Jedna nazwa reguły użyta dla obu stanów promocji rzuca wyjątkiem. Zmiana promocji byłaby wtedy przełączeniem bez efektu, więc promowana stawka prowizji nigdy nie dotarłaby do progu ceny, a synchronizacja cen wyglądałaby zdrowo, systematycznie zaniżając próg każdej promowanej oferty.

Ustawienie obu źródeł SRP naraz rzuca wyjątkiem. To sufit powstrzymuje regułę przed zjeżdżaniem z ceną; dwa źródła to niejednoznaczny sufit.

Zmienne środowiskowe

Harmonogramy i wymuszone wyłączenia są zmiennymi środowiskowymi, a nie opcjami wtyczki, z powodu strukturalnego: Medusa oblicza pole schedule zadania cyklicznego w chwili ładowania wtyczki, zanim istnieje kontener DI, a więc i options tej wtyczki. Nie da się odczytać rozwiązanych opcji modułu z tego statycznego eksportu.

Harmonogramy zaczynają chodzić, gdy tylko wtyczka się załaduje, ale zapisy uzbrajają zapisane przełączniki, które wychodzą z pudełka wyłączone. Instalacja albo aktualizacja uruchamia pętle w ich rytmie; każdy zapis pozostaje rozbrojony, dopóki go nie uzbroisz. Ścieżki odczytu są nieszkodliwe, bo wykrywanie i monitor nie zapisują do Allegro niczego.

Przełączniki czasu działania

Każdy zapis docierający do Allegro ma zapisany, przestawialny przez operatora przełącznik, trzymany w jednowierszowym singletonie allegro_settings. Przestawienie działa od najbliższego taktu albo zdarzenia, bez ponownego wdrożenia, bo każda ścieżka wykonania ustala swój efektywny stan z zapisanego wiersza na starcie uruchomienia, a nie z wartości zapamiętanej przy starcie procesu.

Pierwszeństwo

Środowisko, i opcja wtyczki z chwili startu, to twarde nadpisanie, które potrafi wyłącznie wyłączyć zapis. Nigdy żadnego nie uzbraja:

efektywnieWłączone = zapisaneWłączone && !wymuszoneWyłączenie

• zapisane włączone + brak zmiennej -> włączone
• zapisane włączone + wymuszone wyłączenie -> wyłączone, bo operatora reagującego na awarię nie unieważnia nieaktualny uzbrojony przełącznik
• zapisane wyłączone + brak zmiennej -> wyłączone; zapis uzbraja wyłącznie przełącznik

Panel pokazuje przełącznik wyłączony przez środowisko jako zablokowany i „wymuszone wyłączenie”, razem ze zmienną do wyczyszczenia. Nigdy nie rysuje uzbrojonego przełącznika dla zapisu, który środowisko trzyma na dole. Zapis do wyłączonego przełącznika i tak jest przyjmowany i zapamiętywany, więc intencja przetrwa do chwili zdjęcia nadpisania.

Dołączanie faktur to jedyny zapis wychodzący z pudełka włączony, bo zanim ta wtyczka usłyszy o fakturze, dokument już istnieje jako zapis prawny, więc dostarczenie go jest bezpiecznym domyślnym zachowaniem. Jest bezczynny, dopóki moduł fakturowy nie jest podłączony i nie emituje zdarzeń.

Pola konfiguracji synchronizacji

Dziewięć ustawień da się edytować w Ustawienia -> Allegro na tym samym singletonie: tryb cenowy, dwie nazwy reguł automatyzacji, dwa źródła SRP, limit zmian, identyfikator marketplace'u i zakres kanału sprzedaży. Edycja zapisuje się i działa od najbliższego uruchomienia, bez ponownego wdrożenia.

Sklep, który nigdy nie dotknie tych pól, zachowuje się dokładnie jak wcześniej: każda zapisana kolumna startuje jako null, a null przepuszcza dalej do opcji z medusa-config.ts.

Pierwszeństwo dla wartości, a nie dla flagi

Dla ciągu znaków ani liczby nie istnieje „wyłączone”, więc ustawiona blokada środowiskowa wygrywa bezwarunkowo:

efektywnaWartość = blokadaŚrodowiskowa ?? wartośćZapisana ?? domyślnaZKonfiguracji

Ustawiona blokada środowiskowa jest rozstrzygająca - bije i zapisaną edycję z panelu, i opcję z medusa-config.ts, a panel pokazuje pole jako zablokowane, tak samo jak wyłączony przełącznik. Wyczyszczenie pola w panelu zapisuje null, co wraca do opcji z medusa-config.ts, a nie do pustej wartości.

Dwa pola są krytyczne dla okablowania

Edycja marketplaceId albo salesChannelId zmienia zakres produktów Medusy, które ta wtyczka dopasowuje do ofert Allegro. Błędna wartość psuje mapowanie po cichu, zamiast dać oczywiście zły wynik. Oba pozostają edytowalne, z blokadą środowiskową jako wyjściem awaryjnym: ustaw ALLEGRO_MARKETPLACE_ID albo ALLEGRO_SALES_CHANNEL_ID, żeby przypiąć właściwą wartość na wypadek pomyłki w panelu podczas przełączania. Panel rysuje na obu polach wyraźne ostrzeżenie.

Dwie niezmienniki są pilnowane przy każdym zapisie

Nazwy reguły standardowej i promowanej muszą się różnić, a źródło SRP może być ustawione najwyżej jedno. Oba istniały już jako sprawdzenia przy starcie, a teraz są pilnowane także przy każdym zapisie z panelu, bo zapisanie jednego pola niezależnie od drugiego potrafi stworzyć kolizję, której sprawdzenie startowe nigdy nie widziało. Zapis jest odrzucany, a nie po cichu przyjmowany.

Włączanie zapisów

Każdy zapis wychodzi rozbrojony, więc pętle chodzą tylko do odczytu, dopóki nie uzbroisz kolejnych. Bezpieczna kolejność i powód, dla którego każdy krok stoi tam, gdzie stoi:

1. Połącz konto z uprawnieniem do zapisu. Bez niego każde polecenie odpowiada 403, a panel podnosi baner o ponownym połączeniu.
2. Zostaw zapisy rozbrojone w czasie przygotowań. To domyślny stan świeżej instalacji, więc nie ma tu nic do roboty, chyba że aktualizowałeś z już uzbrojonymi zapisami. Jeśli przełączasz się z innego systemu, który obecnie pisze do Allegro, ustaw zmienne wymuszające wyłączenie, żeby żadne przestawienie przełącznika nie uzbroiło zapisu, zanim stary system nie zostanie wygaszony. Dwa systemy piszące do jednego katalogu to najgorszy możliwy stan, a każdy zapis jest osobny.
3. Pozwól popracować wykrywaniu i monitorowi. Oba są tylko do odczytu. Rozwiąż każdy konflikt na stronie ofert i zobacz, co tryb ceny i dryf naprawdę mówią o katalogu. To ten krok zamienia uzbrojenie zapisów w decyzję zamiast w skok na głęboką wodę.
4. Uzupełnij prowizje kategorii. Dopóki kategoria nie ma obu, każda oferta w niej jest pomijana z missing-break-even.
5. Skonfiguruj źródło SRP i sprawdź, czy warianty faktycznie niosą wartość. Bez tego każda oferta jest pomijana z missing-srp.
6. Utwórz dwie reguły automatyzacji ceny na koncie Allegro i wpisz ich nazwy w automationRules. Do tego czasu synchronizacja cen jest bezczynna z definicji.
7. Uzbrój zapisy - najpierw stany, potem ceny. Zła ilość jest odwracalna w jednym uruchomieniu; zła cena mogła już coś sprzedać. Podnieś changeCap dopiero wtedy, gdy obejrzysz historię wysyłek i uwierzysz uruchomieniu. Drenaż zamówień, zwrotny zapis realizacji i dołączanie faktur uzbrajaj wtedy, gdy będziesz gotowy na każde z osobna.

Zatrzymanie zapisów, natychmiast

Ustaw odpowiednią zmienną i przeładuj środowisko procesu:

ALLEGRO_PRICE_SYNC_DISABLED=1      # polecenia automatyzacji ceny
ALLEGRO_STOCK_SYNC_DISABLED=1      # polecenia zmiany ilości
ALLEGRO_ORDERS_SYNC_DISABLED=1     # drenaż zamówień
ALLEGRO_INVOICE_ATTACH_DISABLED=1  # dołączanie plików PDF faktur

Wyłączona pętla zapisuje na swoim wierszu stanu, że była wyłączona, więc „wyłączone” pozostaje odróżnialne od „zepsute” - z zewnątrz oba wyglądają jak „nic się nie stało”.

Zmienna potrafi wyłącznie wyłączyć, nigdy włączyć. Rozstrzygnięcie brzmi option === true || envIsTruthy, więc ALLEGRO_PRICE_SYNC_DISABLED=0 nie uzbraja pętli, której opcja to true. Co jest potrzebne do ponownego uzbrojenia, zależy więc od tego, jak napisano Twoją konfigurację, i warto to ustalić, zanim będzie trzeba pod presją:

// Wzorzec A - opcja przypięta. Ponowne uzbrojenie to edycja konfiguracji i wdrożenie.
priceSyncDisabled: true,

// Wzorzec B - opcja wyprowadzona z tej samej zmiennej. Ponowne uzbrojenie to jedna
// zmiana środowiska, a wyłącznik awaryjny nadal wygrywa, bo =1 też daje opcję true:
//   brak -> true (wyłączone)    =1 -> true (wyłączone)    =0 -> false (uzbrojone)
priceSyncDisabled: process.env.ALLEGRO_PRICE_SYNC_DISABLED !== "0",

Wzorzec B jest lepszym domyślnym wyborem przy etapowym przełączaniu: jedna zmienna jest zarazem blokadą przed przełączeniem i przełącznikiem uzbrajającym, więc między operatorem a działającą synchronizacją nie stoi żadna edycja konfiguracji. Wzorzec A jest właściwy, gdy chcesz, żeby uzbrojenie wymagało przeglądu kodu. Wzorzec B musi porównywać z "0" wprost, a nie rzutować, bo Boolean(process.env.X) jest true dla ciągu "0", co przypięłoby wyłączenie na zawsze.

Zwróć uwagę, że ordersSyncDisabled nie zatrzymuje zwrotnego zapisu realizacji ani dołączania faktur - każde ma własny wyłącznik. Zatrzymuje natomiast przejście ponawiające faktury, które chodzi na końcu drenażu. Żeby zatrzymać każdy zapis do Allegro, rozłącz konto.

Jak czytać pętlę, która wygląda na zaciętą

Sprawdź status wiersza stanu na stronie ustawień:

• running i nic się nie rusza. Uruchomienie po awarii trzyma zajęcie do sześciu minut, po czym następny takt przejmuje je jako nieświeże i zapisuje to w logu. Nieświeżość mierzy się od claim_heartbeat_at, które żywe uruchomienie podbija co najmniej raz na minutę, więc długie, ale zdrowe uruchomienie utrzymuje swoje zajęcie zamiast zostać przejęte w locie.
• running i linia w logu o utracie zajęcia. Uruchomienie odkryło, że zostało przejęte, i zatrzymało się, nie zapisując już niczego, łącznie z własnym wynikiem. Nic nie ginie; porzucona praca powtórzy się.
• idle albo error z komunikatem o wyłączniku, gdy trwa inne uruchomienie. Pominięcie, które przychodzi w chwili, gdy zajęcie trzyma inne uruchomienie, celowo nie dotyka wiersza stanu i zapisuje w logu, że tego odmówiło. Zapisanie zwolniłoby zajęcie tamtego uruchomienia i pozwoliło następnemu taktowi wystartować drugie równoległe.
• error ze słowem SYSTEMIC w komunikacie. Pętla czeka na Allegro. Nic nie zostało pominięte ani wsadzone do kwarantanny; ponowi sama.
• ok z zerowymi licznikami. Nie ma nic do roboty, co jest czymś innym niż zepsute. Liczniki są w tabeli zdrowia właśnie po to, żeby te dwa stany dało się odróżnić.
• idle z komunikatem o wyłączniku. Działa zgodnie z konfiguracją.

Budżet ręcznych wysyłek

POST /admin/allegro/offers/:sku/push dzieli zasięg rażenia z zaplanowaną pętlą. Ręczne wysyłki są liczone w ruchomym oknie godziny, a gdy licznik sięgnie changeCap, kolejne są odrzucane z kodem HTTP 429 i nagłówkiem Retry-After na godzinę.

Istnieje to dla skryptów, a nie dla ludzi. Każde wywołanie bierze zajęcie synchronizacji, więc wywołania szeregują się - ale szeregowanie to nie ograniczanie, a pętla po tej trasie przeceniłaby inaczej cały katalog, obchodząc prosto limit, który istnieje po to, żeby zły plan tego nie zrobił. Licznik pochodzi z pushed_by w tabeli audytu, więc własne pętle wtyczki nigdy nie zjadają budżetu operatora, a limit przeżywa restart.

Jeśli naprawdę potrzebujesz wysłać w godzinę więcej, podnieś changeCap - co podnosi go także dla zaplanowanej pętli, i to celowo, bo jest to ta sama decyzja.