Instrucțiuni de instalare și configurare

1. Cerințe

Modulul este destinat pentru Magento 2 și pentru instalări gestionate prin Composer.

Necesar:

• proiect Magento 2 gestionat prin Composer,
• versiune PHP compatibilă cu instalarea Magento utilizată,
• acces la Magento CLI,
• OpenAI API key,
• proces Magento Message Queue consumer funcțional.

Pachetul modulului:

kowal/module-ai-email-theme-generator

Numele modulului Magento:

Kowal_AiEmailThemeGenerator

2. Instalare

Adaugă repository-ul Composer:

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

Dacă repository-ul este privat, configurează autentificarea GitHub:

composer config --global --auth github-oauth.github.com 

Instalează modulul:

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

Activează modulul:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Rulează actualizarea Magento:

bin/magento setup:upgrade

Curăță cache-ul:

bin/magento cache:flush

Pentru modul de producție, rulează comenzile standard de deployment folosite în proiect, de exemplu:

bin/magento setup:di:compilebin/magento setup:static-content:deploybin/magento cache:flush

3. Queue Consumer

Generarea AI este procesată asincron prin Magento Message Queue.

Pornește consumerul manual:

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

În mediile de producție, configurează consumerul sub supervisor, systemd sau un alt manager de procese folosit de hosting.

Modulul creează sarcini în panoul de administrare, dar cererea către AI nu va fi procesată până când consumerul nu rulează.

4. Permisiuni de administrator

Modulul adaugă resurse ACL:

Kowal_AiEmailThemeGenerator::rootKowal_AiEmailThemeGenerator::jobsKowal_AiEmailThemeGenerator::generateKowal_AiEmailThemeGenerator::retryKowal_AiEmailThemeGenerator::cancelKowal_AiEmailThemeGenerator::applyKowal_AiEmailThemeGenerator::deleteKowal_AiEmailThemeGenerator::settings

Pentru ca administratorul să poată folosi modulul, atribuie resursele corespunzătoare în:

System > Permissions > User Roles

Pentru acces complet, permite resursa principală AI Email Generation și toate resursele subordonate.

5. Locația configurării

Mergi la:

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

Secțiunea de configurare conține grupul:

General Settings

6. Câmpuri de configurare

Enabled

Tip: Yes/No

Implicit: No

Activează sau dezactivează funcțiile modulului.

Când este setat la No:

• modulul nu ar trebui să creeze sarcini de generare AI,
• acțiunea de generare este blocată,
• administratorul ar trebui să configureze mai întâi modulul.

Setează Yes doar după pregătirea API key și pornirea queue consumerului.

API Provider

Tip: Select

Implicit: OpenAI

Definește furnizorul AI folosit de modul.

Implementarea actuală acceptă:

OpenAI

Câmpul există pentru ca în viitor să poată fi adăugați alți provideri fără schimbarea workflow-ului administratorului.

OpenAI API Key

Tip: câmp ascuns/criptat

Stochează OpenAI API key folosită pentru generare.

Valoarea este criptată de Magento folosind:

MagentoConfigModelConfigBackendEncrypted

Important:

• nu plasa API key direct în cod,
• nu face commit pentru chei de mediu,
• limitează accesul la acest câmp prin ACL,
• folosește o cheie cu permisiuni adecvate proiectului.

OpenAI Model

Tip: Select

Definește modelul OpenAI folosit pentru generare.

Exemplu:

gpt-4.1

Lista este preluată dinamic din OpenAI Models API folosind API key configurată. Modulul filtrează răspunsul la identificatori de modele GPT și cache-uiește lista pentru scurt timp, pentru a nu apela API-ul la fiecare deschidere a configurării.

Dacă API key nu a fost încă salvată, câmpul va afișa o opțiune de rezervă și va cere administratorului să salveze cheia.

Dacă OpenAI API este temporar indisponibil, câmpul păstrează modelul configurat curent, dacă este posibil.

Folosește un model care acceptă tipul de date de intrare necesar:

• generare text pentru prompturi și conținutul șablonului,
• model care acceptă imagini, dacă se folosesc proiecte grafice de referință.

Modelul selectat influențează calitatea rezultatului, timpul de răspuns și costul.

Request Timeout

Tip: Number

Exemplu de valoare implicită:

120

Timpul maxim în secunde permis pentru cererea către OpenAI API.

Valori recomandate:

• 60 pentru generare text scurtă,
• 120 sau mai mult pentru generare HTML/CSS complexă,
• valori mai mari doar atunci când infrastructura permite sarcini mai lungi în coadă.

Timeoutul se referă la procesarea în fundal, nu la cererea formularului de administrare.

Maximum Retries

Tip: Number

Exemplu de valoare implicită:

2

Definește de câte ori consumerul poate relua automat o sarcină de generare nereușită.

Reluările sunt utile în cazul erorilor temporare, precum:

• timeout API,
• eroare temporară a providerului,
• rate limit,
• problemă de rețea.

Erorile permanente, de exemplu configurare incorectă sau răspuns AI nevalid, ar trebui verificate în detaliile sarcinii.

Technical Prompt

Tip: Textarea

Acest prompt este aplicat la fiecare comandă de generare. Ar trebui să conțină reguli tehnice care trebuie respectate întotdeauna.

Exemplu:

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.

Folosește acest câmp pentru instrucțiuni stabile, precum:

• păstrarea directivelor Magento,
• menținerea variabilelor obligatorii,
• evitarea JavaScriptului,
• returnarea exclusivă a JSON,
• scrierea de HTML compatibil cu clienții de e-mail,
• folosirea CSS în câmpul corect al rezultatului.

Nu folosi acest câmp pentru instrucțiuni creative unice. Pentru aceasta există AI Prompt în formularul șablonului.

Default User Prompt

Tip: Textarea

Acest prompt este afișat implicit în secțiunea AI a editorului de șabloane e-mail.

Exemplu:

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

Administratorul îl poate modifica înainte de crearea sarcinii de generare.

Folosește acest câmp pentru a seta o instrucțiune implicită practică pentru sarcini obișnuite de generare.

Allowed Design File Types

Tip: Text

Exemplu de valoare implicită:

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

Listă de extensii de fișiere permise pentru proiectul de referință opțional, separate prin virgule.

Exemple acceptate:

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

În producție, folosește o listă cât mai restrictivă. Nu permite tipuri de fișiere care nu sunt necesare în proces.

Maximum Design File Size

Tip: Number

Exemplu de valoare implicită:

5242880

Dimensiunea maximă a fișierului de referință în bytes.

Exemple:

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

Fișierele mari cresc dimensiunea payload-ului și pot încetini generarea sau depăși limitele providerului.

Automatically Apply Result

Tip: Yes/No

Implicit: No

Definește dacă rezultatul AI corect trebuie să suprascrie imediat câmpurile native ale șablonului Magento.

Când este setat la Yes, consumerul salvează rezultatul generat în:

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

Când este setat la No, rezultatul este stocat în sarcină, iar administratorul îl poate verifica înainte de aplicarea manuală.

Setare recomandată pentru producție:

No

Aprobarea manuală este mai sigură, deoarece rezultatul AI poate fi corect tehnic, dar poate necesita în continuare revizuire de brand, juridică sau de layout.

Keep Request and Response Payloads

Tip: Yes/No

Implicit: Yes

Definește dacă modulul salvează payload-urile complete ale cererii și răspunsului în înregistrarea sarcinii.

Când opțiunea este activată, detaliile sarcinii pot afișa:

• snapshotul șablonului trimis către AI,
• variabilele disponibile,
• prompturile,
• metadatele proiectului de referință,
• răspunsul AI.

Este util pentru debugging și audit.

În mediile de producție, verifică cerințele de confidențialitate înainte de activarea acestei opțiuni. Modulul nu ar trebui să trimită date reale ale clienților către AI, însă payload-urile pot conține în continuare conținut de șabloane sensibil din punct de vedere business.

Retention Days

Tip: Number

Exemplu de valoare implicită:

30

Definește cât timp ar trebui păstrate sarcinile vechi.

Această valoare documentează politica de retenție țintă. Proiectul o poate folosi pentru implementarea unei curățări ciclice conform cerințelor operaționale.

7. Exemplu: generarea șablonului New Order Confirmation for Guest

Acest exemplu descrie procesul complet de generare a unui șablon e-mail Magento îmbunătățit pentru:

New Order Confirmation for Guest

Pasul 1: Configurează modulul

Mergi la:

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

Setează:

Enabled = YesAPI Provider = OpenAIOpenAI API Key = OpenAI Model = gpt-4.1Request Timeout = 120Maximum Retries = 2Automatically Apply Result = NoKeep Request and Response Payloads = Yes

Salvează configurarea și curăță cache-ul dacă Magento solicită acest lucru.

Pasul 2: Pornește queue consumer

Rulează:

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

În timpul testelor, procesul ar trebui să ruleze permanent.

Pasul 3: Creează un șablon nativ Magento

Mergi la:

Marketing > Communications > Email Templates

Click pe:

Add New Template

În câmpul Template selectează:

New Order Confirmation for Guest

Click pe:

Load Template

Magento va completa câmpurile native:

• Template Subject
• Template Content
• Template Styles

Setează numele șablonului, de exemplu:

New Order Confirmation for Guest - AI Draft

Salvează șablonul.

Procesul de generare AI necesită un șablon salvat, deoarece sarcina trebuie să aibă un template_id persistent.

Pasul 4: Completează AI Prompt

După salvare, deschide din nou șablonul, dacă este necesar. Editorul standard de șabloane e-mail Magento conține secțiunea AI Email Generation.

În câmpul AI Prompt introdu instrucțiunea de business, de exemplu:

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.

Semnificația acestui câmp:

• descrie efectul de business așteptat,
• se referă doar la sarcina de generare concretă,
• poate conține instrucțiuni privind brandul, tonul comunicării, layoutul sau conținutul,
• nu ar trebui să conțină date API sau date reale ale clienților.

Pasul 5: Opțional, adaugă Design Reference

Folosește Design Reference dacă e-mailul generat ar trebui să urmeze o anumită direcție vizuală.

Fișiere exemplu:

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

Semnificația acestui câmp:

• oferă AI context vizual sau structural suplimentar,
• ajută la adaptarea șablonului la proiectul grafic,
• este opțional,
• trebuie să respecte limitele pentru extensii și dimensiunea fișierelor.

Dacă proiectul de referință nu este adăugat, AI va folosi doar conținutul șablonului, variabilele, promptul tehnic și promptul utilizatorului.

Pasul 6: Opțional, adaugă Error Screenshot

Folosește Error Screenshot dacă vrei să arăți AI o problemă curentă de randare, layout sau validare a șablonului.

Exemple:

• captură de ecran cu un antet aliniat greșit,
• screenshot al unei probleme cu bannerul,
• previzualizare a e-mailului cu spațiere incorectă,
• captură din clientul de e-mail care arată o problemă de responsivitate,
• screenshot al unui mesaj de eroare dintr-un instrument de testare.

Acest câmp este transmis către AI ca secțiune JSON separată:

{ '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.' }}

Semnificația acestui câmp:

• arată AI eroarea curentă care trebuie remediată,
• nu este un proiect grafic sau un model al aspectului țintă,
• ajută AI să înțeleagă ce nu funcționează în prezent,
• ar trebui folosit împreună cu o descriere clară a problemei în AI Prompt.

Exemplu de prompt:

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.

Pasul 7: Adaugă AI Assets structurate

Editorul conține zona AI Assets. Aceste resurse sunt salvate lângă șablonul Magento și transmise către AI ca URL-uri media frontend grupate.

Grupuri de resurse disponibile:

Fiecare resursă poate conține:

Pentru bannere și iconițe, click pe:

Add BannerAdd Icon

Modulul salvează resursele încărcate în Magento media storage și transmite către AI URL-uri frontend publice în structura:

{ '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 } ] }}

În prompturi, fă referire direct la aceste grupuri. Exemplu:

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.

Pasul 8: Selectează generarea după salvare

Activează:

Generate with AI after saving

Semnificația acestui câmp:

• Magento salvează mai întâi șablonul prin acțiunea nativă standard save,
• după salvarea corectă, modulul creează o sarcină de generare AI,
• proiectul de referință încărcat este atașat la sarcină,
• sarcina este procesată asincron de queue consumer.

Dacă checkboxul nu este bifat, salvarea șablonului funcționează exact ca salvarea standard Magento și nu va fi creată nicio sarcină AI.

Pasul 9: Salvează șablonul

Click pe butonul standard Magento:

Save Template

După salvarea șablonului, modulul creează sarcina de generare.

În acest moment:

• salvarea nativă a șablonului este finalizată,
• statusul sarcinii începe cu pending,
• queue consumer procesează sarcina în fundal.

Pasul 10: Verifică sarcina

Mergi la:

Marketing > Communications > AI Email Generation Jobs

Deschide sarcina creată.

Cele mai importante câmpuri:

Statusuri tipice:

Pasul 11: Aplică rezultatul

Dacă Automatically Apply Result = No, rezultatul nu este salvat automat în șablonul Magento.

Verifică:

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

Dacă rezultatul este corect, click pe:

Apply Result

Modulul va salva valorile generate în câmpurile native ale șablonului Magento.

Pasul 12: Verifică șablonul e-mail nativ

Revino la:

Marketing > Communications > Email Templates

Deschide șablonul și verifică:

• Template Name a fost actualizat,
• Template Subject a fost actualizat,
• Template Content conține HTML-ul așteptat și directivele Magento,
• Template Styles conține CSS-ul așteptat,
• variabilele Magento obligatorii nu au fost eliminate.

Trimite un mesaj de test sau rulează un flux de comandă de test conform procesului standard QA al proiectului.

Pasul 13: Trimite o nouă corecție către AI

După aplicarea rezultatului prin Apply Result, versiunea curentă a șablonului este salvată în câmpurile native Magento. Aceasta înseamnă că următoarea comandă AI va porni de la această versiune, nu de la șablonul inițial.

Poți rafina de mai multe ori același șablon:

1. Aplică rezultatul AI prin Apply Result.
2. Redeschide șablonul în Marketing > Communications > Email Templates.
3. Introdu un prompt nou care descrie corecția concretă.
4. Dacă problema este vizuală, adaugă Error Screenshot.
5. Bifează Generate with AI after saving.
6. Salvează șablonul.
7. Verifică noua sarcină și aplică rezultatul dacă este corect.

În corecțiile următoare, tratează AI Prompt ca descriere a schimbării față de versiunea curentă. Cel mai bine este să indici:

• ce este incorect în prezent,
• ce efect trebuie obținut,
• ce elemente AI nu ar trebui să modifice,
• dacă Error Screenshot atașat arată o eroare de randare, layout vizual, problemă de responsivitate sau mesaj de validare.

Exemplu de prompt pentru o corecție ulterioară:

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.

Acest workflow este util atunci când prima versiune este aproape de efectul așteptat, dar necesită rafinarea detaliilor, precum spațieri, responsivitate, vizibilitatea bannerelor, poziția logo-ului sau stilul butoanelor.

Poți repeta acest ciclu de mai multe ori. Fiecare sarcină nouă creează o intrare separată în istoric, astfel încât se poate reveni la prompturi, payload-uri și răspunsuri AI anterioare pentru a verifica ce instrucțiune a dus la o anumită schimbare.

8. Semnificația câmpurilor payload-ului AI

Modulul trimite către AI un payload structurat. Cele mai importante secțiuni sunt:

template

Conține starea curentă a șablonului Magento:

• ID-ul șablonului,
• numele șablonului,
• subject,
• content,
• styles,
• codul original al șablonului.

AI folosește această secțiune ca material de bază pentru generare.

Important: dacă rezultatul AI a fost aplicat anterior prin Apply Result, secțiunea template conține deja această versiune actualizată. Astfel, următoarea generare poate funcționa ca o corecție pentru șablonul curent.

variables

Conține variabilele și directivele Magento detectate în șablon.

AI ar trebui să păstreze aceste valori și să nu inventeze variabile neacceptate.

prompts

Conține:

• technical - promptul tehnic global din configurare,
• user - promptul introdus în editorul șablonului.

Promptul tehnic protejează structura specifică Magento. Promptul utilizatorului descrie rezultatul așteptat pentru un singur șablon.

design_reference

Conține metadatele opționale și conținutul proiectului de referință încărcat.

Secțiunea este goală atunci când nu a fost încărcat niciun fișier de referință.

error_screenshot

Conține un screenshot opțional care arată erori curente de randare, layout, vizuale sau de validare.

Această secțiune are descrierile purpose și description, pentru ca AI să știe că fișierul servește la înțelegerea problemei, nu ca model al proiectului țintă.

Secțiunea este goală atunci când nu a fost încărcată nicio captură de ecran.

La corecțiile ulterioare, merită folosit error_screenshot împreună cu un prompt precis, care spune ce trebuie corectat și ce nu trebuie schimbat. Astfel, AI poate remedia o problemă concretă fără a reconstrui întregul șablon.

Exemplu: după aplicarea primului rezultat AI, administratorul observă că în Gmail bannerul se suprapune peste secțiunea de sumar al comenzii. În următoarea comandă, atașează un screenshot al acestei vizualizări și introduce un prompt care cere exclusiv remedierea spațierilor și lățimii bannerului. Payload-ul conține în continuare Template Content și Template Styles curente, deci AI lucrează pe ultima versiune salvată.

assets

Conține resursele grafice structurate salvate pentru șablon:

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

Fiecare resursă conține URL media public, label, alt text, target URL, sort order și filename.

AI ar trebui să folosească aceste URL-uri la construirea HTML-ului și nu ar trebui să inventeze adrese suplimentare pentru imagini.

store_context

Conține informații de bază despre magazin, precum:

• store ID,
• locale,
• base URL.

AI le poate folosi pentru a înțelege limba și contextul, dar nu ar trebui să primească date reale ale clienților sau comenzilor.

9. Depanare

Sarcina rămâne în statusul pending

Cea mai probabilă cauză:

• queue consumer nu rulează.

Verifică:

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

Pagina de configurare afișează access denied

Verifică permisiunile ACL pentru:

Kowal_AiEmailThemeGenerator::settings

După modificarea permisiunilor administratorului, deloghează-te și autentifică-te din nou.

Generarea se termină cu eroare de lipsă API key

Verifică:

OpenAI API Key

Asigură-te că modulul este activat și configurarea a fost salvată în scope-ul corect.

Rezultatul AI are status completed, dar șablonul nu a fost actualizat

Verifică:

Automatically Apply Result

Dacă opțiunea este setată la No, deschide sarcina și click pe:

Apply Result

Corecția următoare nu include rezultatul anterior

Verifică dacă rezultatul anterior a fost aplicat prin:

Apply Result

Generarea următoare se bazează pe șablonul Magento salvat curent. Dacă rezultatul jobului are status completed, dar nu a fost aplicat, următorul job va continua să se bazeze pe versiunea mai veche a șablonului.

Răspunsul AI a fost respins

Modulul validează JSON-ul returnat. Poate respinge rezultatul dacă:

• lipsesc câmpuri obligatorii,
• câmpurile obligatorii au tipuri incorecte,
• numele șablonului, subject sau content sunt goale,
• content conține tagul script,
• rezultatul nu este un JSON valid.

Verifică mesajul de eroare din sarcină și reia generarea cu un prompt mai clar.

10. Setări de producție recomandate

Valori inițiale recomandate:

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

Folosește aplicarea manuală a rezultatului până când echipa este sigură că prompturile, modelul selectat și regulile de validare produc șabloane consecvente.