Kowal_CheckoutComment

Opis

Kowal_CheckoutComment dodaje pole komentarza klienta w checkout Magento 2, zapisuje wartość w quote i order, udostępnia ją w siatce zamówień w panelu administracyjnym oraz wstrzykuje do zmiennych szablonów e-mail jako order_comment.

Dla kogo

  • Dla deweloperów Magento wdrażających niestandardowy przepływ danych w checkout
  • Dla DevOps/release engineerów wdrażających moduły ze zmianami checkout i DB
  • Dla administratorów sklepu konfigurujących zachowanie komentarza per scope

Funkcje

  • Dodaje komponent UI checkout pod sekcją płatności (afterMethods) przez plugin LayoutProcessor.
  • Używa mixina frontowego dla Magento_Checkout/js/action/place-order, aby przekazać checkout_comment do payment extension attributes.
  • Deklaruje extension attributes dla:
    • Magento\Quote\Api\Data\PaymentInterface
    • Magento\Quote\Api\Data\CartInterface
    • Magento\Sales\Api\Data\OrderInterface
  • Zapisuje komentarz do quote przez pluginy na:
    • Magento\Quote\Api\PaymentMethodManagementInterface::savePaymentInformationAndPlaceOrder
    • Magento\Quote\Model\PaymentMethodManagement::set
    • Magento\Quote\Model\QuoteRepository::save
  • Kopiuje komentarz z quote do order w observerze eventu sales_model_service_quote_submit_before.
  • Dodaje kolumny checkout_comment w DB (declarative schema) dla:
    • quote
    • sales_order
    • sales_order_grid
  • Rozszerza mapowanie kolumn resource modelu gridu zamówień i dodaje kolumnę UI w Adminie.
  • Dodaje Data Patch oznaczający atrybut zamówienia jako grid-enabled i wykonujący backfill sales_order_grid.checkout_comment z sales_order.
  • Dodaje zmienną order_comment do maili zamówień przez pluginy na SenderBuilder, TransportBuilder i TransportBuilderByStore.
  • Opcjonalny fallback źródła komentarza do maila z historii statusów zamówienia, kontrolowany flagą checkout_comment/general/all_frontend_comments.

Instalacja

* = in production please use the --keep-generated option

Type: Composer

  1. Add the composer repository to the configuration:

    
composer config repositories.checkout.comment vcs https://github.com/kowalco/magento-2-checkout-comment

  2. Add an access token for the private GitLab repository:

    
composer config --global --auth github-oauth.github.com <YOUR_TOKEN>

  3. Install the module using Composer:

    
composer require kowal/module-checkoutcomment

  4. Enable the module:

    
php bin/magento module:enable Kowal_CheckoutComment

  5. Apply database updates:

    
php bin/magento setup:upgrade

  6. Flush the cache:

    
php bin/magento cache:flush

Konfiguracja

  • Ścieżka w Adminie (system config): Stores > Configuration > kowal > Checkout Comment (section id: checkout_comment, group: general).
  • Pola:
    • checkout_comment/general/enable (Yes/No)
    • checkout_comment/general/all_frontend_comments (Yes/No)
  • Dostępność scope w system.xml: default, website, store view (wszystkie aktywne).
  • Odczyt runtime w helperze: scope sklepu (ScopeInterface::SCOPE_STORE).
  • Wartości domyślne (etc/config.xml):
    • enable = 1
    • all_frontend_comments = 0
  • Wpisy menu Admin są zdefiniowane w etc/adminhtml/menu.xml (w tym parent pod Kowal_Base::kowal_modules).
  • Uwaga ACL: moduł odwołuje się do zasobów ACL (Kowal_CheckoutComment::config, ::root, ::general), ale lokalnie nie dostarcza etc/acl.xml.

Wdrożenie i operacje

  • Uruchom php bin/magento setup:upgrade dla declarative schema i wykonania data patch.
  • Uruchom php bin/magento setup:di:compile w trybie produkcyjnym (pluginy, extension attributes, interceptory).
  • Uruchom deploy statycznych zasobów w trybie produkcyjnym dla assetów z view/frontend.
  • Wyczyść cache po wdrożeniu (config, layout, block_html, FPC zależnie od polityki).
  • Zweryfikuj render checkout:
    • W kroku płatności widoczne pole komentarza.
    • Złożenie zamówienia z komentarzem zapisuje wartość w zamówieniu.
  • Zweryfikuj Admin:
    • Siatka zamówień zawiera kolumnę Checkout Comment.
  • Zweryfikuj szablony e-mail:
    • Zmienna order_comment jest dostępna (snippet jest podany w sekcji Configuration w README).

Checklist wdrożeniowy

  • Paczka modułu zainstalowana przez Composer.
  • Moduł włączony (Kowal_CheckoutComment).
  • setup:upgrade zakończony powodzeniem.
  • Kolumny DB istnieją w quote, sales_order, sales_order_grid.
  • Data patch AddCheckoutCommentToGrid został zastosowany.
  • DI compile i static content deploy wykonane (produkcja).
  • Cache wyczyszczony.
  • Konfiguracja sprawdzona per wymagany scope (default/website/store view).
  • Komentarz checkout przechodzi od storefront do zamówienia.
  • Kolumna w gridzie i zmienne e-mail zweryfikowane.
  • Zależność kowal/base obecna i aktywna.

CI/CD i środowiska

  • Moduł nie definiuje własnych cronów, konsumentów kolejek ani custom indexerów.
  • Zalecane kroki w pipeline:
    • composer install
    • php bin/magento module:enable Kowal_CheckoutComment (jeśli nie jest pre-enabled)
    • php bin/magento setup:upgrade
    • php bin/magento setup:di:compile (produkcja)
    • php bin/magento setup:static-content:deploy (produkcja)
    • php bin/magento cache:flush
  • Walidacja środowiska powinna zawierać smoke test checkout + szablony e-mail end-to-end.

Rollback

  • Rollback kodu: cofnięcie wersji paczki Composer i wdrożenie poprzedniego lockfile.
  • Uwaga DB: moduł wprowadza kolumny schematu; usunięcie modułu wymaga jawnej strategii migracyjnej.
  • Po rollbacku uruchomić standardowe komendy wdrożeniowe Magento (setup:upgrade, odświeżenie cache) zgodnie ze stanem docelowym.

Wymagania / uwagi

  • Zależność Composer: kowal/base.
  • Zależność sekwencji modułu: Magento_Checkout.
  • Render w szablonach e-mail wymaga użycia order_comment po stronie template; moduł tylko wstrzykuje zmienną.
  • W kodzie są rozbudowane logi debug/error w pluginach checkout i e-mail.
  • Observer/Frontend/Checkout/SubmitAllAfter.php istnieje, ale nie jest podpięty w etc/events.xml.
  • Model danych zawiera zarówno declarative schema (db_schema.xml), jak i logikę data patch dotyczącą gridu.

Kompatybilność

  • Typ pakietu: moduł Magento 2 (type: magento2-module).
  • Brak jawnego ograniczenia wersji Magento w paczce.
  • Implementacja frontendu celuje w standardową architekturę checkout Knockout w Magento 2.

FAQ

Czy instalacja jest tylko przez Composer?

Tak. README zawiera wyłącznie ścieżkę instalacji Composer.

Gdzie dokładnie kontrolowany jest scope konfiguracji?

system.xml udostępnia default/website/store view. Odczyty runtime są wykonywane w scope store.

Czy moduł definiuje własny plik ACL?

Nie znaleziono etc/acl.xml w tym module.

Czy moduł definiuje cron, queue albo custom indexery?

Nie znaleziono definicji custom cron/queue/indexer.

Czy są luki wymagające ręcznej weryfikacji?

Tak:

  • Bloki kodu instalacji w README nie są domknięte w źródłowym tekście.
  • README wspomina „private GitLab repository”, ale komendy wskazują na GitHub OAuth i URL GitHub.
  • Ponieważ lokalnie nie ma definicji ACL, zachowanie uprawnień trzeba zweryfikować w środowisku docelowym.