Tutoriel sur l’extension d’évaluations

Accédez à Cursor > Settings > Cursor Settings > Tools & MCP et vérifiez que l’ensemble d’outils commerce-extensibility est activé sans erreur. Si des erreurs s’affichent, désactivez la palette d’outils et activez-la.

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

Désactivez toute documentation dans le contexte du curseur :

• Accédez à Cursor > Settings > Cursor Settings > Indexing & Docs et supprimez toute documentation répertoriée.

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

Générer le code pour une extension d’évaluation de produit :

• Dans la fenêtre de conversation Cursor, sélectionnez le mode Agent.
• Saisissez l’invite suivante :

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

Répondez précisément aux questions de l’agent pour l’aider à générer le meilleur code.

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

Utilisez l’exemple de texte suivant pour répondre aux questions de l’agent afin de configurer les données d’évaluation randomisées :

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.

L’agent crée un fichier requirements.md qui sert de source de vérité pour l’implémentation.

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

Consultez le fichier requirements.md et vérifiez le plan.

Si tout semble correct, demandez à l'agent de passer à Phase 2 - Planification de l'architecture.

Examinez le plan d’architecture.

Demandez à l’agent de poursuivre la génération du code.

L’agent génère le code nécessaire et fournit un résumé détaillé des étapes suivantes.

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

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

Demandez à l’agent de vous aider à tester le code localement.

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

Suivez les instructions de l’agent et vérifiez que l’API fonctionne localement.

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

Après avoir vérifié le code généré, déployez l’extension à l’aide de l’invite suivante :

Deploy the ratings API.

L’agent effectue une évaluation de préparation avant le déploiement.

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

Lorsque vous êtes certain des résultats de l’évaluation, demandez à l’agent de procéder au déploiement.

L’agent utilise la boîte à outils MCP pour vérifier, créer et déployer automatiquement.

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

Accédez au dossier storefront :

cd storefront

Ouvrez le dossier storefront dans une nouvelle fenêtre Cursor .

Si l’interface de ligne de commande Cursor CLI est installée, vous pouvez également ouvrir la fenêtre à l’aide de la commande suivante dans votre terminal :

cursor .

Démarrez le serveur de développement local :

npm run start

Dans un navigateur, accédez à une page de produit :

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

Observez la page standard des détails du produit (PDP) du storefront et notez l’absence d’évaluations visuelles du produit.

Utilisez l’invite suivante avec votre agent :

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

L’agent évalue la complexité de la tâche et appelle un workflow échelonné. Au cours de la phase 1 (collecte des exigences) l'agent crée un document d'exigences et pose des questions de clarification telles que :

• Où les notes devraient-elles apparaître sur le PDP ?
• S’agit-il d’un nouveau bloc autonome ou d’une personnalisation d’emplacement dans le composant de dépôt PDP existant ?
• Quelle doit être la solution de secours si l’API n’est pas disponible ou ne renvoie aucune donnée ?
• Les évaluations doivent-elles également apparaître sur le PLP (liste de produits) ou le PDP uniquement ?
• Existe-t-il des spécifications de conception ou des maquettes ?

Répondez à ces questions en fonction des exigences de votre projet. L’agent met à jour le document des exigences et marque la phase comme terminée.

Au cours de Phase 2 (planification architecturale) l’agent effectue des recherches dans la documentation et votre base de code avant de proposer une architecture. Attendez-vous à ce que l’agent :

• Recherchez dans Commerce documentation les conteneurs de dépôt PDP, les emplacements et les payloads d’événement.
• Recherchez du code lié au PDP dans le répertoire blocks et le dossier scripts/initializers/.
• Explorez les définitions TypeScript pour les conteneurs et les formes contextuelles d'emplacement disponibles.

L’agent présente ensuite des options d’architecture telles que :

• Option A : personnalisez un emplacement de dépôt PDP existant pour injecter des évaluations près du titre du produit, une touche plus légère qui permet une mise à niveau.
• Option B : créez un bloc de product-ratings autonome qui récupère l’API indépendamment : plus flexible et découplé.
• Option C : créer un bloc qui écoute également les événements déroulants PDP pour le SKU du produit ; il s’agit d’une approche hybride.

Le plan comprend également des détails sur l’intégration de l’API, des considérations sur les performances (chargement différé, mise en cache), la sécurité (nettoyage des entrées) et une approche de test.

Passez en revue le plan d’architecture et demandez à l’agent de continuer.

Au cours de Phase 3 (Approche d’implémentation) l’agent vous demande de choisir entre :

• Option A : passez en revue un plan d’implémentation détaillé avant la génération du code (consultez d’abord tous les fichiers, modèles et structures de code).
• Option B : passer directement à la génération du code.

Sélectionnez l’approche de votre choix.

Au cours de Phase 4 (implémentation) l’agent génère le code en fonction de l’architecture choisie. Selon l'approche, l'agent utilise plusieurs compétences spécialisées :

• Modélisation de contenu : si un nouveau bloc est nécessaire, l’agent conçoit une structure de contenu conviviale pour la création, telle qu’une table de configuration avec l’URL du point d’entrée de l’API.
• Développement de blocs : l’agent crée des fichiers de bloc en respectant les conventions Edge Delivery Services, notamment les fonctions de décoration JavaScript, les styles CSS étendus, les libellés ARIA pour l’accessibilité, ainsi que le chargement et la gestion des états d’erreur.
• Personnalisation du Drop-in : si l’architecture utilise la personnalisation des emplacements, l’agent importe le conteneur approprié, utilise un emplacement vérifié à proximité du titre du produit et s’abonne aux événements de données de produit pour le SKU actuel.

Regardez le code en cours de génération et posez des questions ou redirigez l’agent si nécessaire. L’agent génère un résumé du niveau de préparation pour la production une fois la génération du code terminée.

Au cours de la phase 4.5 (test), l’agent propose de tester l’implémentation. Si vous acceptez, l’agent :

• Crée une page de test locale avec les scripts et les styles appropriés.
• Démarre un serveur de développement.
• Exécute une vérification basée sur un navigateur pour le rendu visuel, l’interactivité, le comportement réactif, l’accessibilité et les performances.
• Génère un rapport de test structuré avec les résultats.

Suivez les instructions dans le navigateur pour confirmer le comportement et signaler tout problème.

Observez les modifications apportées à la base de code et observez les mises à jour sur la page produit.

Les modifications suivantes devraient s’afficher dans votre environnement de développement et votre navigateur :

• Un composant d’évaluation de produit est automatiquement créé.
• Le composant est intégré au PDP à l’aide de emplacements d’accueil ou sous la forme d’un bloc autonome, selon l’architecture choisie.
• Les étoiles s’affichent avec des proportions de remplissage appropriées en fonction des valeurs d’évaluation de votre API.

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

Avant de commencer : enregistrez l’image simulée suivante et collez-la dans la conversation avec votre agent storefront.

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

Pour créer la boîte de dialogue modale de distribution des évaluations à l’aide de l’image de référence comme guide, procédez comme suit :

• Mettez à jour l’API pour renvoyer des données supplémentaires représentant la distribution des évaluations.
• Mettez à jour le contrat d’API.
• Mettez à jour le contrat dans la base de code du storefront.
• Demandez à l’agent storefront d’utiliser l’image de référence et le contrat d’API mis à jour pour ajouter la distribution des évaluations à la page PDP.

Observez les modifications suivantes dans la base de code et observez les mises à jour sur la page produit :

• Comment l’agent interprète la maquette visuelle
• Utilisation ou non de la structure HTML appropriée pour l’accessibilité
• Gestion des états de positionnement et d’interaction