Instrukcja instalacji i konfiguracji

1. Wymagania

Moduł jest przeznaczony dla Magento 2 i instalacji zarządzanej przez Composer.

Wymagane:

• projekt Magento 2 zarządzany przez Composer,
• wersja PHP zgodna z używaną instalacją Magento,
• dostęp do Magento CLI,
• OpenAI API key,
• działający proces Magento Message Queue consumer.

Paczka modułu:

kowal/module-ai-email-theme-generator

Nazwa modułu Magento:

Kowal_AiEmailThemeGenerator

2. Instalacja

Dodaj repozytorium Composer:

composer config repositories.ai.email.theme.generator vcs https://github.com/kowalco/ai-email-theme-generator

Jeżeli repozytorium jest prywatne, skonfiguruj uwierzytelnienie GitHub:

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

Zainstaluj moduł:

composer require kowal/module-ai-email-theme-generator

Włącz moduł:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Uruchom aktualizację Magento:

bin/magento setup:upgrade

Wyczyść cache:

bin/magento cache:flush

Dla trybu produkcyjnego uruchom standardowe komendy wdrożeniowe używane w projekcie, np.:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy
bin/magento cache:flush

3. Queue Consumer

Generowanie AI jest przetwarzane asynchronicznie przez Magento Message Queue.

Uruchom consumer ręcznie:

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

W środowiskach produkcyjnych skonfiguruj consumer pod supervisor, systemd albo innym menedżerem procesów używanym przez hosting.

Moduł tworzy zadania w panelu administracyjnym, ale żądanie do AI nie zostanie przetworzone, dopóki consumer nie działa.

4. Uprawnienia administratora

Moduł dodaje zasoby ACL:

Kowal_AiEmailThemeGenerator::root
Kowal_AiEmailThemeGenerator::jobs
Kowal_AiEmailThemeGenerator::generate
Kowal_AiEmailThemeGenerator::retry
Kowal_AiEmailThemeGenerator::cancel
Kowal_AiEmailThemeGenerator::apply
Kowal_AiEmailThemeGenerator::delete
Kowal_AiEmailThemeGenerator::settings

Aby administrator mógł korzystać z modułu, przypisz odpowiednie zasoby w:

System > Permissions > User Roles

Dla pełnego dostępu zezwól na główny zasób AI Email Generation oraz wszystkie zasoby podrzędne.

5. Lokalizacja konfiguracji

Przejdź do:

Stores > Configuration > AI Email Generation > AI Email Theme Generator

Sekcja konfiguracji zawiera grupę:

General Settings

6. Pola konfiguracji

Enabled

Typ: Yes/No

Domyślnie: No

Włącza lub wyłącza funkcje modułu.

Gdy ustawione jest No:

• moduł nie powinien tworzyć zadań generowania AI,
• akcja generowania jest blokowana,
• administrator powinien najpierw skonfigurować moduł.

Ustaw Yes dopiero po przygotowaniu API key i uruchomieniu queue consumera.

API Provider

Typ: Select

Domyślnie: OpenAI

Określa dostawcę AI używanego przez moduł.

Aktualna implementacja obsługuje:

OpenAI

Pole istnieje po to, aby w przyszłości można było dodać kolejnych providerów bez zmiany workflow administratora.

OpenAI API Key

Typ: pole ukrywane/szyfrowane

Przechowuje OpenAI API key używany do generowania.

Wartość jest szyfrowana przez Magento z użyciem:

Magento\Config\Model\Config\Backend\Encrypted

Ważne:

• nie umieszczaj API key bezpośrednio w kodzie,
• nie commituj kluczy środowiskowych,
• ogranicz dostęp do tego pola przez ACL,
• użyj klucza z uprawnieniami odpowiednimi dla projektu.

OpenAI Model

Typ: Select

Określa model OpenAI używany do generowania.

Przykład:

gpt-4.1

Lista jest pobierana dynamicznie z OpenAI Models API przy użyciu skonfigurowanego API key. Moduł filtruje odpowiedź do identyfikatorów modeli GPT i cache'uje listę przez krótki czas, aby nie wywoływać API przy każdym otwarciu konfiguracji.

Jeżeli API key nie został jeszcze zapisany, pole pokaże opcję awaryjną i poprosi administratora o zapisanie klucza.

Jeżeli OpenAI API jest chwilowo niedostępne, pole zachowuje aktualnie skonfigurowany model, o ile to możliwe.

Użyj modelu obsługującego potrzebny typ danych wejściowych:

• generowanie tekstowe dla promptów i treści szablonu,
• model obsługujący obrazy, jeśli używane są graficzne projekty referencyjne.

Wybrany model wpływa na jakość wyniku, czas odpowiedzi i koszt.

Request Timeout

Typ: Number

Przykład wartości domyślnej:

120

Maksymalny czas w sekundach dozwolony dla żądania do OpenAI API.

Rekomendowane wartości:

• 60 dla krótkiego generowania tekstowego,
• 120 lub więcej dla złożonego generowania HTML/CSS,
• wyższe wartości tylko wtedy, gdy infrastruktura pozwala na dłuższe zadania w kolejce.

Timeout dotyczy przetwarzania w tle, a nie żądania formularza administracyjnego.

Maximum Retries

Typ: Number

Przykład wartości domyślnej:

2

Określa, ile razy consumer może automatycznie ponowić nieudane zadanie generowania.

Ponowienia są przydatne przy błędach tymczasowych, takich jak:

• timeout API,
• tymczasowy błąd providera,
• rate limit,
• problem sieciowy.

Błędy trwałe, np. niepoprawna konfiguracja albo nieprawidłowa odpowiedź AI, powinny zostać sprawdzone w szczegółach zadania.

Technical Prompt

Typ: Textarea

Ten prompt jest stosowany przy każdym zleceniu generowania. Powinien zawierać reguły techniczne, które zawsze muszą zostać zachowane.

Przykład:

You are an assistant generating Magento 2 email templates.
Return only JSON that matches the provided schema.
Keep Magento directives valid.
Do not invent Magento variables.
Do not add JavaScript.
Put CSS in template_styles unless inline styles are required for email compatibility.
Preserve required variables and add warnings when a requested change is risky.
When assets are provided, use only the URLs from the assets section, preserve alt text, apply target links to clickable images, use banners and icons according to their sort_order, and do not invent additional image URLs.

Używaj tego pola dla stabilnych instrukcji, takich jak:

• zachowywanie dyrektyw Magento,
• utrzymywanie wymaganych zmiennych,
• unikanie JavaScriptu,
• zwracanie wyłącznie JSON,
• pisanie HTML kompatybilnego z klientami pocztowymi,
• używanie CSS we właściwym polu wyniku.

Nie używaj tego pola do jednorazowych instrukcji kreatywnych. Do tego służy AI Prompt w formularzu szablonu.

Default User Prompt

Typ: Textarea

Ten prompt jest domyślnie pokazywany w sekcji AI edytora szablonu e-mail.

Przykład:

Improve this Magento email template while keeping all required Magento variables and directives valid.

Administrator może go zmienić przed utworzeniem zadania generowania.

Użyj tego pola, aby ustawić praktyczną domyślną instrukcję dla typowych zadań generowania.

Allowed Design File Types

Typ: Text

Przykład wartości domyślnej:

png,jpg,jpeg,webp,html,htm,txt

Lista dozwolonych rozszerzeń plików dla opcjonalnego projektu referencyjnego, rozdzielona przecinkami.

Obsługiwane przykłady:

• png
• jpg
• jpeg
• webp
• html
• htm
• txt

W produkcji używaj możliwie restrykcyjnej listy. Nie dopuszczaj typów plików, które nie są potrzebne w procesie.

Maximum Design File Size

Typ: Number

Przykład wartości domyślnej:

5242880

Maksymalny rozmiar pliku referencyjnego w bajtach.

Przykłady:

• 1048576 = 1 MB
• 5242880 = 5 MB
• 10485760 = 10 MB

Duże pliki zwiększają rozmiar payloadu i mogą spowolnić generowanie albo przekroczyć limity providera.

Automatically Apply Result

Typ: Yes/No

Domyślnie: No

Określa, czy poprawny wynik AI ma od razu nadpisać natywne pola szablonu Magento.

Gdy ustawione jest Yes, consumer zapisuje wygenerowany wynik do:

• Template Name
• Template Subject
• Template Content
• Template Styles

Gdy ustawione jest No, wynik jest przechowywany w zadaniu i administrator może go sprawdzić przed ręcznym zastosowaniem.

Rekomendowane ustawienie produkcyjne:

No

Ręczna akceptacja jest bezpieczniejsza, ponieważ wynik AI może być technicznie poprawny, ale nadal wymagać przeglądu marki, prawnego albo layoutowego.

Keep Request and Response Payloads

Typ: Yes/No

Domyślnie: Yes

Określa, czy moduł zapisuje pełne payloady żądania i odpowiedzi w rekordzie zadania.

Gdy opcja jest włączona, szczegóły zadania mogą pokazywać:

• snapshot szablonu wysłany do AI,
• dostępne zmienne,
• prompty,
• metadane projektu referencyjnego,
• odpowiedź AI.

Jest to przydatne przy debugowaniu i audycie.

W środowiskach produkcyjnych sprawdź wymagania prywatności przed włączeniem tej opcji. Moduł nie powinien wysyłać realnych danych klientów do AI, ale payloady mogą nadal zawierać wrażliwą biznesowo treść szablonów.

Retention Days

Typ: Number

Przykład wartości domyślnej:

30

Określa, jak długo stare zadania powinny być przechowywane.

Ta wartość dokumentuje docelową politykę retencji. Projekt może użyć jej do wdrożenia cyklicznego czyszczenia zgodnie z wymaganiami operacyjnymi.

7. Przykład: wygenerowanie szablonu New Order Confirmation for Guest

Ten przykład opisuje pełny proces wygenerowania ulepszonego szablonu e-mail Magento dla:

New Order Confirmation for Guest

Krok 1: Skonfiguruj moduł

Przejdź do:

Stores > Configuration > AI Email Generation > AI Email Theme Generator

Ustaw:

Enabled = Yes
API Provider = OpenAI
OpenAI API Key = <your OpenAI API key>
OpenAI Model = gpt-4.1
Request Timeout = 120
Maximum Retries = 2
Automatically Apply Result = No
Keep Request and Response Payloads = Yes

Zapisz konfigurację i wyczyść cache, jeśli Magento o to poprosi.

Krok 2: Uruchom queue consumer

Uruchom:

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

Podczas testów proces powinien działać cały czas.

Krok 3: Utwórz natywny szablon Magento

Przejdź do:

Marketing > Communications > Email Templates

Kliknij:

Add New Template

W polu Template wybierz:

New Order Confirmation for Guest

Kliknij:

Load Template

Magento uzupełni natywne pola:

• Template Subject
• Template Content
• Template Styles

Ustaw nazwę szablonu, np.:

New Order Confirmation for Guest - AI Draft

Zapisz szablon.

Proces generowania AI wymaga zapisanego szablonu, ponieważ zadanie musi mieć trwałe template_id.

Krok 4: Uzupełnij AI Prompt

Po zapisaniu otwórz szablon ponownie, jeśli to konieczne. Standardowy edytor szablonu e-mail Magento zawiera sekcję AI Email Generation.

W polu AI Prompt wpisz instrukcję biznesową, np.:

Create a modern, clean transactional email for a premium fashion store.
Keep all Magento order variables and directives valid.
Improve the subject line and make the content easier to scan.
Add a clear order summary section, shipping information section, and customer support footer.
Use neutral colors, simple spacing, and email-client-safe HTML.

Znaczenie tego pola:

• opisuje oczekiwany efekt biznesowy,
• dotyczy tylko konkretnego zadania generowania,
• może zawierać instrukcje dotyczące marki, tonu komunikacji, layoutu albo treści,
• nie powinno zawierać danych API ani realnych danych klientów.

Krok 5: Opcjonalnie dodaj Design Reference

Użyj Design Reference, jeśli wygenerowany e-mail powinien podążać za konkretnym kierunkiem wizualnym.

Przykładowe pliki:

• order-email-reference.png
• brand-email-layout.webp
• email-layout.html
• design-notes.txt

Znaczenie tego pola:

• daje AI dodatkowy kontekst wizualny albo strukturalny,
• pomaga dopasować szablon do projektu graficznego,
• jest opcjonalne,
• musi spełniać limity rozszerzeń i rozmiaru plików.

Jeżeli projekt referencyjny nie zostanie dodany, AI użyje tylko treści szablonu, zmiennych, promptu technicznego i promptu użytkownika.

Krok 6: Opcjonalnie dodaj Error Screenshot

Użyj Error Screenshot, jeśli chcesz pokazać AI aktualny problem z renderowaniem, layoutem albo walidacją szablonu.

Przykłady:

• zrzut ekranu źle wyrównanego nagłówka,
• screenshot problemu z bannerem,
• podgląd maila z błędnym odstępem,
• zrzut z klienta pocztowego pokazujący problem responsywności,
• screenshot komunikatu błędu z narzędzia testowego.

To pole jest przekazywane do AI jako osobna sekcja JSON:

{
  "error_screenshot": {
    "type": "image",
    "filename": "email-rendering-error.png",
    "mime_type": "image/png",
    "content_base64": "...",
    "purpose": "current_error_context",
    "description": "Screenshot showing current rendering, layout, visual, or validation errors. Use it to understand what should be fixed. This is not a design reference."
  }
}

Znaczenie tego pola:

• pokazuje AI aktualny błąd do naprawy,
• nie jest projektem graficznym ani wzorem docelowego wyglądu,
• pomaga AI zrozumieć, co obecnie nie działa,
• powinno być używane razem z jasnym opisem problemu w AI Prompt.

Przykład promptu:

Use the attached error screenshot only to understand the current rendering issue.
Fix the spacing problem visible in the screenshot while preserving Magento variables.
Do not treat the screenshot as the target design.

Krok 7: Dodaj strukturalne AI Assets

Edytor zawiera obszar AI Assets. Te zasoby są zapisywane przy szablonie Magento i przekazywane do AI jako pogrupowane frontendowe URL-e mediów.

Dostępne grupy zasobów:

Każdy zasób może zawierać:

Dla bannerów i ikon kliknij:

Add Banner
Add Icon

Moduł zapisuje przesłane zasoby w Magento media storage i przekazuje do AI publiczne frontendowe URL-e w strukturze:

{
  "assets": {
    "logo": {
      "label": "Brand logo",
      "url": "https://example.com/media/ai_email_theme_generator/template_12/logo/logo.png",
      "alt": "Brand logo",
      "link": "https://example.com/",
      "sort_order": 0
    },
    "header_image": {
      "label": "Spring campaign header",
      "url": "https://example.com/media/ai_email_theme_generator/template_12/header/header.jpg",
      "alt": "Spring collection",
      "link": "https://example.com/spring",
      "sort_order": 0
    },
    "banners": [
      {
        "label": "Main promotion",
        "url": "https://example.com/media/ai_email_theme_generator/template_12/banner/banner.jpg",
        "alt": "20% off new collection",
        "link": "https://example.com/new",
        "sort_order": 10
      }
    ],
    "icons": [
      {
        "label": "Free delivery",
        "url": "https://example.com/media/ai_email_theme_generator/template_12/icon/delivery.png",
        "alt": "Free delivery",
        "link": "https://example.com/delivery",
        "sort_order": 10
      }
    ]
  }
}

W promptach odwołuj się do tych grup wprost. Przykład:

Use the uploaded logo as the main brand mark.
Use the header image at the top of the email.
Place banners below the order summary using their sort order.
Use icons in a benefits row and link each icon to its target URL.
Always preserve alt text.

Krok 8: Wybierz generowanie po zapisie

Włącz:

Generate with AI after saving

Znaczenie tego pola:

• Magento najpierw zapisuje szablon standardową natywną akcją save,
• po poprawnym zapisie moduł tworzy zadanie generowania AI,
• przesłany projekt referencyjny zostaje dołączony do zadania,
• zadanie jest przetwarzane asynchronicznie przez queue consumer.

Jeżeli checkbox nie jest zaznaczony, zapis szablonu działa dokładnie jak standardowy zapis Magento i żadne zadanie AI nie zostanie utworzone.

Krok 9: Zapisz szablon

Kliknij standardowy przycisk Magento:

Save Template

Po zapisaniu szablonu moduł tworzy zadanie generowania.

W tym momencie:

• natywny zapis szablonu jest zakończony,
• status zadania zaczyna się od pending,
• queue consumer przetwarza zadanie w tle.

Krok 10: Sprawdź zadanie

Przejdź do:

Marketing > Communications > AI Email Generation Jobs

Otwórz utworzone zadanie.

Najważniejsze pola:

Typowe statusy:

Krok 11: Zastosuj wynik

Jeżeli Automatically Apply Result = No, wynik nie jest automatycznie zapisywany do szablonu Magento.

Sprawdź:

• Template Name
• Template Subject
• Template Content
• Template Styles
• Warnings
• Request Payload
• Response Payload

Jeżeli wynik jest poprawny, kliknij:

Apply Result

Moduł zapisze wygenerowane wartości do natywnych pól szablonu Magento.

Krok 12: Zweryfikuj natywny szablon e-mail

Wróć do:

Marketing > Communications > Email Templates

Otwórz szablon i sprawdź:

• Template Name został zaktualizowany,
• Template Subject został zaktualizowany,
• Template Content zawiera oczekiwany HTML i dyrektywy Magento,
• Template Styles zawiera oczekiwany CSS,
• wymagane zmienne Magento nie zostały usunięte.

Wyślij testową wiadomość albo uruchom testowy przepływ zamówienia zgodnie ze standardowym procesem QA projektu.

Krok 13: Wyślij kolejną poprawkę do AI

Po zastosowaniu wyniku przez Apply Result aktualna wersja szablonu jest zapisana w natywnych polach Magento. Oznacza to, że kolejne zlecenie AI będzie bazowało na tej wersji, a nie na pierwotnym szablonie.

Możesz wielokrotnie dopracowywać ten sam szablon:

1. Zastosuj wynik AI przez Apply Result.
2. Otwórz ponownie szablon w Marketing > Communications > Email Templates.
3. Wpisz nowy prompt opisujący konkretną poprawkę.
4. Jeśli problem jest wizualny, dodaj Error Screenshot.
5. Zaznacz Generate with AI after saving.
6. Zapisz szablon.
7. Sprawdź nowe zadanie i zastosuj wynik, jeśli jest poprawny.

W kolejnych poprawkach traktuj AI Prompt jak opis zmiany do aktualnej wersji. Najlepiej wskazać:

• co obecnie jest błędne,
• jaki efekt ma zostać osiągnięty,
• których elementów AI nie powinno zmieniać,
• czy załączony Error Screenshot pokazuje błąd renderowania, układ wizualny, problem responsywności albo komunikat walidacyjny.

Przykładowy prompt dla kolejnej poprawki:

Use the current saved template as the base.
Fix the spacing issue visible in the attached error screenshot.
Keep the current header layout, all Magento variables, and the existing Template Styles structure.
Do not redesign the whole email.

Ten workflow jest przydatny, gdy pierwsza wersja jest bliska oczekiwanego efektu, ale wymaga dopracowania szczegółów, takich jak odstępy, responsywność, widoczność bannerów, pozycja logo albo styl przycisków.

Możesz powtarzać ten cykl wiele razy. Każde nowe zadanie tworzy osobny wpis w historii, dlatego można wrócić do poprzednich promptów, payloadów i odpowiedzi AI, aby sprawdzić, która instrukcja doprowadziła do konkretnej zmiany.

8. Znaczenie pól payloadu AI

Moduł wysyła do AI strukturalny payload. Najważniejsze sekcje to:

template

Zawiera aktualny stan szablonu Magento:

• ID szablonu,
• nazwę szablonu,
• subject,
• content,
• styles,
• oryginalny kod szablonu.

AI używa tej sekcji jako materiału bazowego do generowania.

Ważne: jeżeli wcześniej zastosowano wynik AI przez Apply Result, sekcja template zawiera już tę zaktualizowaną wersję. Dzięki temu kolejne generowanie może działać jako poprawka do aktualnego szablonu.

variables

Zawiera zmienne i dyrektywy Magento wykryte w szablonie.

AI powinno zachować te wartości i nie powinno wymyślać nieobsługiwanych zmiennych.

prompts

Zawiera:

• technical - globalny prompt techniczny z konfiguracji,
• user - prompt wpisany w edytorze szablonu.

Prompt techniczny chroni strukturę specyficzną dla Magento. Prompt użytkownika opisuje oczekiwany wynik dla jednego szablonu.

design_reference

Zawiera opcjonalne metadane i treść przesłanego projektu referencyjnego.

Sekcja jest pusta, gdy nie przesłano pliku referencyjnego.

error_screenshot

Zawiera opcjonalny screenshot pokazujący aktualne błędy renderowania, layoutu, wizualne albo walidacyjne.

Ta sekcja ma opis purpose i description, aby AI wiedziało, że plik służy do zrozumienia problemu, a nie jako wzór docelowego projektu.

Sekcja jest pusta, gdy nie przesłano zrzutu ekranu.

Przy kolejnych poprawkach warto używać error_screenshot razem z precyzyjnym promptem, który mówi, co należy poprawić i czego nie należy zmieniać. Dzięki temu AI może naprawić konkretny problem bez przebudowy całego szablonu.

Przykład: po zastosowaniu pierwszego wyniku AI administrator zauważa, że w Gmailu banner nachodzi na sekcję podsumowania zamówienia. W kolejnym zleceniu dołącza screenshot tego widoku i wpisuje prompt proszący wyłącznie o naprawę odstępów oraz szerokości bannera. Payload nadal zawiera aktualny Template Content i Template Styles, więc AI pracuje na ostatniej zapisanej wersji.

assets

Zawiera strukturalne zasoby graficzne zapisane dla szablonu:

• logo,
• header image,
• banners,
• icons.

Każdy zasób zawiera publiczny URL mediów, label, alt text, target URL, sort order i filename.

AI powinno używać tych URL-i podczas budowania HTML i nie powinno wymyślać dodatkowych adresów obrazów.

store_context

Zawiera podstawowe informacje o sklepie, takie jak:

• store ID,
• locale,
• base URL.

AI może użyć ich do zrozumienia języka i kontekstu, ale nie powinno otrzymywać realnych danych klientów ani zamówień.

9. Rozwiązywanie problemów

Zadanie pozostaje w statusie pending

Najbardziej prawdopodobna przyczyna:

• queue consumer nie działa.

Sprawdź:

bin/magento queue:consumers:start kowal.ai_email.generate.consumer

Strona konfiguracji pokazuje access denied

Sprawdź uprawnienia ACL dla:

Kowal_AiEmailThemeGenerator::settings

Po zmianie uprawnień administratora wyloguj się i zaloguj ponownie.

Generowanie kończy się błędem braku API key

Sprawdź:

OpenAI API Key

Upewnij się, że moduł jest włączony i konfiguracja została zapisana we właściwym scope.

Wynik AI ma status completed, ale szablon nie został zaktualizowany

Sprawdź:

Automatically Apply Result

Jeżeli opcja jest ustawiona na No, otwórz zadanie i kliknij:

Apply Result

Kolejna poprawka nie uwzględnia poprzedniego wyniku

Sprawdź, czy poprzedni wynik został zastosowany przez:

Apply Result

Kolejne generowanie bazuje na aktualnie zapisanym szablonie Magento. Jeśli wynik joba ma status completed, ale nie został zastosowany, następny job nadal będzie bazował na starszej wersji szablonu.

Odpowiedź AI została odrzucona

Moduł waliduje zwrócony JSON. Może odrzucić wynik, jeśli:

• brakuje wymaganych pól,
• wymagane pola mają niepoprawne typy,
• nazwa szablonu, subject albo content są puste,
• content zawiera tag script,
• wynik nie jest poprawnym JSON-em.

Sprawdź komunikat błędu w zadaniu i ponów generowanie z jaśniejszym promptem.

10. Rekomendowane ustawienia produkcyjne

Rekomendowane wartości początkowe:

Enabled = Yes
Request Timeout = 120
Maximum Retries = 2
Automatically Apply Result = No
Keep Request and Response Payloads = Yes for testing, No or limited retention for production
Retention Days = 30

Używaj ręcznego stosowania wyniku do czasu, aż zespół będzie mieć pewność, że prompty, wybrany model i reguły walidacji dają spójne szablony.