Tutorial zur Bewertungserweiterung

Navigieren Sie zu Cursor > Settings > Cursor Settings > Tools & MCP und stellen Sie sicher, dass das commerce-extensibility-Toolset fehlerfrei aktiviert ist. Wenn Fehler angezeigt werden, schalten Sie das Toolset aus und ein.

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

Deaktivieren Sie jede Dokumentation im Kontext des Cursors:

• Navigieren Sie zu Cursor > Settings > Cursor Settings > Indexing & Docs und löschen Sie die aufgelistete Dokumentation.

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

Generieren von Code für eine Produktbewertungserweiterung:

• Wählen Sie im Cursor-Chat-Fenster den Agent aus.
• Geben Sie die folgende Eingabeaufforderung ein:

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

Beantworten Sie die Fragen des Agenten genau, damit er den besten Code generieren kann.

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

Verwenden Sie den folgenden Beispieltext, um die Fragen des Agenten zu beantworten und randomisierte Bewertungsdaten einzurichten:

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.

Der Agent erstellt eine requirements.md-Datei, die als Datenquelle für die Implementierung dient.

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

Überprüfen Sie die requirements.md und überprüfen Sie den Plan.

Wenn alles korrekt aussieht, weisen Sie den Agenten an, zu Phase 2 - Architekturplanung zu wechseln.

Überprüfen Sie den Architekturplan.

Weisen Sie den Agenten an, mit der Code-Generierung fortzufahren.

Der Agent generiert den erforderlichen Code und stellt eine detaillierte Zusammenfassung der nächsten Schritte bereit.

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

Bitten Sie den Agenten, Ihnen beim lokalen Testen des Codes zu helfen.

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

Befolgen Sie die Anweisungen des Agenten und bestätigen Sie, dass die API lokal funktioniert.

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

Nachdem Sie den generierten Code überprüft haben, stellen Sie die Erweiterung mithilfe der folgenden Eingabeaufforderung bereit:

Deploy the ratings API.

Der Agent führt vor der Bereitstellung eine Bewertung der Bereitschaft durch.

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

Wenn Sie mit den Bewertungsergebnissen vertraut sind, weisen Sie den Agenten an, mit der Bereitstellung fortzufahren.

Der Agent verwendet das MCP-Toolkit, um automatisch zu überprüfen, zu erstellen und bereitzustellen.

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

Navigieren Sie zum Ordner storefront :

cd storefront

Öffnen Sie den Ordner „Storefront“ in einem neuen Cursor-Fenster.

Alternativ können Sie, wenn Sie die Cursor-CLI installiert haben, das Fenster öffnen, indem Sie den folgenden Befehl an Ihrem Terminal verwenden:

cursor .

Starten Sie den lokalen Entwicklungs-Server:

npm run start

Navigieren Sie in einem Browser zu einer Produktseite:

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

Beachten Sie die Produktdetailseite für die TextbausteinStorefront (PDP) und beachten Sie den Mangel an visuellen Produktbewertungen.

Verwenden Sie die folgende Eingabeaufforderung mit Ihrem Agenten:

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

Der Agent bewertet die Aufgabenkomplexität und ruft einen stufenweisen Workflow auf. Während Phase 1 (Anforderungserfassung) erstellt der Agent ein Anforderungsdokument und stellt klärende Fragen wie:

• Wo in der PDP sollten die Bewertungen erscheinen?
• Sollte es sich um einen neuen eigenständigen Block oder eine Steckplatzanpassung innerhalb der vorhandenen Dropdown-Komponente von PDP handeln?
• Was sollte der Fallback sein, wenn die API nicht verfügbar ist oder keine Daten zurückgibt?
• Sollen Bewertungen auch auf der PLP (Produktliste) oder nur auf PDP erscheinen?
• Gibt es Designspezifikationen oder Mockups?

Beantworten Sie diese Fragen entsprechend Ihren Projektanforderungen. Der Agent aktualisiert das Anforderungsdokument und markiert die Phase als abgeschlossen.

Während Phase 2 (Architekturplanung) durchsucht der Agent die Dokumentation und Ihre Codebasis, bevor er eine Architektur vorschlägt. Der Agent soll:

• Suchen Sie in Commerce Dokumentation nach PDP-Dropdown-Containern, Slots und Ereignis-Payloads.
• Überprüfen Sie Ihr blocks und scripts/initializers/ Ordner auf vorhandenen PDP-bezogenen Code.
• Erkunden Sie TypeScript-Definitionen für verfügbare Container und Slotkontext-Shapes.

Der Agent stellt dann Architekturoptionen bereit, z. B.:

• Option A: Passen Sie einen vorhandenen PDP-Dropdown-Slot an, um Bewertungen in der Nähe des Produkttitels einzufügen - eine leichtere Berührung, die upgradefreundlich ist.
• Option B: Erstellen Sie einen neuen eigenständigen product-ratings, der unabhängig von der API abgerufen wird - flexibler und entkoppelt.
• Option C: Erstellen Sie einen neuen Block, der auch auf PDP-Ablageereignisse für die Produkt-SKU lauscht - ein hybrider Ansatz.

Der Plan enthält auch Details zur API-Integration, Leistungsaspekte (verzögertes Laden, Caching), Sicherheit (Bereinigung der Eingabe) und einen Testansatz.

Überprüfen Sie den Architekturplan und weisen Sie den Agenten an, fortzufahren.

Während Phase 3 (Implementierungsansatz) bittet der Agent Sie, zwischen folgenden Optionen zu wählen:

• Option A: Überprüfen Sie vor der Code-Generierung einen detaillierten Implementierungsplan (sehen Sie sich zuerst alle Dateien, Muster und die Code-Struktur an).
• Option B: Direkt mit der Code-Erstellung fortfahren.

Wählen Sie Ihren bevorzugten Ansatz aus.

Während Phase 4 (Implementierung) generiert der Agent Code basierend auf der ausgewählten Architektur. Je nach Ansatz verwendet der Agent mehrere spezialisierte Fähigkeiten:

• Inhaltsmodellierung: Wenn ein neuer Block erforderlich ist, entwirft der Agent eine benutzerfreundliche Inhaltsstruktur, z. B. eine Konfigurationstabelle mit der API-Endpunkt-URL.
• Blockentwicklung: Der Agent erstellt Blockdateien gemäß Edge Delivery Services Konventionen, einschließlich JavaScript-Dekorationsfunktionen, CSS-Stilen in einem Umfang, ARIA-Kennzeichnungen für Barrierefreiheit sowie Lade- und Fehlerstatusbehandlung.
• Dropdown-Anpassung: Wenn die Architektur die Anpassung von Slots verwendet, importiert der Agent den richtigen Container, verwendet einen verifizierten Slot in der Nähe des Produkttitels und abonniert Produktdatenereignisse für die aktuelle SKU.

Beobachten Sie, wie der Code generiert wird, und stellen Sie Fragen oder leiten Sie den Agenten nach Bedarf weiter. Der Agent erstellt nach Abschluss der Code-Generierung eine Zusammenfassung der Produktionsbereitschaft.

Während Phase 4.5 (Testen) bietet der Agent an, die Implementierung zu testen. Wenn Sie akzeptieren, wird der Agent:

• Erstellt eine lokale Testseite mit den richtigen Skripten und Stilen.
• Startet einen Entwicklungsserver.
• Führt eine browserbasierte Überprüfung für visuelles Rendering, Interaktivität, responsives Verhalten, Barrierefreiheit und Leistung durch.
• Erzeugt einen strukturierten Testbericht mit den Ergebnissen.

Folgen Sie im Browser, um das Verhalten zu bestätigen und Probleme zu melden.

Beobachten Sie die Änderungen in der Code-Basis und suchen Sie auf der Produktseite nach Updates.

In Ihrer Entwicklungsumgebung und Ihrem Browser sollten die folgenden Änderungen angezeigt werden:

• Eine Produktbewertungskomponente wird automatisch erstellt.
• Die Komponente wird je nach ausgewählter Architektur mit Drop-In-Steckplätzen oder als eigenständiger Block in die PDP integriert.
• Sterne werden mit korrekten Füllverhältnissen basierend auf den Bewertungswerten aus Ihrer API angezeigt.

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

Vor dem Start: Speichern Sie das folgende Pseudo-Bild und fügen Sie es in den Chat mit Ihrem Storefront-Agenten ein.

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

Führen Sie die folgenden Schritte aus, um das Modal „Bewertungsverteilung“ mithilfe des Referenzbilds als Anleitung zu erstellen:

• Aktualisieren Sie die -API, um zusätzliche Daten zur Verteilung der Bewertungen zurückzugeben.
• Aktualisieren Sie den API-Vertrag.
• Aktualisieren Sie den Vertrag in der Code-Basis der Storefront.
• Bitten Sie den Storefront-Agenten, das Referenzbild und den aktualisierten API-Vertrag zu verwenden, um die Bewertungsverteilung zur PDP-Seite hinzuzufügen.

Sehen Sie sich die folgenden Änderungen in der Code-Basis an und suchen Sie auf der Produktseite nach Aktualisierungen:

• Interpretation des visuellen Mockups durch den Agenten
• Ob eine geeignete HTML-Struktur für Barrierefreiheit verwendet wird
• Handhabung der Positionierungs- und Interaktionsstatus