Tutorial de extensión de clasificaciones

Vaya a Cursor > Settings > Cursor Settings > Tools & MCP y compruebe que el conjunto de herramientas commerce-extensibility esté habilitado sin errores. Si hay errores, active o desactive el conjunto de herramientas.

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

Deshabilite cualquier documentación en el contexto del cursor:

• Vaya a Cursor > Settings > Cursor Settings > Indexing & Docs y elimine cualquier documentación enumerada.

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

Genere un código para una extensión de clasificación de productos:

• En la ventana Cursor chat, seleccione el modo Agent.
• Introduzca la siguiente solicitud:

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 las preguntas del agente con precisión para ayudarle a generar el mejor código.

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

Utilice el siguiente texto de ejemplo para responder a las preguntas del agente con el fin de configurar datos de clasificación aleatorios:

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.

El agente crea un archivo de requirements.md que sirve como origen de la verdad para la implementación.

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

Revise el archivo requirements.md y compruebe el plan.

Si todo parece correcto, indique al agente que pase a Phase 2 - Architecture Planning.

Revise el plan de arquitectura.

Indique al agente que continúe con la generación de código.

El agente genera el código necesario y proporciona un resumen detallado de los pasos siguientes.

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

Pida al agente que le ayude a probar el código localmente.

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

Siga las instrucciones del agente y confirme que la API funciona localmente.

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

Después de verificar el código generado, implemente la extensión mediante el siguiente mensaje:

Deploy the ratings API.

El agente realiza una evaluación de la preparación previa al despliegue antes de este.

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

Cuando confíe en los resultados de la evaluación, indique al agente que continúe con el despliegue.

El agente utiliza el kit de herramientas de MCP para verificar, crear e implementar automáticamente.

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

Vaya a la carpeta storefront:

cd storefront

Abra la carpeta de la tienda en una nueva ventana Cursor.

Alternativamente, si tiene instalado el CLI de cursor, abra la ventana usando el siguiente comando en su terminal:

cursor .

Inicie el servidor de desarrollo local:

npm run start

En un explorador, vaya a una página de producto:

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

Observe la página de detalles del producto (PDP) de la tienda de plantillas y observe la falta de clasificaciones visuales del producto.

Utilice el siguiente mensaje con su 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

El agente evalúa la complejidad de la tarea e invoca un flujo de trabajo por fases. Durante la fase 1 (recopilación de requisitos), el agente crea un documento de requisitos y hace preguntas que aclaran cuestiones como las siguientes:

• ¿En qué punto del PDP deben aparecer las clasificaciones?
• ¿Debería ser un nuevo bloque independiente o una personalización de ranura dentro del componente desplegable PDP existente?
• ¿Cuál debería ser la reserva si la API no está disponible o no devuelve datos?
• ¿Las clasificaciones también deben aparecer en el PLP (lista de productos) o solo en el PDP?
• ¿Hay especificaciones de diseño o maquetas?

Responda estas preguntas en función de los requisitos de su proyecto. El agente actualiza el documento de requisitos y marca la fase como completada.

Durante la Fase 2 (Planificación arquitectónica), el agente investiga la documentación y el código base antes de proponer una arquitectura. Se espera que el agente:

• Busque en la documentación de Commerce contenedores de PDP, ranuras y cargas útiles de eventos.
• Analice el directorio blocks y la carpeta scripts/initializers/ en busca de código relacionado con PDP existente.
• Explore las definiciones de TypeScript para los contenedores disponibles y las formas de contexto de ranura.

A continuación, el agente presenta opciones de arquitectura como:

• Opción A: Personalice una ranura desplegable de PDP existente para insertar clasificaciones cerca del título del producto, un toque más ligero que sea fácil de actualizar.
• Opción B: Cree un nuevo bloque product-ratings independiente que obtenga de la API de forma independiente, más flexible y desunido.
• Opción C: Cree un nuevo bloque que también escuche eventos de PDP para el SKU del producto, un enfoque híbrido.

El plan también incluye detalles sobre la integración de la API, consideraciones de rendimiento (carga diferida, almacenamiento en caché), seguridad (saneamiento de la entrada) y un enfoque de prueba.

Revise el plan de arquitectura e indique al agente que continúe.

Durante la Fase 3 (Enfoque de implementación), el agente le pedirá que elija entre:

• Opción A: Revise un plan de implementación detallado antes de la generación de código (vea primero todos los archivos, patrones y estructura de código).
• Opción B: Continúe directamente con la generación de código.

Seleccione el método que prefiera.

Durante la fase 4 (implementación), el agente genera código basado en la arquitectura elegida. Según el enfoque, el agente utiliza varias habilidades especializadas:

• Modelado de contenido: Si se necesita un nuevo bloque, el agente diseña una estructura de contenido compatible con el autor, como una tabla de configuración con la dirección URL del extremo de API.
• Desarrollo de bloques: El agente crea archivos de bloque siguiendo las convenciones de Edge Delivery Services, incluidas las funciones decorativas de JavaScript, los estilos CSS con ámbito, las etiquetas ARIA para accesibilidad y la administración de estados de carga y error.
• Personalización de inclusión: Si la arquitectura usa la personalización de ranura, el agente importa el contenedor correcto, usa una ranura verificada cerca del título del producto y se suscribe a los eventos de datos del producto para el SKU actual.

Observe el código que se está generando y haga preguntas o redirija el agente según sea necesario. El agente produce un resumen de preparación para la producción cuando finaliza la generación de código.

Durante la fase 4.5 (Pruebas), el agente ofrece probar la implementación. Si acepta, el agente:

• Crea una página de prueba local con los scripts y estilos adecuados.
• Inicia un servidor de desarrollo.
• Ejecuta la verificación basada en el explorador para el procesamiento visual, la interactividad, el comportamiento interactivo, la accesibilidad y el rendimiento.
• Genera un informe de prueba estructurado con los resultados.

Siga los pasos del explorador para confirmar el comportamiento e informar de cualquier problema.

Observe los cambios en la base de código y observe la página de producto para ver las actualizaciones.

Debería ver los siguientes cambios en su entorno de desarrollo y explorador:

• Se crea automáticamente un componente de clasificación de productos.
• El componente está integrado en el PDP mediante ranuras de colocación o como bloque independiente, según la arquitectura elegida.
• Las estrellas se muestran con las proporciones de relleno adecuadas en función de los valores de clasificación de la API.

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

Antes de comenzar: Guarde la siguiente imagen ficticia y péguela en el chat con su agente de tienda.

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

Siga estos pasos para crear el modal de distribución de clasificaciones utilizando la imagen de referencia como guía:

• Actualice la API para devolver datos adicionales que representen la distribución de clasificación.
• Actualice el contrato de API.
• Actualice el contrato en la base de código de la tienda.
• Pida al agente de tienda que utilice la imagen de referencia y el contrato de API actualizado para añadir la distribución de clasificaciones a la página PDP.

Observe los siguientes cambios en la base de código y observe la página de producto para ver las actualizaciones:

• Cómo interpreta el agente la maqueta visual
• Si utiliza la estructura de HTML adecuada para la accesibilidad
• Cómo gestiona los estados de posicionamiento e interacción