Tutorial da extensão de classificações

Navegue até Cursor > Settings > Cursor Settings > Tools & MCP e verifique se o conjunto de ferramentas commerce-extensibility está habilitado sem erros. Se você vir erros, desligue e ligue o conjunto de ferramentas.

{width="600" modal="regular"}

Desative qualquer documentação no contexto do cursor:

• Navegue até Cursor > Settings > Cursor Settings > Indexing & Docs e exclua qualquer documentação listada.

{width="600" modal="regular"}

Gerar código para uma extensão de classificações de produto:

• Na janela Cursor chat, selecione o modo Agent.
• Digite o seguinte prompt:

Implement an Adobe Commerce as a Cloud Service extension to handle Product Ratings.

Implement a REST API to handle GET ratings requests.

GET requests will have to support the following query parameters:

sku -> product SKU

Responda às perguntas do agente com precisão para ajudá-lo a gerar o melhor código.

{width="600" modal="regular"} {width="600" modal="regular"}

Use o seguinte texto de exemplo para responder às perguntas do agente para configurar dados de classificações aleatórias:

Yes, this headless extension is for Adobe Commerce as a Cloud Service storefront,
but we do not need any authentication for the GET API because guest users should be able to use it on the storefront.

This extension is called directly from the storefront, no async invocation, such as events or webhooks, is required.

Start with just the GET API for now, we will implement other CRUD operations at a later time.

We do not need a DB or storage mechanism right now, just return random ratings data between 1 and 5 and a ratings count between 1 and 1000.

The API should only return the average rating for the product and the total number of ratings.
We do not need to add tests right now.

O agente cria um arquivo requirements.md que serve como a fonte da verdade para a implementação.

{width="600" modal="regular"}

Revise o arquivo requirements.md e verifique o plano.

Se tudo estiver correto, instrua o agente a migrar para a Fase 2 - Planejamento de Arquitetura.

Revise o plano de arquitetura.

Instrua o agente a prosseguir com a geração de código.

O agente gera o código necessário e fornece um resumo detalhado com as próximas etapas.

{width="600" modal="regular"} {width="600" modal="regular"} {width="600" modal="regular"}

Peça ao agente para ajudá-lo a testar o código localmente.

Test the ratings API locally on a dev server using cURL.

Siga as instruções do agente e confirme se a API está funcionando localmente.

{width="600" modal="regular"} {width="600" modal="regular"}

Depois de verificar o código gerado, implante a extensão usando o seguinte prompt:

Deploy the ratings API.

O agente realiza uma avaliação de prontidão antes da implantação.

{width="600" modal="regular"}

Quando estiver confiante nos resultados da avaliação, instrua o agente a prosseguir com a implantação.

O agente usa o kit de ferramentas MCP para verificar, compilar e implantar automaticamente.

{width="600" modal="regular"}

Navegue até a pasta storefront:

cd storefront

Abra a pasta de vitrine em uma nova janela Cursor.

Como alternativa, se você tiver a CLI do Cursor instalada, abra a janela usando o seguinte comando no terminal:

cursor .

Iniciar o servidor de desenvolvimento local:

npm run start

Em um navegador, navegue até uma página de produto:

http://localhost:3000/products/llama-plush-shortie/adb336

Observe a página de detalhes do produto (PDP) da vitrine padronizada e observe a falta de classificações visuais do produto.

Use o seguinte prompt com seu agente:

Integrate the ratings API into the PDP to show star ratings and a review count for products. Here's the service contract: @RATINGS_API_CONTRACT.md

O agente avalia a complexidade da tarefa e invoca um fluxo de trabalho em fases. Durante a Fase 1 (Coleta de Requisitos), o agente cria um documento de requisitos e faz perguntas esclarecedoras como:

• Onde as classificações devem aparecer no PDP?
• Deve ser um novo bloco autônomo ou uma personalização de slot dentro do componente PDP existente suspenso?
• Qual deve ser o fallback se a API não estiver disponível ou não retornar dados?
• As classificações também devem aparecer na PLP (lista de produtos) ou somente no PDP?
• Existem especificações ou modelos de design?

Responda a essas perguntas com base nos requisitos do projeto. O agente atualiza o documento de requisitos e marca a fase como concluída.

Durante a Fase 2 (Planejamento de Arquitetura), o agente pesquisa a documentação e a base de código antes de propor uma arquitetura. Espere que o agente:

• Pesquise na documentação do Commerce os contêineres de entrada suspensa de PDP, slots e cargas de evento.
• Procure código existente relacionado a PDP no diretório blocks e na pasta scripts/initializers/.
• Explore definições de TypeScript para contêineres disponíveis e formas de contexto de slot.

O agente apresenta opções de arquitetura como:

• Opção A: Personalize um slot PDP existente para inserir classificações próximas ao título do produto — um toque mais leve e fácil de atualizar.
• Opção B: Crie um novo bloco product-ratings autônomo que obtenha da API independentemente — mais flexível e dissociado.
• Opção C: Crie um novo bloco que também escute eventos de entrega PDP para o SKU do produto — uma abordagem híbrida.

O plano também inclui detalhes sobre a integração da API, considerações de desempenho (carregamento lento, armazenamento em cache), segurança (limpeza de entrada) e uma abordagem de teste.

Revise o plano de arquitetura e instrua o agente a continuar.

Durante a Fase 3 (Abordagem de implementação), o agente solicita que você escolha entre:

• Opção A: Examine um plano de implementação detalhado antes da geração de código (veja primeiro todos os arquivos, padrões e estrutura de código).
• Opção B: Prossiga diretamente para a geração de código.

Selecione a abordagem de sua preferência.

Durante a Fase 4 (Implementação), o agente gera código com base na arquitetura escolhida. Dependendo da abordagem, o agente usa várias habilidades especializadas:

• Modelagem de conteúdo: Se um novo bloco for necessário, o agente criará uma estrutura de conteúdo amigável para o autor, como uma tabela de configuração com a URL do ponto de extremidade da API.
• Desenvolvimento de bloco: o agente cria arquivos de bloco seguindo Edge Delivery Services convenções, incluindo funções de decoração de JavaScript, estilos CSS com escopo, rótulos ARIA para acessibilidade, carregamento e tratamento de estado de erro.
• Personalização de inclusão: se a arquitetura usar personalização de slots, o agente importará o contêiner correto, usará um slot verificado próximo ao título do produto e se inscreverá nos eventos de dados do produto para a SKU atual.

Observe o código que está sendo gerado e faça perguntas ou redirecione o agente, conforme necessário. O agente produz um resumo de prontidão de produção quando a geração do código é concluída.

Durante a Fase 4.5 (Teste), o agente se oferece para testar a implementação. Se você aceitar, o agente:

• Cria uma página de teste local com os scripts e estilos adequados.
• Inicia um servidor de desenvolvimento.
• Executa verificação baseada em navegador para renderização visual, interatividade, comportamento responsivo, acessibilidade e desempenho.
• Gera um relatório de teste estruturado com os resultados.

Siga o procedimento no navegador para confirmar o comportamento e relatar qualquer problema.

Observe as alterações na base de código e observe as atualizações na página do produto.

Você deve ver as seguintes alterações no ambiente de desenvolvimento e no navegador:

• Um componente de classificação de produto é criado automaticamente.
• O componente é integrado ao PDP usando slots internos ou como um bloco autônomo, dependendo da arquitetura escolhida.
• As estrelas são exibidas com proporções de preenchimento apropriadas com base nos valores de classificação da sua API.

{width="600" modal="regular"}

Antes de iniciar: Salve a imagem de modelo a seguir e cole-a no chat com o agente da loja.

{width="600" modal="regular"}

Siga estas etapas para criar o modal de distribuição de classificações usando a imagem de referência como guia:

• Atualize a API para retornar dados adicionais que representem a distribuição de classificações.
• Atualize o contrato de API.
• Atualize o contrato na base de código de vitrine.
• Peça ao agente da loja que use a imagem de referência e o contrato de API atualizado para adicionar a distribuição de classificações à página PDP.

Observe as seguintes alterações na base de código e observe as atualizações na página do produto:

• Como o agente interpreta o modelo visual
• Se ela usa a estrutura apropriada do HTML para acessibilidade
• Como ele lida com os estados de posicionamento e interação