Instrucțiuni de instalare și configurare

1. Cerințe

Modulul este destinat pentru Magento 2 și pentru o instalare gestionată prin Composer.

Cerințe:

• 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

Adăugați repository-ul 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 dumneavoastră, iar TWOJ_TOKEN cu tokenul primit. Executați comenzile în directorul rădăcină Magento.

composer config repositories.kowal composer https://repo.kowal.store

Configurați datele de acces la repository-ul Composer Kowal:

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Instalați modulul:

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

Activați modulul:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Rulați actualizarea Magento:

bin/magento setup:upgrade

Goliți cache-ul:

bin/magento cache:flush

Pentru modul de producție, rulați comenzile standard de deployment utilizate î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.

Porniți consumer-ul manual:

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

În mediile de producție, configurați consumer-ul sub supervisor, systemd sau un alt manager de procese utilizat de hosting.

Modulul creează joburi în panoul de administrare, însă cererea către AI nu va fi procesată până când consumer-ul nu rulează.

4. Permisiuni 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ă utiliza modulul, atribuiți resursele corespunzătoare în:

System > Permissions > User Roles

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

5. Locația configurării

Accesați:

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 joburi de generare AI,
• acțiunea de generare este blocată,
• administratorul ar trebui să configureze mai întâi modulul.

Setați Yes doar după pregătirea API key și pornirea queue consumer-ului.

API Provider

Tip: Select

Implicit: OpenAI

Definește furnizorul AI utilizat de modul.

Implementarea actuală acceptă:

OpenAI

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

OpenAI API Key

Tip: câmp ascuns/criptat

Stochează OpenAI API key utilizat pentru generare.

Valoarea este criptată de Magento folosind:

Magento\Config\Model\Config\Backend\Encrypted

Important:

• nu plasați API key direct în cod,
• nu comiteți chei de mediu,
• limitați accesul la acest câmp prin ACL,
• utilizați o cheie cu permisiuni adecvate pentru proiect.

OpenAI Model

Tip: Select

Definește modelul OpenAI utilizat pentru generare.

Exemplu:

gpt-4.1

Lista este preluată dinamic din OpenAI Models API folosind API key configurat. Modulul filtrează răspunsul la identificatorii modelelor 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 îi va solicita administratorului să salveze cheia.

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

Utilizați un model care acceptă tipul necesar de date de intrare:

• generare de text pentru prompturi și conținutul șablonului,
• model care acceptă imagini, dacă sunt utilizate 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 scurtă de text,
• 120 sau mai mult pentru generare HTML/CSS complexă,
• valori mai mari doar atunci când infrastructura permite joburi mai lungi în coadă.

Timeout-ul se referă la procesarea în fundal, nu la cererea formularului administrativ.

Maximum Retries

Tip: Number

Exemplu de valoare implicită:

2

Definește de câte ori consumer-ul poate reîncerca automat un job de generare eșuat.

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

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

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

Technical Prompt

Tip: Textarea

Acest prompt este aplicat la fiecare cerere 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.

Utilizați acest câmp pentru instrucțiuni stabile, precum:

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

Nu utilizați acest câmp pentru instrucțiuni creative punctuale. Pentru acestea se folosește AI Prompt din 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 jobului de generare.

Utilizați acest câmp pentru a seta o instrucțiune implicită practică pentru joburile tipice 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, separată prin virgule.

Exemple acceptate:

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

În producție, utilizați o listă cât mai restrictivă. Nu permiteți 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 payloadului și pot încetini generarea sau pot depăși limitele providerului.

Automatically Apply Result

Tip: Yes/No

Implicit: No

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

Când este setat la Yes, consumer-ul salvează rezultatul generat în:

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

Când este setat la No, rezultatul este stocat în job, 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 verificare de brand, juridică sau de layout.

Keep Request and Response Payloads

Tip: Yes/No

Implicit: Yes

Definește dacă modulul salvează payloadurile complete ale cererii și răspunsului în înregistrarea jobului.

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

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

Acest lucru este util pentru debugging și audit.

În mediile de producție, verificați 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ă payloadurile 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 joburile vechi.

Această valoare documentează politica țintă de retenție. Proiectul o poate utiliza pentru implementarea curățării 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: Configurați modulul

Accesați:

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

Setați:

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

Salvați configurația și goliți cache-ul, dacă Magento vă solicită acest lucru.

Pasul 2: Porniți queue consumer-ul

Rulați:

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

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

Pasul 3: Creați un șablon Magento nativ

Accesați:

Marketing > Communications > Email Templates

Faceți clic pe:

Add New Template

În câmpul Template selectați:

New Order Confirmation for Guest

Faceți clic pe:

Load Template

Magento va completa câmpurile native:

• Template Subject
• Template Content
• Template Styles

Setați numele șablonului, de exemplu:

New Order Confirmation for Guest - AI Draft

Salvați șablonul.

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

Pasul 4: Completați AI Prompt

După salvare, deschideți 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 introduceți instrucțiunea 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 business așteptat,
• se referă doar la jobul 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, adăugați Design Reference

Utilizați Design Reference dacă e-mailul generat ar trebui să urmeze o direcție vizuală concretă.

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 privind extensiile și dimensiunea fișierelor.

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

Pasul 6: Opțional, adăugați Error Screenshot

Utilizați Error Screenshot dacă doriți să arătați AI problema actuală de randare, layout sau validare a șablonului.

Exemple:

• captură de ecran cu un header 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ă problema de responsivitate,
• screenshot al mesajului de eroare din instrumentul 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 actuală care trebuie remediată,
• nu este un proiect grafic și nici un model al aspectului țintă,
• ajută AI să înțeleagă ce nu funcționează în prezent,
• ar trebui utilizat î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: Adăugați AI Assets structurale

Editorul conține zona AI Assets. Aceste resurse sunt salvate împreună cu ș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 pictograme, faceți clic pe:

Add BannerAdd Icon

Modulul salvează resursele încărcate în Magento media storage și transmite către AI URL-urile 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, faceți 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: Selectați generarea după salvare

Activați:

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ă un job de generare AI,
• proiectul de referință încărcat este atașat la job,
• jobul 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 niciun job AI.

Pasul 9: Salvați șablonul

Faceți clic pe butonul standard Magento:

Save Template

După salvarea șablonului, modulul creează un job de generare.

În acest moment:

• salvarea nativă a șablonului este finalizată,
• statusul jobului începe cu pending,
• queue consumer-ul procesează jobul în fundal.

Pasul 10: Verificați jobul

Accesați:

Marketing > Communications > AI Email Generation Jobs

Deschideți jobul creat.

Cele mai importante câmpuri:

Statusuri tipice:

Pasul 11: Aplicați rezultatul

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

Verificați:

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

Dacă rezultatul este corect, faceți clic pe:

Apply Result

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

Pasul 12: Verificați șablonul e-mail nativ

Reveniți la:

Marketing > Communications > Email Templates

Deschideți șablonul și verificați:

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

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

Pasul 13: Trimiteți o altă 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 cerere AI se va baza pe această versiune, nu pe șablonul inițial.

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

1. Aplicați rezultatul AI prin Apply Result.
2. Redeschideți șablonul în Marketing > Communications > Email Templates.
3. Introduceți un prompt nou care descrie corecția concretă.
4. Dacă problema este vizuală, adăugați Error Screenshot.
5. Bifați Generate with AI after saving.
6. Salvați șablonul.
7. Verificați noul job și aplicați rezultatul dacă este corect.

În corecțiile următoare, tratați AI Prompt ca pe descrierea modificării pentru versiunea curentă. Cel mai bine este să indicați:

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

Exemplu de prompt pentru următoarea corecție:

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, cum ar fi spațierile, responsivitatea, vizibilitatea bannerelor, poziția logo-ului sau stilul butoanelor.

Puteți repeta acest ciclu de mai multe ori. Fiecare job nou creează o intrare separată în istoric, astfel încât se poate reveni la prompturile, payloadurile și răspunsurile AI anterioare pentru a verifica ce instrucțiune a dus la o anumită modificare.

8. Semnificația câmpurilor payloadului AI

Modulul trimite către AI un payload structural. 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 utilizează această secțiune ca material de bază pentru generare.

Important: dacă anterior a fost aplicat rezultatul AI prin Apply Result, secțiunea template conține deja această versiune actualizată. Datorită acestui lucru, generarea următoare poate funcționa ca o corecție a șablonului curent.

variables

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

AI ar trebui să păstreze aceste valori și nu ar trebui să 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 un fișier de referință.

error_screenshot

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

Această secțiune are descrierea purpose și description, astfel încât 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 următoare, merită să utilizați error_screenshot împreună cu un prompt precis, care spune ce trebuie corectat și ce nu trebuie modificat. 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 cerere, atașează un screenshot al acestei vizualizări și introduce un prompt care solicită exclusiv corectarea spațierilor și a lățimii bannerului. Payloadul conține în continuare Template Content și Template Styles curente, astfel încât AI lucrează pe ultima versiune salvată.

assets

Conține resursele grafice structurale salvate pentru șablon:

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

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

AI ar trebui să utilizeze aceste URL-uri la construirea HTML și nu ar trebui să inventeze adrese suplimentare de 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

Jobul rămâne în statusul pending

Cea mai probabilă cauză:

• queue consumer-ul nu rulează.

Verificați:

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

Pagina de configurare afișează access denied

Verificați permisiunile ACL pentru:

Kowal_AiEmailThemeGenerator::settings

După modificarea permisiunilor administratorului, deconectați-vă și autentificați-vă din nou.

Generarea se încheie cu eroare de lipsă API key

Verificați:

OpenAI API Key

Asigurați-vă că modulul este activat și configurarea a fost salvată în scope-ul corect.

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

Verificați:

Automatically Apply Result

Dacă opțiunea este setată la No, deschideți jobul și faceți clic pe:

Apply Result

Corecția următoare nu ia în considerare rezultatul anterior

Verificați dacă rezultatul anterior a fost aplicat prin:

Apply Result

Generarea următoare se bazează pe șablonul Magento salvat curent. Dacă rezultatul jobului are statusul 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.

Verificați mesajul de eroare din job și reluați generarea cu un prompt mai clar.

10. Setări recomandate pentru producție

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

Utilizați aplicarea manuală a rezultatului până când echipa are certitudinea că prompturile, modelul selectat și regulile de validare generează șabloane consecvente.