Kowal ShippingRules — ghid de instalare, configurare și utilizare

Scopul documentului

Acest document descrie implementarea practică și utilizarea modulului Kowal_ShippingRules în Magento 2. Este destinat persoanelor responsabile pentru instalarea modulului, configurarea magazinului, testele de implementare și administrarea zilnică a regulilor de livrare.

Documentul include:

• instalarea modulului,
• configurarea de bază,
• crearea metodelor de livrare,
• configurarea tarifelor,
• gestionarea restricțiilor metodelor de livrare,
• gestionarea taxelor suplimentare Extra Fee,
• diagnosticare,
• migrarea din modulele Amasty,
• checklistul testelor după implementare.

Informații de bază

Numele tehnic al modulului:

Kowal_ShippingRules

Locația modulului:

app/code/Kowal/ShippingRules

Codul carrierului:

kowal_shippingrules

Codul metodei de livrare în checkout are formatul:

kowal_shippingrules_

Exemplu:

kowal_shippingrules_dostawa_paletowa

Cerințe înainte de instalare

Înainte de instalare trebuie confirmat:

• magazinul rulează pe Magento 2.4.x,
• mediul folosește PHP >=8.1,
• modulul Kowal_Base este disponibil,
• a fost efectuat un backup al fișierelor și bazei de date,
• implementarea se realizează mai întâi pe un mediu de test sau staging,
• după instalare va exista posibilitatea de a rula setup:upgrade și setup:di:compile,
• persoana care testează are acces la panoul de administrare și la checkout.

Instalarea modulului

1. Încarcă modulul

Modulul trebuie să se afle în directorul:

app/code/Kowal/ShippingRules

2. Activează modulul

bin/magento module:enable Kowal_ShippingRules

Dacă Kowal_Base nu este încă activat, trebuie activat mai devreme sau împreună cu modulul:

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Actualizează baza de date

bin/magento setup:upgrade

Această comandă creează tabelele modulului și adaugă coloanele necesare pentru gestionarea Extra Fee în quote, order, invoice și creditmemo.

4. Compilează DI

În producție:

bin/magento setup:di:compile

5. Golește cache-ul

bin/magento cache:flush

6. Verifică statusul modulului

bin/magento module:status Kowal_ShippingRules

Modulul trebuie să se afle pe lista modulelor active.

Verificare după instalare

După instalare rulează diagnosticul:

bin/magento kowal:shippingrules:stabilization:check

Varianta completă în JSON:

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

Comanda este read-only și nu modifică datele. Verifică, printre altele:

• prezența tabelelor modulului,
• numărul de înregistrări,
• JSON incorect în condiții,
• metode active fără tarife active,
• reguli Extra Fee cu tax class la tax mode dezactivat.

Dacă această comandă returnează erori, modulul nu trebuie trecut în utilizare de producție înainte de clarificarea acestora.

Configurare de bază

Carrier

Calea în panoul Magento:

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

Câmpuri:

• Enabled — activează sau dezactivează carrierul kowal_shippingrules.
• Title — numele grupului de metode vizibil în checkout.
• Test Method Name — numele metodei de test din configurație.
• Test Method Price — prețul metodei de test din configurație.
• Sort Order — ordinea carrierului în lista metodelor de livrare.
• Show Method If Not Applicable — dacă să afișeze eroarea când nu există metode disponibile.
• Displayed Error Message — mesajul atunci când metoda nu este disponibilă.

Cea mai importantă setare:

carriers/kowal_shippingrules/active = 1

Dacă carrierul este dezactivat, metodele create în modul nu vor fi disponibile în checkout.

Diagnosticare și funcții de urgență

Calea în panoul Magento:

Stores / Configuration / Sales / Shipping Methods & Rules

Secțiunea General Diagnostics:

• Enable Debug Logging — salvează detalii despre decizii în log.
• Shadow Mode — mod pregătit pentru compararea comportamentului în timpul migrării.

Secțiunea Restrictions:

• Enable Restrictions — activează sau dezactivează doar restricțiile.

Secțiunea Extra Fees:

• Enable Extra Fees — activează sau dezactivează doar taxele suplimentare.
• Fee Tax Mode — definește modul de gestionare a taxei pentru Extra Fee.

Moduri de taxă disponibile:

• Do Not Calculate Tax — modulul nu calculează taxa pentru Extra Fee.
• Calculate by Fee Tax Class — modulul calculează taxa conform clasei de taxă setate în regula fee.

Setări implicite și sigure:

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

Meniul modulului în panou

Cale:

Sales / Shipping Methods & Rules

Secțiuni disponibile:

• Shipping Methods — metode de livrare și tarife,
• Shipping Restrictions — restricții ale metodelor de livrare,
• Extra Fees — taxe suplimentare.

Gestionarea metodelor de livrare

Când se creează o metodă de livrare?

Metoda de livrare trebuie creată atunci când magazinul are nevoie de o opțiune proprie de livrare, de exemplu:

• livrare pe palet,
• transport special,
• livrare locală,
• curier pentru produse voluminoase,
• ridicare logistică,
• metodă disponibilă doar pentru produse sau regiuni selectate.

Crearea metodei

Accesează:

Sales / Shipping Methods & Rules / Shipping Methods

Apoi selectează Add New sau editează o metodă existentă.

Câmpuri tipice ale metodei:

• Is Active — dacă metoda este activă.
• Code — codul tehnic al metodei.
• Name — numele vizibil pentru client.
• Description — descrierea metodei.
• Sort Order — ordinea de afișare.
• Store Views — vizibilitate pentru store view.
• Customer Groups — vizibilitate pentru grupurile de clienți.
• Conditions — condițiile de disponibilitate ale metodei.

Recomandări pentru câmpul Code:

• folosește litere mici,
• nu folosi diacritice poloneze,
• nu folosi spații,
• folosește underscore în loc de spații.

Exemple:

dostawa_paletowatransport_specjalnykurier_gabarytdostawa_lokalna

Codul complet al metodei în checkout va avea prefixul carrierului:

kowal_shippingrules_dostawa_paletowa

Tarifele metodei

O metodă activă trebuie să aibă cel puțin un tarif activ. Dacă metoda nu are un tarif potrivit, nu va apărea în checkout.

Tariful poate depinde de:

• țară,
• regiune,
• cod poștal,
• valoarea coșului,
• greutate,
• cantitatea de produse,
• tipul de livrare,
• prioritate.

Moduri de preț:

• fixed — preț fix,
• percent_subtotal — procent din subtotal.

Exemple:

• preț de 29 zł pentru expedieri de până la 30 kg,
• preț de 149 zł pentru livrare pe palet,
• 5% din valoarea coșului pentru transport special,
• tarif separat pentru coduri poștale selectate.

Condițiile metodei

Condițiile stabilesc când metoda trebuie să fie disponibilă.

Exemple:

• metoda disponibilă doar pentru produse din categoria selectată,
• metoda disponibilă doar pentru un anumit atribut al produsului,
• metoda disponibilă doar pentru un coș peste o anumită valoare,
• metoda disponibilă doar pentru țara de livrare selectată.

Dacă condițiile sunt goale, metoda este limitată doar de status, store view, customer group și un tarif compatibil.

Gestionarea restricțiilor metodelor de livrare

Când se folosesc restricțiile?

Restricțiile sunt folosite pentru a ascunde sau bloca metodele de livrare care nu ar trebui să fie disponibile pentru o anumită comandă.

Exemple:

• ascunde lockerul pentru produse voluminoase,
• blochează livrarea internațională pentru o categorie selectată,
• afișează mesajul că transportul expres nu este disponibil pentru produse la comandă,
• ascunde metoda de livrare pentru o țară selectată.

Crearea unei restricții

Accesează:

Sales / Shipping Methods & Rules / Shipping Restrictions

Apoi selectează Add New sau editează o restricție existentă.

Câmpuri tipice:

• Is Active — dacă restricția funcționează.
• Name — nume intern.
• Target Carrier — carrierul la care se aplică restricția.
• Target Method — metoda la care se aplică restricția.
• Action — modul de acțiune.
• Message — mesajul pentru client.
• Priority — prioritate.
• Stop Processing — dacă se oprește verificarea ulterioară a regulilor.
• Store Views — domeniul store view.
• Customer Groups — domeniul grupurilor de clienți.
• Conditions — condițiile de potrivire.

Acțiuni ale restricției

hide:

• metoda va fi ascunsă,
• clientul nu o va vedea,
• bună pentru limitări evidente, de exemplu locker pentru gabarit.

error:

• metoda va fi afișată ca indisponibilă,
• clientul va vedea un mesaj,
• bună atunci când merită explicat motivul indisponibilității.

Prioritate și Stop Processing

Regulile sunt verificate în funcție de prioritate. O prioritate mai mare înseamnă verificare mai devreme.

Stop Processing = Yes înseamnă că după potrivirea acestei restricții, modulul nu mai verifică restricțiile următoare pentru această metodă.

Recomandare:

• folosește priorități mai mari pentru reguli mai detaliate,
• folosește priorități mai mici pentru reguli generale,
• activează Stop Processing dacă regula trebuie să decidă definitiv disponibilitatea metodei.

Gestionarea Extra Fee

Când se folosește Extra Fee?

Extra Fee este folosită pentru a adăuga taxe suplimentare la comandă.

Exemple:

• taxă pentru ambalare nestandard,
• suprataxă pentru transport voluminos,
• taxă pentru produse fragile,
• taxă logistică pentru o anumită metodă de livrare,
• suprataxă pentru regiuni selectate.

Crearea Extra Fee

Accesează:

Sales / Shipping Methods & Rules / Extra Fees

Apoi selectează Add New sau editează o taxă existentă.

Câmpuri tipice:

• Is Active — dacă fee este activă.
• Name — nume intern.
• Label — denumirea taxei vizibilă în totals.
• Target Carrier — carrierul la care se aplică fee.
• Target Method — metoda la care se aplică fee.
• Price Type — tipul prețului.
• Price — valoarea taxei.
• Apply Mode — modul de calcul.
• Tax Class ID — clasa de taxă, dacă este folosit tax mode.
• Priority — prioritate.
• Stop Processing — dacă se oprește calcularea ulterioară a fee.
• Store Views — domeniul store view.
• Customer Groups — domeniul grupurilor de clienți.
• Conditions — condițiile de aplicare.

Moduri de preț

fixed:

• sumă fixă,
• de exemplu 19 zł pentru ambalare.

percent_subtotal:

• procent din valoarea coșului,
• de exemplu 3% din valoarea comenzii.

Moduri de calcul

cart:

• o singură taxă pentru întregul coș.

per_item:

• taxa se înmulțește cu numărul de produse.

per_matching_item:

• taxa se aplică doar produselor care îndeplinesc condițiile.

Exemplu:

Dacă taxa pentru protecție specială este 5 zł, iar în coș există 3 produse care îndeplinesc condiția, modul per_matching_item va calcula 15 zł.

Taxa pentru Extra Fee

În mod implicit, taxa pentru Extra Fee nu este calculată:

kowal_shippingrules/fees/tax_mode = none

Pentru a calcula taxa:

1. Setează Fee Tax Mode la Calculate by Fee Tax Class.
2. Completează Tax Class ID în regula Extra Fee.
3. Testează coșul, order, invoice și creditmemo.

Taxa pentru Extra Fee trebuie verificată de fiecare dată în raport cu configurația fiscală a magazinului respectiv.

Gestionarea condițiilor

Modulul folosește un generator de condiții similar regulilor Magento.

Condițiile pot privi, printre altele:

• atributele produselor,
• SKU,
• categoriile,
• tipul produsului,
• greutatea,
• prețul,
• valoarea coșului,
• cantitatea de produse,
• țara de livrare,
• regiunea,
• orașul,
• codul poștal,
• cuponul,
• metoda de livrare selectată.

Exemplu de condiție pentru un produs voluminos

Presupunere:

• produsul are atributul shipping_type,
• valoarea pentru gabarit este pallet.

Regulă:

Jeżeli produkt w koszyku ma shipping_type = pallet

Acțiuni posibile:

• afișează metoda Dostawa paletowa,
• ascunde lockerul,
• adaugă fee Transport gabarytowy.

Recomandări pentru lucrul cu condițiile

• creează mai întâi o regulă simplă și testeaz-o în coș,
• evită prea multe condiții într-o singură regulă,
• denumește regulile cu nume clare,
• pentru regulile importante folosește atribute de produs fără ambiguități,
• după schimbarea atributelor produselor, testează din nou coșul.

Diagnosticare și logare

Fișier de log dedicat:

var/log/kowal_shipping_rules.log

Debug poate fi activat în:

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

Activează:

Enable Debug Logging = Yes

Recomandări:

• nu lăsa debug logging activ permanent în producție,
• activează debug doar pentru perioada de diagnosticare,
• după finalizarea testelor dezactivează debug,
• analizează logurile împreună cu coșul de test și configurația regulilor.

Funcții de urgență

Dacă după implementare apare o problemă, se poate dezactiva independent:

Întregul carrier

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

Efect:

• metodele din carrierul kowal_shippingrules nu vor fi disponibile.

Doar restricțiile

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

Efect:

• metodele nu vor fi ascunse sau blocate de restricții.

Doar Extra Fee

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

Efect:

• taxele suplimentare nu vor fi calculate.

Migrare de la Amasty

Scopul migrării

Migrarea de la Amasty are rolul de a ajuta la transferul configurației restricțiilor și extra fee către Kowal_ShippingRules.

Modulul Kowal nu necesită Amasty pentru funcționarea normală. Amasty poate fi folosit ca sursă de date de migrare și punct de referință în timpul testelor.

Surse de date suportate

Migratorul analizează:

amasty_shiprestriction_ruleamasty_extrafeeamasty_extrafee_option

Tabele țintă:

kowal_shipping_restrictionkowal_shipping_fee

Reguli de siguranță pentru migrare

Migrarea a fost proiectată cu prudență:

• raportul este read-only,
• dry-run nu salvează date,
• apply funcționează implicit ca preview,
• salvarea necesită opțiunea explicită --execute,
• sunt salvate doar înregistrările cu statusul ready,
• înregistrările manual_review și unsupported sunt omise,
• migrarea este idempotentă datorită câmpurilor migration_source și migration_source_key,
• migrarea nu dezactivează Amasty,
• migrarea nu comută automat traficul.

Pasul 1 — raport de bază

Rulează:

bin/magento kowal:shippingrules:amasty:report

Raportul va fi salvat în:

var/report/kowal_shippingrules_amasty_report.json

Raportul arată prezența și numărul de înregistrări din tabelele Amasty și din tabelele Kowal.

Pasul 2 — dry-run al transformării

Rulează:

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

Dry-run pregătește planul de transformare, dar nu salvează nimic.

Statusuri ale înregistrărilor:

• ready — înregistrarea poate fi transferată automat,
• manual_review — înregistrarea necesită analiză manuală,
• unsupported — înregistrarea nu este suportată de migratorul automat.

Dacă raportul conține multe manual_review sau unsupported, aceste reguli trebuie analizate înainte de apply.

Pasul 3 — preview apply

Rulează:

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

Acest lucru tot nu salvează date. Comanda arată câte înregistrări ar fi create, omise sau s-ar încheia cu eroare.

Pasul 4 — apply pentru restricții

După acceptarea previewului:

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

Comanda va salva doar restricțiile cu statusul ready.

Pasul 5 — apply pentru Extra Fee

După acceptarea previewului:

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

Comanda va salva doar extra fees cu statusul ready.

Pasul 6 — diagnosticare după migrare

Rulează:

bin/magento kowal:shippingrules:stabilization:check

Verifică și în panou:

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

Pasul 7 — teste comparative cu Amasty

Înainte de dezactivarea sau înlocuirea configurației Amasty, trebuie comparate rezultatele pentru coșurile de test.

Coșuri recomandate:

• produs standard,
• produs voluminos,
• produs fragil,
• mai multe produse cu condiții diferite,
• comandă cu țări de livrare diferite,
• comandă cu coduri poștale diferite,
• comandă cu cupon,
• comandă cu metoda selectată acoperită de Extra Fee.

Pentru fiecare coș verifică:

• metodele de livrare disponibile,
• metodele ascunse,
• mesajele de eroare,
• extra fee calculate,
• sumele brute/net, dacă este folosit tax fee,
• order,
• invoice,
• creditmemo.

Pasul 8 — decizia de comutare

Abia după acceptarea rezultatelor se poate planifica comutarea configurației de producție.

Recomandări:

• nu dezactiva Amasty fără backup,
• nu șterge datele Amasty imediat după migrare,
• mai întâi dezactivează funcționarea din configurație,
• păstrează posibilitatea de rollback,
• pregătește o listă a regulilor care necesită corecție manuală.

Rollback după migrare

Dacă apare o problemă:

1. Dezactivează carrierul Kowal ShippingRules.
2. Dezactivează Enable Restrictions.
3. Dezactivează Enable Extra Fees.
4. Restaurează configurația Amasty utilizată anterior.
5. Verifică checkoutul.
6. Păstrează rapoartele de migrare pentru analiză.

Checklist după implementare

Tehnic

• module:status afișează Kowal_ShippingRules ca activ,
• setup:upgrade s-a încheiat fără erori,
• setup:di:compile s-a încheiat fără erori,
• cache:flush executat,
• stabilization:check nu returnează erori,
• panoul de administrare afișează meniul Shipping Methods & Rules,
• fișierul de log este scris când debug este activat.

Configurare

• carrierul este activat,
• a fost creată cel puțin o metodă de livrare,
• metoda activă are un tarif activ,
• store views sunt setate corect,
• customer groups sunt setate corect,
• restricțiile sunt activate sau dezactivate în mod conștient,
• extra fees sunt activate sau dezactivate în mod conștient,
• tax mode este conform cu configurația fiscală a magazinului.

Checkout

• metoda apare pentru un coș care îndeplinește condițiile,
• metoda nu apare când nu există un tarif potrivit,
• restricția hide ascunde metoda,
• restricția error afișează mesajul,
• extra fee apare în totals după selectarea metodei,
• schimbarea metodei de livrare recalculează fee,
• order conține valorile fee,
• invoice conține valorile fee,
• creditmemo rambursează corect fee.

Cele mai frecvente probleme

Metoda nu apare în checkout

Verifică:

• dacă carrierul este activat,
• dacă metoda este activă,
• dacă metoda are un tarif activ,
• dacă tariful se potrivește cu țara, regiunea, codul poștal, greutatea și subtotalul,
• dacă store view este corect,
• dacă customer group este corect,
• dacă sunt îndeplinite condițiile metodei,
• dacă o restricție nu ascunde metoda.

Extra Fee nu se calculează

Verifică:

• dacă Enable Extra Fees = Yes,
• dacă fee este activă,
• dacă target carrier și target method sunt corecte,
• dacă sunt îndeplinite condițiile fee,
• dacă a fost selectată metoda de livrare,
• dacă prețul fee este mai mare decât zero,
• dacă Stop Processing al unei reguli anterioare nu a oprit calculul ulterior.

Restricția nu funcționează

Verifică:

• dacă Enable Restrictions = Yes,
• dacă restricția este activă,
• dacă target carrier și target method sunt corecte,
• dacă sunt îndeplinite condițiile restricției,
• dacă prioritatea regulii este corectă,
• dacă altă regulă cu Stop Processing nu încheie procesarea mai devreme.

Taxa pentru Extra Fee nu se calculează

Verifică:

• dacă Fee Tax Mode = Calculate by Fee Tax Class,
• dacă regula fee are setat Tax Class ID,
• dacă configurația fiscală Magento returnează cota de taxă pentru adresă,
• dacă coșul are adresă de livrare,
• dacă fee este într-adevăr calculată.

Bune practici

• Mai întâi configurează reguli simple, apoi adaugă condiții suplimentare.
• Pentru fiecare regulă importantă pregătește un coș de test.
• Folosește nume clare pentru metode, restricții și fee.
• Evită mai multe reguli foarte asemănătoare cu aceeași prioritate.
• Documentează motivul creării restricției sau fee în nume.
• După schimbarea atributelor produselor, efectuează un test de checkout.
• Activează debug logging doar pe durata diagnosticării.
• Efectuează migrarea din Amasty în etape: raport, dry-run, preview, execute, QA.

Documente asociate

• README.md — descriere tehnică a modulului pentru dezvoltatori.
• docs/WDROZENIE.md — documentație detaliată de implementare și arhitectură.
• docs/OPIS_MARKETINGOWY.md — descrierea de marketing a modulului.