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 gestionarea zilnică a regulilor de expediere.

Documentul include:

• instalarea modulului,
• configurarea de bază,
• crearea metodelor de expediere,
• 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 expediere în checkout are formatul:

kowal_shippingrules_

Exemplu:

kowal_shippingrules_dostawa_paletowa

Cerințe înainte de instalare

Înainte de instalare, confirmați că:

• magazinul rulează pe Magento 2.4.x,
• mediul utilizează PHP >=8.1,
• modulul Kowal_Base este disponibil,
• a fost efectuat un backup al fișierelor și bazei de date,
• implementarea este realizată mai întâi într-un mediu de test sau staging,
• după instalare va fi posibilă rularea setup:upgrade și setup:di:compile,
• persoana care testează are acces la panoul administrativ ș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ță, vor fi primite prin e-mail după achiziție. Sunt disponibile și în panoul clientului după autentificarea 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, acesta 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. Curățaț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 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 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 — numele grupului de metode vizibil în checkout.
• Test Method Name — numele metodei de configurare de test.
• Test Method Price — prețul metodei de configurare de test.
• Sort Order — ordinea carrierului în lista metodelor de livrare.
• Show Method If Not Applicable — dacă se afișează o eroare 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ă acest carrier este dezactivat, metodele create în modul nu vor fi disponibile în checkout.

Diagnostic ș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 fiscale setate în 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 expediere și tarife,
• Shipping Restrictions — restricții pentru metodele de livrare,
• Extra Fees — taxe suplimentare.

Gestionarea metodelor de expediere

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

O metodă de expediere 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 agabaritice,
• preluare logistică,
• metodă disponibilă doar pentru produse sau regiuni selectate.

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 — numele vizibil pentru client.
• Description — descrierea metodei.
• Sort Order — ordinea de afișare.
• Store Views — vizibilitatea pentru store view.
• Customer Groups — vizibilitatea pentru grupuri de clienți.
• Conditions — condițiile de disponibilitate ale metodei.

Recomandări pentru câmpul Code:

• folosiți litere mici,
• nu folosiți diacritice poloneze,
• nu folosiți spații,
• folosiți 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ă ar trebui 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 produselor,
• tipul de expediere,
• prioritate.

Moduri de preț:

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

Exemple:

• preț 29 zł pentru expedieri de până la 30 kg,
• preț 149 zł pentru livrare pe paleți,
• 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:

• metodă disponibilă doar pentru produsele dintr-o categorie selectată,
• metodă disponibilă doar pentru un anumit atribut al produsului,
• metodă disponibilă doar pentru un coș peste o anumită valoare,
• metodă disponibilă doar pentru țara de livrare selectată.

Dacă nu există condiții, metoda este limitată doar de status, store view, customer group și tariful potrivit.

Gestionarea restricțiilor pentru metodele de livrare

Când se folosesc restricțiile?

Restricțiile sunt utilizate pentru ascunderea sau blocarea metodelor de expediere care nu ar trebui să fie disponibile pentru o anumită comandă.

Exemple:

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

Crearea restricțiilor

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 — nume intern.
• Target Carrier — carrierul vizat de restricție.
• Target Method — metoda vizată de restricție.
• 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ții de potrivire.

Acțiunile restricției

hide:

• metoda va fi ascunsă,
• clientul nu o va vedea,
• potrivită pentru limitări evidente, de exemplu locker pentru colete în cazul gabaritelor.

error:

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

Prioritate și Stop Processing

Regulile sunt verificate conform priorității. O prioritate mai mare înseamnă verificare mai devreme.

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

Recomandare:

• folosiți priorități mai mari pentru reguli mai detaliate,
• 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 taxelor suplimentare la comandă.

Exemple:

• taxă pentru ambalare nestandard,
• supliment pentru transport agabaritic,
• taxă pentru produse fragile,
• taxă logistică pentru o anumită metodă de livrare,
• supliment 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 — nume intern.
• Label — numele taxei vizibil în totals.
• Target Carrier — carrierul vizat de fee.
• Target Method — metoda vizată de fee.
• Price Type — tipul prețului.
• Price — valoarea taxei.
• Apply Mode — modul de calculare.
• Tax Class ID — clasa fiscală, 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 calculare.

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 calculare

cart:

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

per_item:

• taxă înmulțită cu cantitatea produselor.

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 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 Extra Fee trebuie verificată de fiecare dată cu configurația fiscală a magazinului respectiv.

Gestionarea condițiilor

Modulul utilizează 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 produselor,
• țara de livrare,
• regiunea,
• orașul,
• codul poștal,
• cuponul,
• metoda de expediere selectată.

Exemplu de condiție pentru un produs agabaritic

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șați metoda Dostawa paletowa,
• ascundeți lockerul pentru colete,
• 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 nume clare,
• pentru regulile importante, folosiți atribute de produs fără ambiguitate,
• după modificarea atributelor produselor, testați din nou coșul.

Diagnostic și logare

Fișier 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 activat 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ă după implementare apare o problemă, 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 ajută la transferul configurației 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

Principii 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 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ă 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 tabelelor Amasty și 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 transformării, 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 restricții

După acceptarea preview:

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

Comanda va salva doar restricțiile cu statusul ready.

Pasul 5 — apply Extra Fee

După acceptarea preview:

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

Comanda va salva doar extra fees cu statusul ready.

Pasul 6 — diagnostic 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 configurației Amasty, comparați rezultatele pentru coșurile de test.

Coșuri recomandate:

• produs standard,
• produs agabaritic,
• 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ș, verificați:

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

Pasul 8 — decizia de comutare

Abia după acceptarea rezultatelor se poate planifica trecerea configurației 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 din configurare,
• păstrați posibilitatea de rollback,
• pregătiți lista regulilor care necesită corecție 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 configurația 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 administrativ afișează meniul Shipping Methods & Rules,
• fișierul log este salvat când debug este activat.

Configurare

• carrierul este activat,
• a fost creată cel puțin o metodă de expediere,
• 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 configurarea 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ă alegerea metodei,
• schimbarea metodei de expediere 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 țării, regiunii, codului poștal, greutății și subtotalului,
• 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 expediere,
• 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ă configurația fiscală Magento returnează o cotă de taxă pentru adresă,
• dacă coșul are adresă de livrare,
• dacă fee este într-adevăr calculat.

Bune practici

• Configurați mai întâi reguli simple, apoi adăugați condiții suplimentare.
• Pentru fiecare regulă importantă, pregătiți un coș de test.
• Folosiți nume clare pentru metode, restricții și fee.
• Evitați mai multe reguli foarte asemănătoare cu aceeași prioritate.
• Documentați motivul creării restricției sau fee în nume.
• 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 — descriere tehnică a modulului pentru dezvoltatori.
• docs/WDROZENIE.md — documentație detaliată de implementare și arhitectură.
• docs/OPIS_MARKETINGOWY.md — descriere marketing a modulului.