Especificação de módulo Magento: um modelo que o dev não consegue interpretar errado

Por que módulo Magento pede especificação própria

Uma funcionalidade que parece simples no Magento encosta em várias partes da plataforma ao mesmo tempo: configuração com escopo, permissão de usuário do admin, API, e-mail transacional, várias store views, importação por planilha. Quando a especificação não fala de uma delas, o dev decide sozinho. Em geral decide pelo caminho mais curto, e cada decisão dessas volta depois como pedido de alteração.

A especificação não substitui a conversa com o dev. Ela registra o que foi combinado, para que o orçamento e o aceite da entrega sejam feitos contra o mesmo documento.

Modelo de especificação para desenvolvimento Magento

Copie as seções abaixo. Quando uma delas não se aplica, escreva “não se aplica”: isso também é informação, e evita que alguém inclua a parte por conta própria.

1. Objetivo. Uma frase com o problema do negócio, não com a solução técnica.
2. Regras de negócio. Numeradas, cada uma com um exemplo de valores.
3. Escopo de configuração. Para cada opção nova: o nome, onde aparece em Stores > Settings > Configuration e se o valor muda por website ou por store view. Os limites de cada nível estão explicados no artigo sobre escopo global, website e store view.
4. Permissões no admin. Quais papéis de usuário vão operar a funcionalidade. O módulo precisa criar recurso de ACL próprio, que aparece em System > Permissions > User Roles, na aba Role Resources.
5. Telas. No admin (grid, formulário, campos obrigatórios) e na loja (produto, carrinho, checkout), com um rascunho ou print marcado.
6. API e GraphQL. Se algum sistema externo, aplicativo ou vitrine separada precisa ler ou gravar esses dados.
7. E-mails transacionais. Qual evento dispara, quem recebe e se o texto precisa ser editável em Marketing > Communications > Email Templates.
8. Várias lojas e idiomas. O que muda em cada store view, incluindo textos que precisam de tradução.
9. Importação e exportação. Se os dados entram por planilha, em System > Data Transfer > Import, ou por integração.
10. Critérios de aceite. Cenários no formato Dado/Quando/Então.
11. Fora do escopo. Lista explícita do que não será feito.
12. Ambiente e entrega. Versão do Magento e do PHP (os mesmos dados da loja que o dev pede para orçar), onde a entrega será homologada e em que repositório o código fica.

Exemplo preenchido: brinde por faixa de valor do carrinho

Exemplo fictício, montado para este modelo; não é projeto de cliente.

Antes de especificar, confira se o nativo resolve. Pela documentação da Adobe, a ação Buy X get Y free da regra de carrinho só dá desconto quando a quantidade X+Y do mesmo produto já está no carrinho: ela não coloca um brinde lá. A ação Free Gift, que adiciona o produto, é exclusiva do Adobe Commerce, e a mesma página diz que ela não tem suporte em vitrine Luma. Numa loja Open Source com Luma, portanto, o brinde automático é desenvolvimento.

Os critérios de aceite do mesmo exemplo, no formato que dá para testar no staging sem ler código:

Cenário: carrinho atinge a faixa
  Dado que a faixa do website Varejo é 300,00 e o brinde é o SKU BRINDE-01
  Quando o subtotal do carrinho chega a 300,00
  Então o SKU BRINDE-01 entra no carrinho com quantidade 1 e preço zero

Cenário: carrinho cai abaixo da faixa
  Dado um carrinho com o brinde e subtotal de 300,00
  Quando o cliente remove um item e o subtotal fica em 250,00
  Então o brinde sai do carrinho e o aviso da faixa volta a aparecer

Cenário: brinde sem estoque
  Dado que o SKU BRINDE-01 está sem estoque
  Quando o subtotal chega a 300,00
  Então nenhum brinde é adicionado
  E o pedido pode ser finalizado normalmente

O que deixar escrito como fora do escopo e quanto detalhe basta

A lista de fora do escopo protege os dois lados. O dev sabe o que não precisa fazer, e você sabe, antes de começar, o que vai ser um pedido novo. No exemplo, “brinde por grupo de cliente” fora da lista é exatamente o tipo de coisa que alguém do marketing pede na semana da entrega.

Para medir o detalhe, uso uma regra: toda regra de negócio precisa virar pelo menos um cenário Dado/Quando/Então. Se você não consegue escrever o cenário, a regra ainda não está clara para você, e o dev vai completar a lacuna com uma suposição. Por outro lado, a especificação não deve dizer como programar: nome de classe, tabela ou plugin é decisão do dev, e ele responde pelo resultado nos critérios de aceite.

Mudou de ideia no meio? Registre a mudança como item novo, com a regra alterada, o cenário novo e uma nova estimativa. Mudança combinada só por mensagem some na hora da homologação. Quer uma revisão da especificação antes de mandar para orçamento? Fale comigo.