DfPreorder SW: guia completo

O Shopware não oferece nativamente qualquer função «Avise-me quando voltar a haver stock». O DfPreorder SW preenche essa lacuna: em cada página de produto esgotado aparece automaticamente um formulário de inscrição, e o cliente recebe um alerta por email, no seu próprio idioma, assim que o produto regressa. A extensão acrescenta também um modo de pré-encomenda leve (selo e data de expedição prevista) e um módulo de administração para acompanhar as inscrições. Um único ZIP instala-se no Shopware 6.5, 6.6 e 6.7. Este guia cobre a instalação, a compilação dos recursos, o worker e a tarefa agendada, a configuração, a utilização no storefront, o modo de pré-encomenda, os emails, a Store API, a conformidade com o RGPD e a resolução de problemas.

Como funciona a deteção do regresso ao stock

O DfPreorder deteta os reabastecimentos de duas formas complementares, que convergem para um mesmo processamento idempotente, pelo que os seus clientes são sempre avisados, e nunca duas vezes:

• Em tempo real: um subscritor escuta a escrita dos produtos e reage assim que o stock ou o stock disponível muda.
• Varredura agendada: uma tarefa agendada corre a cada 15 minutos e apanha as atualizações de stock feitas em SQL direto, tipicamente a decrementação do stock disponível na colocação de uma encomenda, ou uma importação ERP, que não acionam qualquer evento aplicacional.

O formulário de lista de espera aparece numa página de produto quando se reúnem duas condições: o produto está em modo «esgotado oculta a disponibilidade» (closeout) e o seu stock disponível chegou a zero.

Instalação

1. Transfira o arquivo DfPreorder-v1.0.0.zip a partir da sua conta DataFirefly.
2. Copie a pasta descomprimida DfPreorder para custom/plugins/, ou instale o ZIP em Administração → Extensões → As minhas extensões → Carregar extensão.
3. Instale e ative a extensão:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfPreorder

4. Compile os recursos do storefront e da administração (passo indispensável, não é fornecido qualquer dist):

   ./bin/build-storefront.sh
   ./bin/build-administration.sh

5. Limpe a cache:

   bin/console cache:clear

Na instalação, a extensão cria a tabela df_stock_notification, o conjunto de campos personalizados df_preorder na entidade produto, dois modelos de email e a tarefa agendada. Na desinstalação sem conservação dos dados, tudo é eliminado.

Worker e tarefa agendada

Para que os emails sejam realmente enviados, dois mecanismos têm de estar a correr, o que em produção costuma já acontecer através do admin-worker, do systemd ou do cron:

• O worker Messenger, que consome a mensagem assíncrona de reabastecimento e envia os emails;
• O agendador de tarefas, que aciona a varredura de segurança a cada 15 minutos.

bin/console messenger:consume async --time-limit=60
bin/console scheduled-task:run

Configuração

Abra Extensões → As minhas extensões → DataFirefly Pré-encomenda e Lista de Espera → ⋯ → Configurar. Todas as opções são reguláveis por canal de venda graças ao seletor nativo no topo da página.

• Ativar a lista de espera: interruptor principal. Apresenta o formulário nas páginas esgotadas.
• Duplo opt-in: exige uma confirmação por email antes de ativar a inscrição (recomendado para o RGPD). Desativado por predefinição.
• Autorizar visitantes: se desativado, só os clientes com sessão iniciada se podem inscrever.
• Eliminar a inscrição após a notificação: minimização dos dados; o endereço de email é apagado assim que o alerta é enviado. Se desativado, a inscrição é conservada com o estado «notificado».
• Notificações por lote: número máximo de emails enviados por execução (worker ou varredura). 100 por predefinição.
• Mostrar o selo de pré-encomenda: ativa a apresentação do selo e da data de expedição nos produtos configurados em pré-encomenda.

A lista de espera no storefront

Quando um produto está esgotado (closeout e stock disponível a zero), o formulário «Ser avisado do regresso ao stock» aparece automaticamente sob o botão de compra. O cliente introduz o seu email (pré-preenchido se tiver sessão iniciada) e valida.

• A submissão é feita em AJAX com uma alternativa completa sem JavaScript (mensagem flash e reencaminhamento).
• Um campo honeypot invisível filtra os robots.
• Se o duplo opt-in estiver ativo, é enviado um email de confirmação; a inscrição só fica ativa depois do clique na ligação de confirmação.
• Cada email pode conter uma ligação de cancelamento da subscrição num clique.

Modo de pré-encomenda

A extensão cria um grupo de campos personalizados Pré-encomenda na entidade produto. Abra um produto em Catálogos → Produtos, separador Especificações → Campos personalizados, grupo Pré-encomenda:

• Ativar a pré-encomenda: interruptor de ativação para este produto.
• Data de expedição prevista: a data apresentada no selo.
• Nota de pré-encomenda: texto livre apresentado sob o selo.

Quando a pré-encomenda está ativa e o selo está autorizado na configuração, aparece um selo âmbar acima do botão de compra com a data de expedição prevista. A renderização está isolada no template do buy-widget e mantém-se sobreponível.

Emails e traduções

São criados dois modelos de email na instalação, traduzidos em cinco idiomas: francês, inglês, alemão, espanhol e italiano:

• Regresso ao stock (df_preorder.back_in_stock): variáveis productName, productUrl e o objeto product completo.
• Confirmação de inscrição (df_preorder.double_opt_in): acrescenta a variável confirmUrl.

Cada cliente é notificado no idioma da loja no momento da sua inscrição: a extensão reconstrói um contexto de idioma próprio do subscritor para resolver o nome traduzido do produto e o modelo certo. O URL do produto é resolvido através do URL SEO canónico do canal e do idioma em causa.

Os modelos mantêm-se inteiramente editáveis em Definições → Emails → Modelos de email. Pesquise «regresso ao stock» ou «back in stock» para os encontrar.

Módulo de administração

O menu Marketing → Lista de Espera e Pré-encomenda lista todas as inscrições: endereço de email, produto, estado (pendente / confirmado / notificado), data de inscrição e data de notificação. A eliminação em massa está disponível, útil para limpar manualmente inscrições antigas.

Store API (headless / móvel)

Para as lojas headless ou as aplicações móveis, um ponto de entrada Store API permite inscrever um cliente na lista de espera:

POST /store-api/df-waitlist/subscribe
Content-Type: application/json
sw-access-key: <a-sua-chave-de-acesso>

{
  "productId": "0189a1b2c3d4...",
  "email": "cliente@example.com"
}

Um pedido válido devolve uma resposta de sucesso; um identificador de produto ou um email inválido devolve um erro 400. Aplicam-se as mesmas regras de configuração (duplo opt-in, autorização de visitantes, e as restantes).

Conformidade com o RGPD

• Os endereços de email são recolhidos apenas para a notificação pedida.
• O duplo opt-in opcional regista um consentimento explícito.
• O comportamento predefinido elimina o dado pessoal assim que o alerta é enviado.
• Pode ser inserida nos modelos de email uma ligação de cancelamento da subscrição num clique.
• A desinstalação com eliminação dos dados apaga a tabela, os modelos, os campos personalizados e a configuração.

Compatibilidade 6.5 a 6.7 e resolução de problemas

O formulário não aparece num produto esgotado. Verifique que a opção «Ativar a lista de espera» está marcada para o canal de venda certo, que o produto está mesmo em modo closeout, e que o seu stock disponível está a zero. Limpe a cache depois de qualquer alteração de configuração.

As inscrições são registadas mas nenhum email é enviado. O worker Messenger e/ou o agendador de tarefas não estão a correr. Execute-os manualmente para testar (ver a secção Worker), e depois garanta que correm em contínuo em produção.

Erro do serviço de email na ativação no Shopware 6.7. A classe abstrata do serviço de email foi substituída por uma classe concreta na 6.7. A extensão trata automaticamente dessa diferença através de um compiler pass que cria o alias adequado; um simples cache:clear recompila o contentor se o erro persistir depois de uma atualização.

O email sai no idioma errado. O idioma usado é o do canal de venda no momento da inscrição. Verifique que o canal em causa tem mesmo o idioma esperado e que o modelo de email tem uma tradução para esse idioma.

Parece haver emails enviados em duplicado. Não deveria acontecer: o processamento é idempotente e marca (ou elimina) cada inscrição depois do envio. Se o observar, verifique que não está a executar vários workers em concorrência sem a configuração de transporte adequada.

O que acontece na desinstalação? Com a opção de eliminação dos dados, a tabela df_stock_notification, os dois modelos de email, o conjunto de campos df_preorder, a tarefa agendada e a configuração são eliminados. Sem essa opção, tudo é conservado para uma reinstalação posterior.