Kowal ShippingRules — instrukcja instalacji, konfiguracji i obsługi

Cel dokumentu

Ten dokument opisuje praktyczne wdrożenie i obsługę modułu Kowal_ShippingRules w Magento 2. Jest przeznaczony dla osób odpowiedzialnych za instalację modułu, konfigurację sklepu, testy wdrożeniowe oraz codzienną obsługę reguł wysyłki.

Dokument obejmuje:

• instalację modułu,
• konfigurację podstawową,
• tworzenie metod wysyłki,
• konfigurację stawek,
• obsługę restrykcji metod dostawy,
• obsługę dodatkowych opłat Extra Fee,
• diagnostykę,
• migrację z modułów Amasty,
• checklistę testów po wdrożeniu.

Informacje podstawowe

Nazwa techniczna modułu:

Kowal_ShippingRules

Lokalizacja modułu:

app/code/Kowal/ShippingRules

Kod carriera:

kowal_shippingrules

Kod metody wysyłki w checkout ma format:

kowal_shippingrules_<kod_metody>

Przykład:

kowal_shippingrules_dostawa_paletowa

Wymagania przed instalacją

Przed instalacją należy potwierdzić:

• sklep działa na Magento 2.4.x,
• środowisko używa PHP >=8.1,
• moduł Kowal_Base jest dostępny,
• wykonano backup plików i bazy danych,
• wdrożenie jest wykonywane najpierw na środowisku testowym lub staging,
• po instalacji będzie możliwość uruchomienia setup:upgrade i setup:di:compile,
• osoba testująca ma dostęp do panelu administracyjnego i checkoutu.

Instalacja modułu

1. Wgraj moduł

Moduł powinien znajdować się w katalogu:

app/code/Kowal/ShippingRules

2. Włącz moduł

bin/magento module:enable Kowal_ShippingRules

Jeżeli Kowal_Base nie jest jeszcze włączony, należy włączyć go wcześniej albo razem z modułem:

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Zaktualizuj bazę danych

bin/magento setup:upgrade

Ta komenda tworzy tabele modułu oraz dodaje kolumny wymagane do obsługi Extra Fee w quote, order, invoice i creditmemo.

4. Skompiluj DI

Na produkcji:

bin/magento setup:di:compile

5. Wyczyść cache

bin/magento cache:flush

6. Sprawdź status modułu

bin/magento module:status Kowal_ShippingRules

Moduł powinien znajdować się na liście modułów aktywnych.

Kontrola po instalacji

Po instalacji uruchom diagnostykę:

bin/magento kowal:shippingrules:stabilization:check

Wariant pełny w JSON:

bin/magento kowal:shippingrules:stabilization:check --json

Komenda jest read-only i nie zmienia danych. Sprawdza między innymi:

• obecność tabel modułu,
• liczbę rekordów,
• błędny JSON warunków,
• aktywne metody bez aktywnych stawek,
• reguły Extra Fee z tax class przy wyłączonym trybie podatku.

Jeżeli komenda zwraca błędy, nie należy przełączać modułu na produkcyjne użycie przed ich wyjaśnieniem.

Konfiguracja podstawowa

Carrier

Ścieżka w panelu Magento:

Stores / Configuration / Sales / Delivery Methods / Shipping Methods & Rules

Pola:

• Enabled — włącza lub wyłącza carrier kowal_shippingrules.
• Title — nazwa grupy metod widoczna w checkout.
• Test Method Name — nazwa testowej metody konfiguracyjnej.
• Test Method Price — cena testowej metody konfiguracyjnej.
• Sort Order — kolejność carriera na liście metod dostawy.
• Show Method If Not Applicable — czy pokazać błąd, gdy brak dostępnych metod.
• Displayed Error Message — komunikat, gdy metoda nie jest dostępna.

Najważniejsze ustawienie:

carriers/kowal_shippingrules/active = 1

Jeżeli carrier jest wyłączony, metody tworzone w module nie będą dostępne w checkout.

Diagnostyka i funkcje awaryjne

Ścieżka w panelu Magento:

Stores / Configuration / Sales / Shipping Methods & Rules

Sekcja General Diagnostics:

• Enable Debug Logging — zapisuje szczegóły decyzji do logu.
• Shadow Mode — tryb przygotowany do porównywania zachowania podczas migracji.

Sekcja Restrictions:

• Enable Restrictions — włącza lub wyłącza tylko restrykcje.

Sekcja Extra Fees:

• Enable Extra Fees — włącza lub wyłącza tylko dodatkowe opłaty.
• Fee Tax Mode — określa sposób obsługi podatku dla Extra Fee.

Dostępne tryby podatku:

• Do Not Calculate Tax — moduł nie nalicza podatku od Extra Fee.
• Calculate by Fee Tax Class — moduł nalicza podatek według klasy podatkowej ustawionej na regule fee.

Domyślne, bezpieczne ustawienia:

kowal_shippingrules/general/debug = 0
kowal_shippingrules/general/shadow_mode = 0
kowal_shippingrules/restrictions/enabled = 1
kowal_shippingrules/fees/enabled = 1
kowal_shippingrules/fees/tax_mode = none

Menu modułu w panelu

Ścieżka:

Sales / Shipping Methods & Rules

Dostępne sekcje:

• Shipping Methods — metody wysyłki i stawki,
• Shipping Restrictions — restrykcje metod dostawy,
• Extra Fees — dodatkowe opłaty.

Obsługa metod wysyłki

Kiedy tworzyć metodę wysyłki?

Metodę wysyłki należy utworzyć wtedy, gdy sklep potrzebuje własnej opcji dostawy, np.:

• dostawa paletowa,
• transport specjalny,
• dostawa lokalna,
• kurier dla produktów gabarytowych,
• odbiór logistyczny,
• metoda dostępna tylko dla wybranych produktów lub regionów.

Tworzenie metody

Przejdź do:

Sales / Shipping Methods & Rules / Shipping Methods

Następnie wybierz Add New albo edytuj istniejącą metodę.

Typowe pola metody:

• Is Active — czy metoda jest aktywna.
• Code — techniczny kod metody.
• Name — nazwa widoczna dla klienta.
• Description — opis metody.
• Sort Order — kolejność wyświetlania.
• Store Views — widoczność dla store view.
• Customer Groups — widoczność dla grup klientów.
• Conditions — warunki dostępności metody.

Zalecenia dla pola Code:

• używaj małych liter,
• nie używaj polskich znaków,
• nie używaj spacji,
• stosuj podkreślenia zamiast spacji.

Przykłady:

dostawa_paletowa
transport_specjalny
kurier_gabaryt
dostawa_lokalna

Pełny kod metody w checkout będzie miał prefiks carriera:

kowal_shippingrules_dostawa_paletowa

Stawki metody

Aktywna metoda powinna mieć co najmniej jedną aktywną stawkę. Jeżeli metoda nie ma pasującej stawki, nie pojawi się w checkout.

Stawka może zależeć od:

• kraju,
• regionu,
• kodu pocztowego,
• wartości koszyka,
• wagi,
• ilości produktów,
• typu wysyłki,
• priorytetu.

Tryby ceny:

• fixed — stała cena,
• percent_subtotal — procent od subtotalu.

Przykłady:

• cena 29 zł dla przesyłek do 30 kg,
• cena 149 zł dla dostawy paletowej,
• 5% wartości koszyka dla specjalnego transportu,
• osobna stawka dla wybranych kodów pocztowych.

Warunki metody

Warunki określają, kiedy metoda ma być dostępna.

Przykłady:

• metoda dostępna tylko dla produktów z wybranej kategorii,
• metoda dostępna tylko przy określonym atrybucie produktu,
• metoda dostępna tylko dla koszyka powyżej określonej wartości,
• metoda dostępna tylko dla wybranego kraju dostawy.

Jeżeli warunki są puste, metoda jest ograniczana tylko przez status, store view, customer group i pasującą stawkę.

Obsługa restrykcji metod dostawy

Kiedy używać restrykcji?

Restrykcje służą do ukrywania lub blokowania metod wysyłki, które nie powinny być dostępne dla konkretnego zamówienia.

Przykłady:

• ukryj paczkomat dla produktów gabarytowych,
• zablokuj wysyłkę zagraniczną dla wybranej kategorii,
• pokaż komunikat, że transport ekspresowy jest niedostępny dla produktów na zamówienie,
• ukryj metodę dostawy dla wybranego kraju.

Tworzenie restrykcji

Przejdź do:

Sales / Shipping Methods & Rules / Shipping Restrictions

Następnie wybierz Add New albo edytuj istniejącą restrykcję.

Typowe pola:

• Is Active — czy restrykcja działa.
• Name — nazwa wewnętrzna.
• Target Carrier — carrier, którego dotyczy restrykcja.
• Target Method — metoda, której dotyczy restrykcja.
• Action — sposób działania.
• Message — komunikat dla klienta.
• Priority — priorytet.
• Stop Processing — czy zatrzymać dalsze sprawdzanie reguł.
• Store Views — zakres store view.
• Customer Groups — zakres grup klientów.
• Conditions — warunki dopasowania.

Akcje restrykcji

hide:

• metoda zostanie ukryta,
• klient jej nie zobaczy,
• dobre dla oczywistych ograniczeń, np. paczkomat dla gabarytów.

error:

• metoda zostanie pokazana jako niedostępna,
• klient zobaczy komunikat,
• dobre, gdy warto wyjaśnić powód niedostępności.

Priorytet i Stop Processing

Reguły są sprawdzane według priorytetu. Wyższy priorytet oznacza wcześniejsze sprawdzanie.

Stop Processing = Yes oznacza, że po dopasowaniu tej restrykcji moduł nie sprawdza kolejnych restrykcji dla tej metody.

Zalecenie:

• używaj wyższych priorytetów dla reguł bardziej szczegółowych,
• używaj niższych priorytetów dla reguł ogólnych,
• włącz Stop Processing, jeśli reguła ma ostatecznie rozstrzygać dostępność metody.

Obsługa Extra Fee

Kiedy używać Extra Fee?

Extra Fee służy do doliczania dodatkowych opłat do zamówienia.

Przykłady:

• opłata za pakowanie niestandardowe,
• dopłata za transport gabarytowy,
• opłata za produkty delikatne,
• opłata logistyczna dla konkretnej metody dostawy,
• dopłata dla wybranych regionów.

Tworzenie Extra Fee

Przejdź do:

Sales / Shipping Methods & Rules / Extra Fees

Następnie wybierz Add New albo edytuj istniejącą opłatę.

Typowe pola:

• Is Active — czy fee działa.
• Name — nazwa wewnętrzna.
• Label — nazwa opłaty widoczna w totals.
• Target Carrier — carrier, którego dotyczy fee.
• Target Method — metoda, której dotyczy fee.
• Price Type — typ ceny.
• Price — wartość opłaty.
• Apply Mode — sposób naliczania.
• Tax Class ID — klasa podatkowa, jeśli używany jest tax mode.
• Priority — priorytet.
• Stop Processing — czy zatrzymać dalsze naliczanie fee.
• Store Views — zakres store view.
• Customer Groups — zakres grup klientów.
• Conditions — warunki naliczenia.

Tryby ceny

fixed:

• stała kwota,
• np. 19 zł za pakowanie.

percent_subtotal:

• procent od wartości koszyka,
• np. 3% wartości zamówienia.

Tryby naliczania

cart:

• jedna opłata dla całego koszyka.

per_item:

• opłata mnożona przez ilość produktów.

per_matching_item:

• opłata naliczana tylko dla produktów spełniających warunki.

Przykład:

Jeżeli opłata za specjalne zabezpieczenie wynosi 5 zł, a w koszyku są 3 produkty spełniające warunek, tryb per_matching_item naliczy 15 zł.

Podatek Extra Fee

Domyślnie podatek od Extra Fee nie jest naliczany:

kowal_shippingrules/fees/tax_mode = none

Aby naliczać podatek:

1. Ustaw Fee Tax Mode na Calculate by Fee Tax Class.
2. Uzupełnij Tax Class ID na regule Extra Fee.
3. Przetestuj koszyk, order, invoice i creditmemo.

Podatek Extra Fee powinien być każdorazowo sprawdzony z konfiguracją podatkową konkretnego sklepu.

Obsługa warunków

Moduł korzysta z generatora warunków podobnego do reguł Magento.

Warunki mogą dotyczyć między innymi:

• atrybutów produktów,
• SKU,
• kategorii,
• typu produktu,
• wagi,
• ceny,
• wartości koszyka,
• ilości produktów,
• kraju dostawy,
• regionu,
• miasta,
• kodu pocztowego,
• kuponu,
• wybranej metody wysyłki.

Przykład warunku dla produktu gabarytowego

Założenie:

• produkt ma atrybut shipping_type,
• wartość dla gabarytu to pallet.

Reguła:

Jeżeli produkt w koszyku ma shipping_type = pallet

Możliwe działania:

• pokaż metodę Dostawa paletowa,
• ukryj paczkomat,
• dolicz fee Transport gabarytowy.

Zalecenia przy pracy z warunkami

• twórz najpierw prostą regułę i przetestuj ją w koszyku,
• unikaj zbyt wielu warunków w jednej regule,
• opisuj reguły czytelnymi nazwami,
• dla ważnych reguł używaj jednoznacznych atrybutów produktów,
• po zmianie atrybutów produktów przetestuj koszyk ponownie.

Diagnostyka i logowanie

Dedykowany plik logu:

var/log/kowal_shipping_rules.log

Debug można włączyć w:

Stores / Configuration / Sales / Shipping Methods & Rules / General Diagnostics

Włącz:

Enable Debug Logging = Yes

Zalecenia:

• nie zostawiaj debug logging włączonego stale na produkcji,
• włącz debug tylko na czas diagnozy,
• po zakończeniu testów wyłącz debug,
• logi analizuj razem z koszykiem testowym i konfiguracją reguł.

Funkcje awaryjne

Jeżeli po wdrożeniu wystąpi problem, można niezależnie wyłączyć:

Cały carrier

Stores / Configuration / Sales / Delivery Methods / Shipping Methods & Rules / Enabled = No

Efekt:

• metody z carriera kowal_shippingrules nie będą dostępne.

Tylko restrykcje

Stores / Configuration / Sales / Shipping Methods & Rules / Restrictions / Enable Restrictions = No

Efekt:

• metody nie będą ukrywane ani blokowane przez restrykcje.

Tylko Extra Fee

Stores / Configuration / Sales / Shipping Methods & Rules / Extra Fees / Enable Extra Fees = No

Efekt:

• dodatkowe opłaty nie będą naliczane.

Migracja z Amasty

Cel migracji

Migracja z Amasty ma pomóc przenieść konfigurację restrykcji i extra fee do Kowal_ShippingRules.

Moduł Kowal nie wymaga Amasty do normalnego działania. Amasty może być użyte jako źródło danych migracyjnych oraz punkt odniesienia podczas testów.

Obsługiwane źródła danych

Migrator analizuje:

amasty_shiprestriction_rule
amasty_extrafee
amasty_extrafee_option

Docelowe tabele:

kowal_shipping_restriction
kowal_shipping_fee

Zasady bezpieczeństwa migracji

Migracja została zaprojektowana ostrożnie:

• raport jest read-only,
• dry-run nie zapisuje danych,
• apply domyślnie działa jako preview,
• zapis wymaga jawnej opcji --execute,
• zapisywane są tylko rekordy ze statusem ready,
• rekordy manual_review i unsupported są pomijane,
• migracja jest idempotentna dzięki polom migration_source i migration_source_key,
• migracja nie wyłącza Amasty,
• migracja nie przełącza ruchu automatycznie.

Krok 1 — raport bazowy

Uruchom:

bin/magento kowal:shippingrules:amasty:report

Raport zostanie zapisany do:

var/report/kowal_shippingrules_amasty_report.json

Raport pokazuje obecność i liczebność tabel Amasty oraz tabel Kowal.

Krok 2 — dry-run transformacji

Uruchom:

bin/magento kowal:shippingrules:amasty:report --dry-run --limit=100

Dry-run przygotowuje plan transformacji, ale nic nie zapisuje.

Statusy rekordów:

• ready — rekord może zostać przeniesiony automatycznie,
• manual_review — rekord wymaga ręcznej analizy,
• unsupported — rekord nie jest obsługiwany przez automatyczny migrator.

Jeżeli raport zawiera dużo manual_review albo unsupported, należy przeanalizować te reguły przed apply.

Krok 3 — preview apply

Uruchom:

bin/magento kowal:shippingrules:amasty:apply --limit=100

To nadal nie zapisuje danych. Komenda pokazuje, ile rekordów zostałoby utworzonych, pominiętych lub zakończonych błędem.

Krok 4 — apply restrykcji

Po akceptacji preview:

bin/magento kowal:shippingrules:amasty:apply --type=restrictions --limit=100 --execute

Komenda zapisze tylko restrykcje ze statusem ready.

Krok 5 — apply Extra Fee

Po akceptacji preview:

bin/magento kowal:shippingrules:amasty:apply --type=fees --limit=100 --execute

Komenda zapisze tylko extra fees ze statusem ready.

Krok 6 — diagnostyka po migracji

Uruchom:

bin/magento kowal:shippingrules:stabilization:check

Sprawdź również panel:

Sales / Shipping Methods & Rules / Shipping Restrictions
Sales / Shipping Methods & Rules / Extra Fees

Krok 7 — testy porównawcze z Amasty

Przed wyłączeniem lub zastąpieniem konfiguracji Amasty należy porównać wyniki dla koszyków testowych.

Rekomendowane koszyki:

• produkt standardowy,
• produkt gabarytowy,
• produkt delikatny,
• kilka produktów o różnych warunkach,
• zamówienie z różnymi krajami dostawy,
• zamówienie z różnymi kodami pocztowymi,
• zamówienie z kuponem,
• zamówienie z wybraną metodą objętą Extra Fee.

Dla każdego koszyka sprawdź:

• dostępne metody dostawy,
• ukryte metody,
• komunikaty błędów,
• naliczone extra fee,
• kwoty brutto/netto, jeśli używany jest tax fee,
• order,
• invoice,
• creditmemo.

Krok 8 — decyzja o przełączeniu

Dopiero po akceptacji wyników można planować przełączenie konfiguracji produkcyjnej.

Zalecenia:

• nie wyłączaj Amasty bez backupu,
• nie usuwaj danych Amasty od razu po migracji,
• najpierw wyłącz działanie po stronie konfiguracji,
• zachowaj możliwość rollbacku,
• przygotuj listę reguł wymagających ręcznej korekty.

Rollback po migracji

Jeżeli wystąpi problem:

1. Wyłącz carrier Kowal ShippingRules.
2. Wyłącz Enable Restrictions.
3. Wyłącz Enable Extra Fees.
4. Przywróć dotychczasową konfigurację Amasty.
5. Sprawdź checkout.
6. Zachowaj raporty migracyjne do analizy.

Checklist po wdrożeniu

Techniczna

• module:status pokazuje Kowal_ShippingRules jako aktywny,
• setup:upgrade zakończył się bez błędów,
• setup:di:compile zakończył się bez błędów,
• cache:flush wykonany,
• stabilization:check nie zwraca błędów,
• panel administracyjny pokazuje menu Shipping Methods & Rules,
• plik logu jest zapisywany przy włączonym debug.

Konfiguracyjna

• carrier jest włączony,
• utworzono co najmniej jedną metodę wysyłki,
• aktywna metoda ma aktywną stawkę,
• store views są ustawione poprawnie,
• customer groups są ustawione poprawnie,
• restrykcje są włączone albo świadomie wyłączone,
• extra fees są włączone albo świadomie wyłączone,
• tax mode jest zgodny z konfiguracją podatkową sklepu.

Checkout

• metoda pojawia się dla koszyka spełniającego warunki,
• metoda nie pojawia się, gdy brak pasującej stawki,
• restrykcja hide ukrywa metodę,
• restrykcja error pokazuje komunikat,
• extra fee pojawia się w totals po wyborze metody,
• zmiana metody wysyłki przelicza fee,
• order zawiera kwoty fee,
• invoice zawiera kwoty fee,
• creditmemo poprawnie refunduje fee.

Najczęstsze problemy

Metoda nie pojawia się w checkout

Sprawdź:

• czy carrier jest włączony,
• czy metoda jest aktywna,
• czy metoda ma aktywną stawkę,
• czy stawka pasuje do kraju, regionu, kodu pocztowego, wagi i subtotalu,
• czy store view jest poprawny,
• czy customer group jest poprawna,
• czy warunki metody są spełnione,
• czy restrykcja nie ukrywa metody.

Extra Fee nie nalicza się

Sprawdź:

• czy Enable Extra Fees = Yes,
• czy fee jest aktywne,
• czy target carrier i target method są poprawne,
• czy warunki fee są spełnione,
• czy wybrano metodę wysyłki,
• czy cena fee jest większa od zera,
• czy Stop Processing wcześniejszej reguły nie zatrzymał dalszego naliczania.

Restrykcja nie działa

Sprawdź:

• czy Enable Restrictions = Yes,
• czy restrykcja jest aktywna,
• czy target carrier i target method są poprawne,
• czy warunki restrykcji są spełnione,
• czy priorytet reguły jest właściwy,
• czy inna reguła z Stop Processing nie kończy przetwarzania wcześniej.

Podatek Extra Fee nie nalicza się

Sprawdź:

• czy Fee Tax Mode = Calculate by Fee Tax Class,
• czy reguła fee ma ustawiony Tax Class ID,
• czy konfiguracja podatkowa Magento zwraca stawkę podatku dla adresu,
• czy koszyk ma adres dostawy,
• czy fee jest faktycznie naliczone.

Dobre praktyki

• Najpierw konfiguruj proste reguły, potem dodawaj kolejne warunki.
• Dla każdej ważnej reguły przygotuj koszyk testowy.
• Używaj czytelnych nazw metod, restrykcji i fee.
• Unikaj kilku bardzo podobnych reguł o tym samym priorytecie.
• Dokumentuj powód utworzenia restrykcji lub fee w nazwie.
• Po zmianie atrybutów produktów wykonaj test checkoutu.
• Debug logging włączaj tylko na czas diagnozy.
• Migrację z Amasty wykonuj etapami: raport, dry-run, preview, execute, QA.

Dokumenty powiązane

• README.md — techniczny opis modułu dla programistów.
• docs/WDROZENIE.md — szczegółowa dokumentacja wdrożeniowa i architektura.
• docs/OPIS_MARKETINGOWY.md — opis marketingowy modułu.