Kowal ShippingRules — instrucțiuni de instalare, configurare și utilizare

Scopul documentului

Acest document descrie implementarea practică și utilizarea modulului Kowal_ShippingRules în Magento 2. Este destinat persoanelor responsabile de 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 pentru metodele de livrare,
• gestionarea taxelor suplimentare Extra Fee,
• diagnosticarea,
• migrarea din modulele Amasty,
• checklistul testelor după implementare.

Informații de bază

Denumirea tehnică a modulului:

Kowal_ShippingRules

Locația modulului:

vendor/kowal/module-shipping-rules

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 că:

• 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 al bazei de date,
• implementarea este realizată 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

Instalare prin Composer

Datele de acces la repository-ul Composer, adresa de e-mail a clientului și tokenul de licență, le veți primi prin e-mail după achiziție. Acestea sunt disponibile și în panoul clientului după autentificare pe kowal.store. Înlocuiți TWOJ_EMAIL_KLIENTA cu adresa de e-mail a contului dvs., iar TWOJ_TOKEN cu tokenul primit. Executați comenzile în directorul rădăcină Magento.

composer config repositories.kowal composer https://repo.kowal.storecomposer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'composer require kowal/module-shipping-rules

2. Activați modulul

bin/magento module:enable Kowal_ShippingRules

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

bin/magento module:enable Kowal_Base Kowal_ShippingRules

3. Actualizați 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. Compilați DI

În producție:

bin/magento setup:di:compile

5. Goliți cache-ul

bin/magento cache:flush

6. Verificați statusul modulului

bin/magento module:status Kowal_ShippingRules

Modulul ar trebui să se afle pe lista modulelor active.

Verificare după instalare

După instalare, rulați diagnosticarea:

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 al condițiilor,
• metode active fără tarife active,
• reguli Extra Fee cu tax class când modul de taxare este dezactivat.

Dacă această comandă returnează erori, modulul nu trebuie trecut în utilizare de producție înainte ca acestea să fie clarificate.

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 — denumirea grupului de metode vizibilă în checkout.
• Test Method Name — denumirea metodei de test de configurare.
• Test Method Price — prețul metodei de test de configurare.
• Sort Order — ordinea carrierului în lista metodelor de livrare.
• Show Method If Not Applicable — dacă se afișează o eroare atunci când nu există metode disponibile.
• Displayed Error Message — mesajul afișat 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ă detaliile deciziilor î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 — stabilește modul de gestionare a taxei pentru Extra Fee.

Moduri de taxare disponibile:

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

Setări implicite, 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 pentru metodele de livrare,
• Extra Fees — taxe suplimentare.

Gestionarea metodelor de livrare

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

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

• livrare pe paleți,
• transport special,
• livrare locală,
• curier pentru produse voluminoase,
• ridicare logistică,
• metodă disponibilă doar pentru anumite produse sau regiuni.

Crearea metodei

Accesați:

Sales / Shipping Methods & Rules / Shipping Methods

Apoi selectați Add New sau editați o metodă existentă.

Câmpuri tipice ale metodei:

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

Recomandări pentru câmpul Code:

• folosiți litere mici,
• nu folosiți caractere poloneze,
• nu folosiți spații,
• folosiți underscore în locul spațiilor.

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ă ar trebui să aibă cel puțin un tarif activ. Dacă metoda nu are un tarif care se potrivește, 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 livrarea pe paleți,
• 5% din valoarea coșului pentru transport special,
• tarif separat pentru anumite coduri poștale.

Condițiile metodei

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

Exemple:

• metodă disponibilă doar pentru produse dintr-o categorie selectată,
• metodă disponibilă doar pentru un anumit atribut de produs,
• metodă disponibilă doar pentru coșuri peste o anumită valoare,
• metodă disponibilă doar pentru o anumită țară de livrare.

Dacă nu există condiții, metoda este limitată doar de status, store view, customer group și un tarif corespunzător.

Gestionarea restricțiilor pentru metodele de livrare

Când se folosesc restricțiile?

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

Exemple:

• ascundeți lockerul pentru produse voluminoase,
• blocați livrarea internațională pentru o categorie selectată,
• afișați un mesaj că transportul expres nu este disponibil pentru produse la comandă,
• ascundeți metoda de livrare pentru o țară selectată.

Crearea restricției

Accesați:

Sales / Shipping Methods & Rules / Shipping Restrictions

Apoi selectați Add New sau editați o restricție existentă.

Câmpuri tipice:

• Is Active — dacă restricția funcționează.
• Name — denumire internă.
• Target Carrier — carrierul căruia i se aplică restricția.
• Target Method — metoda căreia i se aplică restricția.
• Action — modul de acțiune.
• Message — mesaj pentru client.
• Priority — prioritate.
• Stop Processing — dacă se oprește verificarea regulilor următoare.
• 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,
• potrivită pentru limitări evidente, de exemplu locker pentru produse voluminoase.

error:

• metoda va fi afișată ca indisponibilă,
• clientul va vedea mesajul,
• potrivită 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:

• folosiți priorități mai mari pentru reguli mai specifice,
• folosiți priorități mai mici pentru reguli generale,
• activați Stop Processing dacă regula trebuie să decidă definitiv disponibilitatea metodei.

Gestionarea Extra Fee

Când se folosește Extra Fee?

Extra Fee este utilizat pentru adăugarea unor 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

Accesați:

Sales / Shipping Methods & Rules / Extra Fees

Apoi selectați Add New sau editați o taxă existentă.

Câmpuri tipice:

• Is Active — dacă fee funcționează.
• Name — denumire internă.
• Label — denumirea taxei vizibilă în totals.
• Target Carrier — carrierul căruia i se aplică fee.
• Target Method — metoda căreia i se aplică fee.
• Price Type — tipul prețului.
• Price — valoarea taxei.
• Apply Mode — modul de calcul.
• Tax Class ID — clasa de taxare, dacă este utilizat tax mode.
• Priority — prioritate.
• Stop Processing — dacă se oprește calcularea taxelor fee următoare.
• Store Views — domeniul store view.
• Customer Groups — domeniul grupurilor de clienți.
• Conditions — condițiile de calcul.

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:

• taxă înmulțită cu cantitatea de produse.

per_matching_item:

• taxă calculată doar pentru produsele care îndeplinesc condițiile.

Exemplu:

Dacă taxa pentru protecție specială este de 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. Setați Fee Tax Mode la Calculate by Fee Tax Class.
2. Completați Tax Class ID în regula Extra Fee.
3. Testați coșul, order, invoice și creditmemo.

Taxa pentru Extra Fee trebuie verificată de fiecare dată cu configurarea fiscală a magazinului respectiv.

Gestionarea condițiilor

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

Condițiile pot viza, printre altele:

• atributele produselor,
• SKU,
• categorii,
• 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

Ipoteză:

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

Regulă:

Jeżeli produkt w koszyku ma shipping_type = pallet

Acțiuni posibile:

• afișați metoda Dostawa paletowa,
• ascundeți lockerul,
• adăugați fee Transport gabarytowy.

Recomandări pentru lucrul cu condițiile

• creați mai întâi o regulă simplă și testați-o în coș,
• evitați prea multe condiții într-o singură regulă,
• descrieți regulile cu denumiri clare,
• pentru regulile importante folosiți atribute de produs fără ambiguitate,
• după modificarea atributelor produselor, testați 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

Activați:

Enable Debug Logging = Yes

Recomandări:

• nu lăsați debug logging activ permanent în producție,
• activați debug doar pe durata diagnosticării,
• după finalizarea testelor, dezactivați debug,
• analizați logurile împreună cu coșul de test și configurarea regulilor.

Funcții de urgență

Dacă apare o problemă după implementare, se pot 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 din Amasty

Scopul migrării

Migrarea din Amasty are rolul de a ajuta la transferul configurării restricțiilor și extra fee în Kowal_ShippingRules.

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

Surse de date acceptate

Migratorul analizează:

amasty_shiprestriction_ruleamasty_extrafeeamasty_extrafee_option

Tabele țintă:

kowal_shipping_restrictionkowal_shipping_fee

Reguli de siguranță ale migrării

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 status 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ă traficul automat.

Pasul 1 — raport de bază

Rulați:

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 tabelele Kowal.

Pasul 2 — dry-run al transformării

Rulați:

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 acceptată de migratorul automat.

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

Pasul 3 — preview apply

Rulați:

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

Aceasta încă nu salvează date. Comanda arată câte înregistrări ar fi create, omise sau finalizate cu eroare.

Pasul 4 — apply pentru restricții

După acceptarea preview:

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

Comanda va salva doar restricțiile cu status ready.

Pasul 5 — apply pentru Extra Fee

După acceptarea preview:

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

Comanda va salva doar extra fees cu status ready.

Pasul 6 — diagnosticare după migrare

Rulați:

bin/magento kowal:shippingrules:stabilization:check

Verificați și panoul:

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

Pasul 7 — teste comparative cu Amasty

Înainte de dezactivarea sau înlocuirea configurării 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 o metodă selectată acoperită de Extra Fee.

Pentru fiecare coș, verificați:

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

Pasul 8 — decizia de comutare

Abia după acceptarea rezultatelor se poate planifica trecerea configurării de producție.

Recomandări:

• nu dezactivați Amasty fără backup,
• nu ștergeți datele Amasty imediat după migrare,
• mai întâi dezactivați funcționarea la nivel de configurare,
• păstrați posibilitatea de rollback,
• pregătiți o listă a regulilor care necesită corectare manuală.

Rollback după migrare

Dacă apare o problemă:

1. Dezactivați carrierul Kowal ShippingRules.
2. Dezactivați Enable Restrictions.
3. Dezactivați Enable Extra Fees.
4. Restabiliți configurarea Amasty existentă.
5. Verificați checkoutul.
6. Păstrați rapoartele de migrare pentru analiză.

Checklist după implementare

Tehnic

• module:status afișează Kowal_ShippingRules ca activ,
• setup:upgrade s-a finalizat fără erori,
• setup:di:compile s-a finalizat fără erori,
• cache:flush a fost executat,
• stabilization:check nu returnează erori,
• panoul de administrare afișează meniul Shipping Methods & Rules,
• fișierul de log este salvat 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 deliberat,
• extra fees sunt activate sau dezactivate în mod deliberat,
• tax mode este conform cu configurarea fiscală a magazinului.

Checkout

• metoda apare pentru un coș care îndeplinește condițiile,
• metoda nu apare când nu există un tarif corespunzător,
• 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 sumele fee,
• invoice conține sumele fee,
• creditmemo rambursează corect fee.

Cele mai frecvente probleme

Metoda nu apare în checkout

Verificați:

• 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ă

Verificați:

• 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 calcularea ulterioară.

Restricția nu funcționează

Verificați:

• 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ă o altă regulă cu Stop Processing nu încheie procesarea mai devreme.

Taxa pentru Extra Fee nu se calculează

Verificați:

• dacă Fee Tax Mode = Calculate by Fee Tax Class,
• dacă regula fee are setat Tax Class ID,
• dacă configurarea fiscală Magento returnează cota de taxă pentru adresă,
• dacă coșul are o adresă de livrare,
• dacă fee este efectiv calculat.

Bune practici

• Configurați mai întâi reguli simple, apoi adăugați condiții suplimentare.
• Pregătiți un coș de test pentru fiecare regulă importantă.
• Folosiți denumiri clare pentru metode, restricții și fee.
• Evitați mai multe reguli foarte similare cu aceeași prioritate.
• Documentați în denumire motivul creării restricției sau fee.
• După modificarea atributelor produselor, efectuați un test de checkout.
• Activați debug logging doar pe durata diagnosticării.
• Efectuați migrarea din Amasty pe etape: raport, dry-run, preview, execute, QA.

Documente conexe

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