Instruções de instalação e configuração

1. Requisitos

O módulo destina-se a Magento 2 e a instalações geridas pelo Composer.

Necessário:

• projeto Magento 2 gerido pelo Composer,
• versão PHP compatível com a instalação Magento utilizada,
• acesso ao Magento CLI,
• OpenAI API key,
• processo Magento Message Queue consumer em funcionamento.

Pacote do módulo:

kowal/module-ai-email-theme-generator

Nome do módulo Magento:

Kowal_AiEmailThemeGenerator

2. Instalação

Adicione o repositório Composer:

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

Se o repositório for privado, configure a autenticação GitHub:

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

Instale o módulo:

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

Ative o módulo:

bin/magento module:enable Kowal_AiEmailThemeGenerator

Execute a atualização do Magento:

bin/magento setup:upgrade

Limpe a cache:

bin/magento cache:flush

Para o modo de produção, execute os comandos de deployment padrão utilizados no projeto, por exemplo:

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

3. Queue Consumer

A geração com IA é processada de forma assíncrona pela Magento Message Queue.

Execute o consumer manualmente:

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

Em ambientes de produção, configure o consumer com supervisor, systemd ou outro gestor de processos utilizado pelo alojamento.

O módulo cria tarefas no painel de administração, mas o pedido para a IA não será processado enquanto o consumer não estiver em execução.

4. Permissões de administrador

O módulo adiciona recursos ACL:

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

Para que o administrador possa utilizar o módulo, atribua os recursos adequados em:

System > Permissions > User Roles

Para acesso total, permita o recurso principal AI Email Generation e todos os recursos subordinados.

5. Localização da configuração

Aceda a:

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

A secção de configuração contém o grupo:

General Settings

6. Campos de configuração

Enabled

Tipo: Yes/No

Predefinição: No

Ativa ou desativa as funcionalidades do módulo.

Quando definido como No:

• o módulo não deve criar tarefas de geração com IA,
• a ação de geração é bloqueada,
• o administrador deve primeiro configurar o módulo.

Defina Yes apenas depois de preparar a API key e iniciar o queue consumer.

API Provider

Tipo: Select

Predefinição: OpenAI

Define o fornecedor de IA utilizado pelo módulo.

A implementação atual suporta:

OpenAI

O campo existe para permitir adicionar outros providers no futuro sem alterar o workflow do administrador.

OpenAI API Key

Tipo: campo ocultado/encriptado

Armazena a OpenAI API key utilizada para a geração.

O valor é encriptado pelo Magento com:

MagentoConfigModelConfigBackendEncrypted

Importante:

• não coloque a API key diretamente no código,
• não faça commit de chaves de ambiente,
• restrinja o acesso a este campo através de ACL,
• utilize uma chave com permissões adequadas ao projeto.

OpenAI Model

Tipo: Select

Define o modelo OpenAI utilizado para a geração.

Exemplo:

gpt-4.1

A lista é obtida dinamicamente a partir da OpenAI Models API utilizando a API key configurada. O módulo filtra a resposta para identificadores de modelos GPT e coloca a lista em cache durante um curto período, para não chamar a API sempre que a configuração é aberta.

Se a API key ainda não tiver sido guardada, o campo mostrará uma opção de contingência e pedirá ao administrador para guardar a chave.

Se a OpenAI API estiver temporariamente indisponível, o campo mantém o modelo atualmente configurado, sempre que possível.

Utilize um modelo que suporte o tipo de dados de entrada necessário:

• geração de texto para prompts e conteúdo do modelo,
• modelo com suporte para imagens, se forem utilizados designs gráficos de referência.

O modelo escolhido influencia a qualidade do resultado, o tempo de resposta e o custo.

Request Timeout

Tipo: Number

Exemplo de valor predefinido:

120

Tempo máximo em segundos permitido para o pedido à OpenAI API.

Valores recomendados:

• 60 para geração curta de texto,
• 120 ou mais para geração HTML/CSS complexa,
• valores superiores apenas quando a infraestrutura permitir tarefas em fila mais longas.

O timeout aplica-se ao processamento em segundo plano, não ao pedido do formulário de administração.

Maximum Retries

Tipo: Number

Exemplo de valor predefinido:

2

Define quantas vezes o consumer pode repetir automaticamente uma tarefa de geração falhada.

As repetições são úteis em erros temporários, tais como:

• timeout da API,
• erro temporário do provider,
• rate limit,
• problema de rede.

Erros permanentes, por exemplo configuração incorreta ou resposta inválida da IA, devem ser verificados nos detalhes da tarefa.

Technical Prompt

Tipo: Textarea

Este prompt é aplicado a cada pedido de geração. Deve conter regras técnicas que têm sempre de ser preservadas.

Exemplo:

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.

Utilize este campo para instruções estáveis, como:

• preservar diretivas do Magento,
• manter variáveis obrigatórias,
• evitar JavaScript,
• devolver apenas JSON,
• escrever HTML compatível com clientes de email,
• utilizar CSS no campo correto do resultado.

Não utilize este campo para instruções criativas pontuais. Para isso existe o AI Prompt no formulário do modelo.

Default User Prompt

Tipo: Textarea

Este prompt é apresentado por predefinição na secção de IA do editor de modelos de email.

Exemplo:

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

O administrador pode alterá-lo antes de criar a tarefa de geração.

Utilize este campo para definir uma instrução predefinida prática para tarefas típicas de geração.

Allowed Design File Types

Tipo: Text

Exemplo de valor predefinido:

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

Lista de extensões de ficheiros permitidas para o design de referência opcional, separadas por vírgulas.

Exemplos suportados:

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

Em produção, utilize uma lista tão restritiva quanto possível. Não permita tipos de ficheiro que não sejam necessários no processo.

Maximum Design File Size

Tipo: Number

Exemplo de valor predefinido:

5242880

Tamanho máximo do ficheiro de referência em bytes.

Exemplos:

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

Ficheiros grandes aumentam o tamanho do payload e podem tornar a geração mais lenta ou exceder os limites do provider.

Automatically Apply Result

Tipo: Yes/No

Predefinição: No

Define se um resultado válido da IA deve substituir imediatamente os campos nativos do modelo Magento.

Quando definido como Yes, o consumer guarda o resultado gerado em:

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

Quando definido como No, o resultado é armazenado na tarefa e o administrador pode verificá-lo antes de o aplicar manualmente.

Configuração recomendada para produção:

No

A aprovação manual é mais segura, porque o resultado da IA pode estar tecnicamente correto, mas ainda assim exigir revisão de marca, legal ou de layout.

Keep Request and Response Payloads

Tipo: Yes/No

Predefinição: Yes

Define se o módulo guarda os payloads completos do pedido e da resposta no registo da tarefa.

Quando a opção está ativa, os detalhes da tarefa podem mostrar:

• snapshot do modelo enviado para a IA,
• variáveis disponíveis,
• prompts,
• metadados do design de referência,
• resposta da IA.

Isto é útil para debugging e auditoria.

Em ambientes de produção, verifique os requisitos de privacidade antes de ativar esta opção. O módulo não deve enviar dados reais de clientes para a IA, mas os payloads podem ainda conter conteúdo de modelos sensível para o negócio.

Retention Days

Tipo: Number

Exemplo de valor predefinido:

30

Define durante quanto tempo as tarefas antigas devem ser mantidas.

Este valor documenta a política de retenção pretendida. O projeto pode utilizá-lo para implementar limpeza periódica de acordo com os requisitos operacionais.

7. Exemplo: gerar o modelo New Order Confirmation for Guest

Este exemplo descreve o processo completo de geração de um modelo de email Magento melhorado para:

New Order Confirmation for Guest

Passo 1: Configure o módulo

Aceda a:

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

Defina:

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

Guarde a configuração e limpe a cache se o Magento o solicitar.

Passo 2: Inicie o queue consumer

Execute:

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

Durante os testes, o processo deve estar sempre em execução.

Passo 3: Crie um modelo Magento nativo

Aceda a:

Marketing > Communications > Email Templates

Clique em:

Add New Template

No campo Template, selecione:

New Order Confirmation for Guest

Clique em:

Load Template

O Magento irá preencher os campos nativos:

• Template Subject
• Template Content
• Template Styles

Defina o nome do modelo, por exemplo:

New Order Confirmation for Guest - AI Draft

Guarde o modelo.

O processo de geração com IA requer um modelo guardado, porque a tarefa tem de ter um template_id persistente.

Passo 4: Preencha o AI Prompt

Depois de guardar, abra novamente o modelo, se necessário. O editor padrão de modelos de email do Magento contém a secção AI Email Generation.

No campo AI Prompt, introduza a instrução de negócio, por exemplo:

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 deste campo:

• descreve o efeito de negócio esperado,
• aplica-se apenas à tarefa de geração concreta,
• pode incluir instruções sobre marca, tom de comunicação, layout ou conteúdo,
• não deve conter dados de API nem dados reais de clientes.

Passo 5: Opcionalmente, adicione Design Reference

Utilize Design Reference se o email gerado deve seguir uma direção visual específica.

Ficheiros de exemplo:

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

Significado deste campo:

• dá à IA contexto visual ou estrutural adicional,
• ajuda a adaptar o modelo ao design gráfico,
• é opcional,
• deve cumprir os limites de extensões e tamanho de ficheiro.

Se nenhum design de referência for adicionado, a IA utilizará apenas o conteúdo do modelo, as variáveis, o prompt técnico e o prompt do utilizador.

Passo 6: Opcionalmente, adicione Error Screenshot

Utilize Error Screenshot se quiser mostrar à IA o problema atual de renderização, layout ou validação do modelo.

Exemplos:

• captura de ecrã de um cabeçalho mal alinhado,
• screenshot de um problema com banner,
• pré-visualização do email com espaçamento incorreto,
• captura de um cliente de email a mostrar um problema de responsividade,
• screenshot de uma mensagem de erro de uma ferramenta de teste.

Este campo é enviado para a IA como uma secção JSON separada:

{ '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 deste campo:

• mostra à IA o erro atual a corrigir,
• não é um design gráfico nem um modelo do aspeto final pretendido,
• ajuda a IA a compreender o que atualmente não funciona,
• deve ser utilizado juntamente com uma descrição clara do problema no AI Prompt.

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

Passo 7: Adicione AI Assets estruturados

O editor inclui a área AI Assets. Estes recursos são guardados com o modelo Magento e enviados para a IA como URLs frontend de media agrupados.

Grupos de recursos disponíveis:

Cada recurso pode conter:

Para banners e ícones, clique em:

Add BannerAdd Icon

O módulo guarda os recursos enviados no Magento media storage e envia para a IA URLs frontend públicos na estrutura:

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

Nos prompts, faça referência direta a estes grupos. Exemplo:

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.

Passo 8: Selecione a geração após guardar

Ative:

Generate with AI after saving

Significado deste campo:

• o Magento guarda primeiro o modelo através da ação nativa padrão save,
• após a gravação correta, o módulo cria uma tarefa de geração com IA,
• o design de referência enviado é anexado à tarefa,
• a tarefa é processada de forma assíncrona pelo queue consumer.

Se a checkbox não estiver selecionada, a gravação do modelo funciona exatamente como a gravação padrão do Magento e nenhuma tarefa de IA será criada.

Passo 9: Guarde o modelo

Clique no botão padrão do Magento:

Save Template

Depois de guardar o modelo, o módulo cria uma tarefa de geração.

Neste momento:

• a gravação nativa do modelo está concluída,
• o estado da tarefa começa em pending,
• o queue consumer processa a tarefa em segundo plano.

Passo 10: Verifique a tarefa

Aceda a:

Marketing > Communications > AI Email Generation Jobs

Abra a tarefa criada.

Campos mais importantes:

Estados típicos:

Passo 11: Aplique o resultado

Se Automatically Apply Result = No, o resultado não é guardado automaticamente no modelo Magento.

Verifique:

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

Se o resultado estiver correto, clique em:

Apply Result

O módulo guardará os valores gerados nos campos nativos do modelo Magento.

Passo 12: Verifique o modelo de email nativo

Volte a:

Marketing > Communications > Email Templates

Abra o modelo e verifique:

• Template Name foi atualizado,
• Template Subject foi atualizado,
• Template Content contém o HTML esperado e diretivas Magento,
• Template Styles contém o CSS esperado,
• as variáveis Magento obrigatórias não foram removidas.

Envie uma mensagem de teste ou execute um fluxo de pedido de teste de acordo com o processo QA padrão do projeto.

Passo 13: Envie outra correção para a IA

Depois de aplicar o resultado com Apply Result, a versão atual do modelo fica guardada nos campos nativos do Magento. Isto significa que o pedido de IA seguinte será baseado nessa versão, e não no modelo original.

Pode aperfeiçoar o mesmo modelo várias vezes:

1. Aplique o resultado da IA através de Apply Result.
2. Abra novamente o modelo em Marketing > Communications > Email Templates.
3. Introduza um novo prompt que descreva a correção concreta.
4. Se o problema for visual, adicione Error Screenshot.
5. Selecione Generate with AI after saving.
6. Guarde o modelo.
7. Verifique a nova tarefa e aplique o resultado se estiver correto.

Nas correções seguintes, trate o AI Prompt como uma descrição da alteração à versão atual. O ideal é indicar:

• o que está atualmente incorreto,
• qual o efeito pretendido,
• quais elementos a IA não deve alterar,
• se o Error Screenshot anexado mostra um erro de renderização, layout visual, problema de responsividade ou mensagem de validação.

Exemplo de prompt para uma correção seguinte:

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 é útil quando a primeira versão está próxima do efeito esperado, mas requer aperfeiçoamento de detalhes, como espaçamentos, responsividade, visibilidade de banners, posição do logótipo ou estilo dos botões.

Pode repetir este ciclo muitas vezes. Cada nova tarefa cria uma entrada separada no histórico, por isso é possível regressar a prompts, payloads e respostas da IA anteriores para verificar qual instrução levou a uma alteração concreta.

8. Significado dos campos do payload da IA

O módulo envia para a IA um payload estruturado. As secções mais importantes são:

template

Contém o estado atual do modelo Magento:

• ID do modelo,
• nome do modelo,
• subject,
• content,
• styles,
• código original do modelo.

A IA utiliza esta secção como material base para a geração.

Importante: se o resultado da IA tiver sido previamente aplicado através de Apply Result, a secção template já contém essa versão atualizada. Assim, a geração seguinte pode funcionar como uma correção ao modelo atual.

variables

Contém variáveis e diretivas Magento detetadas no modelo.

A IA deve preservar estes valores e não deve inventar variáveis não suportadas.

prompts

Contém:

• technical - prompt técnico global da configuração,
• user - prompt introduzido no editor do modelo.

O prompt técnico protege a estrutura específica do Magento. O prompt do utilizador descreve o resultado esperado para um único modelo.

design_reference

Contém metadados opcionais e o conteúdo do design de referência enviado.

A secção fica vazia quando não é enviado qualquer ficheiro de referência.

error_screenshot

Contém um screenshot opcional que mostra erros atuais de renderização, layout, visuais ou de validação.

Esta secção tem a descrição purpose e description para que a IA saiba que o ficheiro serve para compreender o problema, e não como modelo do design final.

A secção fica vazia quando não é enviada uma captura de ecrã.

Em correções seguintes, vale a pena utilizar error_screenshot juntamente com um prompt preciso que indique o que deve ser corrigido e o que não deve ser alterado. Assim, a IA pode resolver um problema específico sem reconstruir todo o modelo.

Exemplo: depois de aplicar o primeiro resultado da IA, o administrador repara que, no Gmail, o banner sobrepõe a secção de resumo do pedido. No pedido seguinte, anexa um screenshot dessa vista e introduz um prompt pedindo apenas a correção dos espaçamentos e da largura do banner. O payload continua a conter o Template Content e o Template Styles atuais, por isso a IA trabalha sobre a última versão guardada.

assets

Contém recursos gráficos estruturados guardados para o modelo:

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

Cada recurso contém URL público de media, label, alt text, target URL, sort order e filename.

A IA deve utilizar estes URLs ao construir o HTML e não deve inventar endereços adicionais de imagens.

store_context

Contém informações básicas sobre a loja, tais como:

• store ID,
• locale,
• base URL.

A IA pode utilizá-las para compreender o idioma e o contexto, mas não deve receber dados reais de clientes ou pedidos.

9. Resolução de problemas

A tarefa permanece no estado pending

Causa mais provável:

• o queue consumer não está em execução.

Verifique:

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

A página de configuração mostra access denied

Verifique as permissões ACL para:

Kowal_AiEmailThemeGenerator::settings

Depois de alterar as permissões do administrador, termine a sessão e volte a iniciar sessão.

A geração termina com erro de falta de API key

Verifique:

OpenAI API Key

Certifique-se de que o módulo está ativo e que a configuração foi guardada no scope correto.

O resultado da IA tem estado completed, mas o modelo não foi atualizado

Verifique:

Automatically Apply Result

Se a opção estiver definida como No, abra a tarefa e clique em:

Apply Result

A correção seguinte não considera o resultado anterior

Verifique se o resultado anterior foi aplicado através de:

Apply Result

A geração seguinte baseia-se no modelo Magento atualmente guardado. Se o resultado do job tiver estado completed, mas não tiver sido aplicado, o job seguinte continuará a basear-se na versão mais antiga do modelo.

A resposta da IA foi rejeitada

O módulo valida o JSON devolvido. Pode rejeitar o resultado se:

• faltarem campos obrigatórios,
• campos obrigatórios tiverem tipos incorretos,
• o nome do modelo, subject ou content estiverem vazios,
• content contiver a tag script,
• o resultado não for JSON válido.

Verifique a mensagem de erro na tarefa e repita a geração com um prompt mais claro.

10. Configurações de produção recomendadas

Valores iniciais recomendados:

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

Utilize a aplicação manual do resultado até que a equipa tenha confiança de que os prompts, o modelo escolhido e as regras de validação produzem modelos consistentes.