Instrucciones de instalación y configuración

1. Requisitos

El módulo está destinado a Magento 2 y a una instalación gestionada mediante Composer.

Requisitos:

• proyecto Magento 2 gestionado mediante Composer,
• versión de PHP compatible con la instalación de Magento utilizada,
• acceso a Magento CLI,
• OpenAI API key,
• proceso Magento Message Queue consumer en funcionamiento.

Paquete del módulo:

kowal/module-ai-email-theme-generator

Nombre del módulo Magento:

Kowal_AiEmailThemeGenerator

2. Instalación

Añade el repositorio Composer:

Recibirás por e-mail los datos de acceso al repositorio Composer, dirección de e-mail del cliente y token de licencia, tras la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de correo electrónico de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

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

Configura los datos de acceso al repositorio Composer de Kowal:

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

Instala el módulo:

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

Activa el módulo:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Ejecuta la actualización de Magento:

bin/magento setup:upgrade

Limpia la caché:

bin/magento cache:flush

Para el modo de producción, ejecute los comandos estándar de despliegue utilizados en el proyecto, por ejemplo:

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

3. Queue Consumer

La generación AI se procesa de forma asíncrona mediante Magento Message Queue.

Ejecute el consumer manualmente:

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

En entornos de producción, configure el consumer con supervisor, systemd u otro gestor de procesos utilizado por el hosting.

El módulo crea tareas en el panel de administración, pero la solicitud a AI no se procesará hasta que el consumer esté en ejecución.

4. Permisos de administrador

El módulo añade recursos 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

Para que el administrador pueda utilizar el módulo, asigne los recursos correspondientes en:

System > Permissions > User Roles

Para acceso completo, permita el recurso principalAI Email Generationy todos los recursos secundarios.

5. Ubicación de la configuración

Ve a:

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

La sección de configuración contiene el grupo:

General Settings

6. Campos de configuración

Enabled

Tipo: Yes/No

Valor predeterminado: No

Activa o desactiva las funciones del módulo.

Cuando está establecido enNo:

• el módulo no debería crear tareas de generación AI,
• la acción de generación se bloquea,
• el administrador debe configurar primero el módulo.

ConfiguraYessolo después de preparar la API key e iniciar el queue consumer.

API Provider

Tipo: Select

Valor predeterminado: OpenAI

Define el proveedor de AI utilizado por el módulo.

La implementación actual admite:

OpenAI

El campo existe para que en el futuro se puedan añadir más providers sin cambiar el workflow del administrador.

OpenAI API Key

Tipo: campo oculto/cifrado

Almacena la OpenAI API key utilizada para la generación.

El valor es cifrado por Magento mediante:

Magento\Config\Model\Config\Backend\Encrypted

Importante:

• no coloque la API key directamente en el código,
• no haga commit de claves de entorno,
• limite el acceso a este campo mediante ACL,
• utilice una clave con permisos adecuados para el proyecto.

OpenAI Model

Tipo: Select

Define el modelo OpenAI utilizado para la generación.

Ejemplo:

gpt-4.1

La lista se obtiene dinámicamente desde OpenAI Models API utilizando la API key configurada. El módulo filtra la respuesta a identificadores de modelos GPT y almacena la lista en cache durante un breve periodo para no llamar a la API cada vez que se abre la configuración.

Si la API key aún no se ha guardado, el campo mostrará una opción de emergencia y solicitará al administrador que guarde la clave.

Si OpenAI API no está disponible temporalmente, el campo conserva el modelo configurado actualmente, siempre que sea posible.

Utilice un modelo compatible con el tipo de datos de entrada necesario:

• generación de texto para prompts y contenido de la plantilla,
• modelo compatible con imágenes si se utilizan diseños gráficos de referencia.

El modelo seleccionado influye en la calidad del resultado, el tiempo de respuesta y el coste.

Request Timeout

Tipo: Number

Ejemplo de valor predeterminado:

120

Tiempo máximo en segundos permitido para la solicitud a OpenAI API.

Valores recomendados:

• 60para generación de texto breve,
• 120o más para generación HTML/CSS compleja,
• valores superiores solo cuando la infraestructura permite tareas más largas en la cola.

El timeout se aplica al procesamiento en segundo plano, no a la solicitud del formulario administrativo.

Maximum Retries

Tipo: Number

Ejemplo de valor predeterminado:

2

Define cuántas veces el consumer puede reintentar automáticamente una tarea de generación fallida.

Los reintentos son útiles ante errores temporales, como:

• timeout de API,
• error temporal del provider,
• rate limit,
• problema de red.

Los errores permanentes, por ejemplo una configuración incorrecta o una respuesta AI no válida, deben revisarse en los detalles de la tarea.

Technical Prompt

Tipo: Textarea

Este prompt se aplica a cada solicitud de generación. Debe contener reglas técnicas que siempre deben conservarse.

Ejemplo:

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.

Utilice este campo para instrucciones estables, como:

• conservar directivas Magento,
• mantener las variables requeridas,
• evitar JavaScript,
• devolver únicamente JSON,
• escribir HTML compatible con clientes de correo,
• usar CSS en el campo correcto del resultado.

No utilice este campo para instrucciones creativas puntuales. Para ello sirveAI Prompten el formulario de la plantilla.

Default User Prompt

Tipo: Textarea

Este prompt se muestra por defecto en la sección AI del editor de plantillas de correo electrónico.

Ejemplo:

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

El administrador puede cambiarlo antes de crear la tarea de generación.

Utilice este campo para establecer una instrucción predeterminada práctica para tareas de generación habituales.

Allowed Design File Types

Tipo: Text

Ejemplo de valor predeterminado:

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

Lista de extensiones de archivo permitidas para el proyecto de referencia opcional, separadas por comas.

Ejemplos admitidos:

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

En producción, utilice una lista lo más restrictiva posible. No permita tipos de archivo que no sean necesarios en el proceso.

Maximum Design File Size

Tipo: Number

Ejemplo de valor predeterminado:

5242880

Tamaño máximo del archivo de referencia en bytes.

Ejemplos:

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

Los archivos grandes aumentan el tamaño del payload y pueden ralentizar la generación o superar los límites del provider.

Automatically Apply Result

Tipo: Yes/No

Valor predeterminado: No

Define si un resultado AI correcto debe sobrescribir inmediatamente los campos nativos de la plantilla Magento.

Cuando está establecido enYes, el consumer guarda el resultado generado en:

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

Cuando está establecido enNo, el resultado se almacena en la tarea y el administrador puede revisarlo antes de aplicarlo manualmente.

Configuración recomendada para producción:

No

La aceptación manual es más segura, porque el resultado AI puede ser técnicamente correcto, pero seguir requiriendo una revisión de marca, legal o de layout.

Keep Request and Response Payloads

Tipo: Yes/No

Valor predeterminado: Yes

Define si el módulo guarda los payloads completos de solicitud y respuesta en el registro de la tarea.

Cuando la opción está activada, los detalles de la tarea pueden mostrar:

• snapshot de la plantilla enviado a AI,
• variables disponibles,
• prompts,
• metadatos del proyecto de referencia,
• respuesta AI.

Esto resulta útil para depuración y auditoría.

En entornos de producción, revise los requisitos de privacidad antes de activar esta opción. El módulo no debería enviar datos reales de clientes a AI, pero los payloads aún pueden contener contenido de plantillas sensible desde el punto de vista empresarial.

Retention Days

Tipo: Number

Ejemplo de valor predeterminado:

30

Define durante cuánto tiempo deben conservarse las tareas antiguas.

Este valor documenta la política de retención objetivo. El proyecto puede utilizarlo para implementar una limpieza cíclica conforme a los requisitos operativos.

7. Ejemplo: generar la plantilla New Order Confirmation for Guest

Este ejemplo describe el proceso completo para generar una plantilla de correo Magento mejorada para:

New Order Confirmation for Guest

Paso 1: Configure el módulo

Ve a:

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

Configura:

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

Guarda la configuración y limpia la caché si Magento lo solicita.

Paso 2: Ejecute el queue consumer

Ejecuta:

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

Durante las pruebas, el proceso debe estar en ejecución todo el tiempo.

Paso 3: Cree una plantilla Magento nativa

Ve a:

Marketing > Communications > Email Templates

Haz clic en:

Add New Template

En el campoTemplate , seleccione:

New Order Confirmation for Guest

Haz clic en:

Load Template

Magento rellenará los campos nativos:

• Template Subject
• Template Content
• Template Styles

Establezca el nombre de la plantilla, por ejemplo:

New Order Confirmation for Guest - AI Draft

Guarde la plantilla.

El proceso de generación AI requiere una plantilla guardada, porque la tarea debe tener untemplate_id.

Paso 4: Complete el AI Prompt

Después de guardar, vuelva a abrir la plantilla si es necesario. El editor estándar de plantillas de correo electrónico de Magento incluye la secciónAI Email Generation.

En el campoAI Prompt , introduzca una instrucción de negocio, por ejemplo:

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.

Significado de este campo:

• describe el resultado de negocio esperado,
• se aplica solo a una tarea de generación concreta,
• puede incluir instrucciones sobre la marca, el tono de comunicación, el layout o el contenido,
• no debe contener datos de API ni datos reales de clientes.

Paso 5: Añada opcionalmente Design Reference

UtiliceDesign Referencesi el correo generado debe seguir una dirección visual concreta.

Archivos de ejemplo:

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

Significado de este campo:

• proporciona a AI contexto visual o estructural adicional,
• ayuda a adaptar la plantilla al diseño gráfico,
• es opcional,
• debe cumplir los límites de extensiones y tamaño de archivo.

Si no se añade ningún proyecto de referencia, AI usará solo el contenido de la plantilla, las variables, el prompt técnico y el prompt de usuario.

Paso 6: Añada opcionalmente Error Screenshot

UtiliceError Screenshotsi desea mostrar a AI el problema actual de renderizado, layout o validación de la plantilla.

Ejemplos:

• captura de pantalla de un encabezado mal alineado,
• screenshot de un problema con el banner,
• vista previa del email con espaciado incorrecto,
• captura desde el cliente de correo que muestra un problema de responsividad,
• screenshot de un mensaje de error de una herramienta de prueba.

Este campo se envía a AI como una sección JSON independiente:

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

Significado de este campo:

• muestra a AI el error actual que debe corregirse,
• no es un diseño gráfico ni un modelo del aspecto objetivo,
• ayuda a AI a entender qué no funciona actualmente,
• debe utilizarse junto con una descripción clara del problema enAI Prompt.

Ejemplo 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.

Paso 7: Añada AI Assets estructurales

El editor contiene el áreaAI Assets. Estos recursos se guardan con la plantilla Magento y se envían a AI como URL de medios frontend agrupadas.

Grupos de recursos disponibles:

Cada recurso puede contener:

Para banners e iconos, haga clic en:

Add Banner
Add Icon

El módulo guarda los recursos subidos en Magento media storage y envía a AI las URL frontend públicas en la estructura:

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

En los prompts, haga referencia a estos grupos de forma directa. Ejemplo:

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.

Paso 8: Seleccione la generación después de guardar

Active:

Generate with AI after saving

Significado de este campo:

• Magento primero guarda la plantilla mediante la acción nativa estándar save,
• tras guardarse correctamente, el módulo crea una tarea de generación AI,
• el proyecto de referencia enviado se adjunta a la tarea,
• la tarea se procesa de forma asíncrona mediante queue consumer.

Si la checkbox no está marcada, el guardado de la plantilla funciona exactamente como el guardado estándar de Magento y no se crea ninguna tarea AI.

Paso 9: Guarde la plantilla

Haga clic en el botón estándar de Magento:

Save Template

Después de guardar la plantilla, el módulo crea una tarea de generación.

En este momento:

• el guardado nativo de la plantilla ha finalizado,
• el estado de la tarea empieza enpending,
• el queue consumer procesa la tarea en segundo plano.

Paso 10: Revise la tarea

Ve a:

Marketing > Communications > AI Email Generation Jobs

Abra la tarea creada.

Campos más importantes:

Estados habituales:

Paso 11: Aplique el resultado

SiAutomatically Apply Result = No, el resultado no se guarda automáticamente en la plantilla Magento.

Comprueba:

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

Si el resultado es correcto, haga clic en:

Apply Result

El módulo guardará los valores generados en los campos nativos de la plantilla Magento.

Paso 12: Verifique la plantilla nativa de correo electrónico

Vuelva a:

Marketing > Communications > Email Templates

Abra la plantilla y revise:

• Template Name se ha actualizado,
• Template Subject se ha actualizado,
• Template Content contiene el HTML esperado y las directivas Magento,
• Template Styles contiene el CSS esperado,
• las variables Magento requeridas no se han eliminado.

Envíe un mensaje de prueba o ejecute un flujo de pedido de prueba conforme al proceso QA estándar del proyecto.

Paso 13: Envíe otra corrección a AI

Después de aplicar el resultado medianteApply Result, la versión actual de la plantilla queda guardada en los campos nativos de Magento. Esto significa que la siguiente solicitud AI se basará en esta versión, no en la plantilla original.

Puede perfeccionar la misma plantilla varias veces:

1. Aplique el resultado AI medianteApply Result.
2. Vuelva a abrir la plantilla enMarketing > Communications > Email Templates.
3. Introduzca un nuevo prompt que describa la corrección concreta.
4. Si el problema es visual, añadaError Screenshot.
5. MarqueGenerate with AI after saving.
6. Guarde la plantilla.
7. Revise la nueva tarea y aplique el resultado si es correcto.

En las siguientes correcciones, trateAI Promptcomo una descripción del cambio para la versión actual. Lo mejor es indicar:

• qué es incorrecto actualmente,
• qué resultado debe lograrse,
• qué elementos no debe modificar AI,
• si elError Screenshotadjunto muestra un error de renderizado, diseño visual, problema de responsividad o mensaje de validación.

Prompt de ejemplo para la siguiente corrección:

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.

Este workflow es útil cuando la primera versión está cerca del resultado esperado, pero requiere ajustar detalles como espaciados, responsividad, visibilidad de banners, posición del logo o estilo de los botones.

Puede repetir este ciclo muchas veces. Cada nueva tarea crea una entrada independiente en el historial, por lo que es posible volver a prompts, payloads y respuestas AI anteriores para comprobar qué instrucción produjo un cambio concreto.

8. Significado de los campos del payload AI

El módulo envía a AI un payload estructural. Las secciones más importantes son:

template

Contiene el estado actual de la plantilla Magento:

• ID de la plantilla,
• nombre de la plantilla,
• subject,
• content,
• styles,
• código original de la plantilla.

AI utiliza esta sección como material base para la generación.

Importante: si anteriormente se aplicó el resultado AI medianteApply Result, la seccióntemplateya contiene esa versión actualizada. Gracias a ello, la siguiente generación puede funcionar como una corrección de la plantilla actual.

variables

Contiene variables y directivas Magento detectadas en la plantilla.

AI debe conservar estos valores y no debe inventar variables no compatibles.

prompts

Contiene:

• technical- prompt técnico global de la configuración,
• user- prompt introducido en el editor de la plantilla.

El prompt técnico protege la estructura específica de Magento. El prompt de usuario describe el resultado esperado para una sola plantilla.

design_reference

Contiene metadatos y contenido opcionales del proyecto de referencia enviado.

La sección queda vacía cuando no se ha subido ningún archivo de referencia.

error_screenshot

Contiene un screenshot opcional que muestra errores actuales de renderizado, layout, visuales o de validación.

Esta sección tiene la descripciónpurposeydescriptionpara que AI sepa que el archivo sirve para comprender el problema y no como modelo del diseño objetivo.

La sección queda vacía cuando no se ha subido ninguna captura de pantalla.

En correcciones posteriores, conviene utilizarerror_screenshotjunto con un prompt preciso que indique qué debe corregirse y qué no debe cambiarse. De este modo, AI puede corregir un problema concreto sin reconstruir toda la plantilla.

Ejemplo: después de aplicar el primer resultado AI, el administrador observa que en Gmail un banner se superpone a la sección de resumen del pedido. En la siguiente solicitud adjunta un screenshot de esa vista e introduce un prompt que solicita únicamente corregir los espaciados y el ancho del banner. El payload sigue conteniendo losTemplate ContentyTemplate Stylesactuales, por lo que AI trabaja sobre la última versión guardada.

assets

Contiene recursos gráficos estructurales guardados para la plantilla:

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

Cada recurso contiene una URL pública de medios, label, alt text, target URL, sort order y filename.

AI debe utilizar estas URL al construir el HTML y no debe inventar direcciones de imágenes adicionales.

store_context

Contiene información básica sobre la tienda, como:

• store ID,
• locale,
• base URL.

AI puede utilizarla para entender el idioma y el contexto, pero no debe recibir datos reales de clientes ni de pedidos.

9. Resolución de problemas

La tarea permanece en estado pending

Causa más probable:

• el queue consumer no está en ejecución.

Comprueba:

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

La página de configuración muestra access denied

Compruebe los permisos ACL para:

Kowal_AiEmailThemeGenerator::settings

Después de cambiar los permisos del administrador, cierre sesión y vuelva a iniciarla.

La generación termina con un error de falta de API key

Comprueba:

OpenAI API Key

Asegúrese de que el módulo está activado y de que la configuración se ha guardado en el scope correcto.

El resultado AI tiene estado completed, pero la plantilla no se ha actualizado

Comprueba:

Automatically Apply Result

Si la opción está establecida enNo, abra la tarea y haga clic en:

Apply Result

La siguiente corrección no tiene en cuenta el resultado anterior

Compruebe si el resultado anterior se aplicó mediante:

Apply Result

La siguiente generación se basa en la plantilla Magento guardada actualmente. Si el resultado del job tiene estadocompleted, pero no se ha aplicado, el siguiente job seguirá basándose en una versión anterior de la plantilla.

La respuesta AI ha sido rechazada

El módulo valida el JSON devuelto. Puede rechazar el resultado si:

• faltan campos requeridos,
• los campos requeridos tienen tipos incorrectos,
• el nombre de la plantilla, el subject o el content están vacíos,
• el content contiene la etiquetascript,
• el resultado no es un JSON válido.

Revise el mensaje de error en la tarea y repita la generación con un prompt más claro.

10. Configuración recomendada para producción

Valores iniciales recomendados:

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

Utilice la aplicación manual del resultado hasta que el equipo tenga la seguridad de que los prompts, el modelo seleccionado y las reglas de validación producen plantillas coherentes.