Incidentes de qualidade no Drupal Commerce: da reclamação da cliente ao artigo reparado a caminho de casa

Uma cliente escreve: a sola do sapato esquerdo descolou, três semanas depois da entrega. Alguém responde ao email, outra pessoa regista-o numa folha de cálculo, a reparação combina-se por telefone com a oficina e, quando o par fica pronto, é preciso criar um envio para uma encomenda que saiu há um mês. Seis meses depois, ninguém sabe dizer se falha mais a colagem ou a costura, nem em que modelo.

O Commerce Quality Incident transforma essa reclamação num registo dentro da própria loja, ligado à encomenda, à linha e ao SKU que falhou, com número, workflow e histórico próprios. É software livre, sob GPL-2.0-or-later, publicado no drupal.org, e assenta no que um site Commerce já tem: encomendas, State Machine, Commerce Log e Commerce Number Pattern. A versão 1.1.0 acrescenta o último passo: o envio que leva o artigo reparado ou substituído de volta à cliente.

O que podes construir com ele

• Um registo por reclamação, numerado como as encomendas (QI-2026-00001), acessível a partir da página de administração da própria encomenda, onde aparecem todos os incidentes dessa encomenda.
• Um registo de defeitos que dá para contar. A categoria e a subcategoria escolhem-se de uma lista fixa no formulário, por isso "Manufacturing defect: Gluing" é sempre a mesma coisa, a par de uma severidade de low a critical.
• Categorias à medida do que vendes. O plugin por omissão serve para qualquer produto, um plugin Footwear & Bags vem incluído como exemplo, e o teu exige uma única classe PHP.
• Um incidente que não se fecha sem dizer como foi resolvido.
• A ordem de reparação ou substituição, criada a partir do incidente com o Commerce Make-to-Order, com a prioridade tirada da severidade do incidente.
• O envio de volta, criado a partir do incidente com o Commerce Shipping, novo na 1.1.0.
• Defeitos detetados na produção ou na receção de mercadoria, registados sem encomenda nenhuma.

O envio que o Commerce não deixava criar

O envio de volta precisou de um submódulo próprio por causa da forma como o Commerce Shipping evita que uma linha seja enviada duas vezes. O formulário de envio só oferece linhas de encomenda que nenhum outro envio leva. Um par reparado volta por uma linha que já saiu no primeiro envio da encomenda, por isso um envio acrescentado ali para a devolução fica sem item. As transportadoras que declaram o conteúdo recusam-no: a UPS, para uma encomenda que sai da União Europeia, responde 128039 Invalid number of products.

O submódulo QI-Shipping constrói o envio a partir do incidente. Leva uma unidade da linha do incidente, segue para uma cópia da morada de envio da encomenda, propõe o método de envio que a encomenda usou da última vez e aponta de volta para o incidente num campo source_incident, que o Views consegue listar nos envios de uma encomenda. A página do incidente passa a mostrar o envio com o estado, os itens e o código de tracking, junto com as operações que outros módulos lhe acrescentem, como a transmissão à transportadora. Um site que precise de preencher campos seus no envio, um código de motivo por exemplo, subscreve um evento e define-os antes de o envio ser gravado.

O que ele se recusa a fazer

Cada um destes limites existe porque o registo tem de ser fiável meses depois, quando alguém for contar.

O item e a morada do envio de volta aparecem no diálogo, mas não se escolhem. O envio vai para onde foi a encomenda, com a linha de que trata o incidente. Mandá-lo para outro lado é editar o envio, de propósito, por alguém que vê o que está a mudar.

Há um único envio de volta ativo por incidente. O botão desaparece enquanto ele existir e só volta quando for cancelado, e os envios cancelados continuam listados no incidente. Um segundo envio criado por um duplo clique, ou por duas pessoas na mesma manhã, é uma encomenda que a transportadora recolhe e que a cliente nunca esperou.

Fechar um incidente pede notas de resolução. Um incidente fechado sem nada escrito é a folha de cálculo outra vez.

De onde veio

Construímo-lo para um dos nossos clientes, uma marca de calçado cujos sapatos são feitos à mão depois de encomendados, e o plugin de categorias Footwear & Bags é a lista dessa loja do que pode correr mal num sapato. Já estava em produção antes da primeira versão pública, em julho, que trouxe o plugin de categorias genérico, os testes próprios e a limpeza para o drupal.org. O envio de volta nasceu na mesma loja, que criou a primeira devolução pelo novo submódulo no próprio dia em que a 1.1.0 saiu.

O lado make-to-order do mesmo fluxo tem um post próprio: com os dois módulos, uma reclamação passa a ordem de reparação na oficina e depois a envio, e cada registo aponta para os outros.

Instalar

composer require drupal/commerce_quality_incident
drush en commerce_quality_incident

Requer Drupal 10.3 ou 11, PHP 8.1, Commerce 2.x ou 3.x e State Machine. Os dois submódulos são opcionais e ativam-se da mesma forma: o commerce_quality_incident_mto precisa do Commerce Make-to-Order, o commerce_quality_incident_shipping precisa do Commerce Shipping. As versões estáveis estão cobertas pela security advisory policy do Drupal.

A página do projeto tem a documentação completa. Se a tua loja trata reclamações, garantias ou reparações de uma forma a que o módulo ainda não se adapta, conta-nos na issue queue.