Esercitazione sull’estensione delle valutazioni

Passare a Cursor > Settings > Cursor Settings > Tools & MCP e verificare che il set di strumenti commerce-extensibility sia abilitato senza errori. Se vengono visualizzati degli errori, disattiva e attiva la serie di strumenti.

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

Disattiva qualsiasi documentazione nel contesto del cursore:

• Passa a Cursor > Settings > Cursor Settings > Indexing & Docs ed elimina la documentazione elencata.

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

Genera il codice per un’estensione di valutazione del prodotto:

• Dalla finestra di chat del cursore, selezionare la modalità Agent.
• Immetti il seguente 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

Rispondi alle domande dell'agente esattamente per aiutarlo a generare il codice migliore.

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

Utilizza il testo di esempio seguente per rispondere alle domande dell’agente per impostare dati di valutazione randomizzati:

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'agente crea un file requirements.md che funge da origine di verità per l'implementazione.

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

Esaminare il file requirements.md e verificare il piano.

Se tutto sembra corretto, indicare all'agente di passare alla Fase 2 - Pianificazione architettura.

Rivedi il piano dell’architettura.

Indica all'agente di procedere con la generazione del codice.

L'agente genera il codice necessario e fornisce un riepilogo dettagliato con i passaggi successivi.

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

Chiedi all'agente di aiutarti a testare il codice localmente.

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

Segui le istruzioni dell’agente e verifica che l’API funzioni localmente.

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

Dopo aver verificato il codice generato, distribuisci l’estensione utilizzando il seguente prompt:

Deploy the ratings API.

Prima della distribuzione, l'agente esegue una valutazione di fattibilità pre-distribuzione.

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

Quando sei sicuro dei risultati della valutazione, indica all’agente di procedere con la distribuzione.

L’agente utilizza il toolkit MCP per verificare, generare e distribuire automaticamente.

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

Passare alla cartella storefront:

cd storefront

Aprire la cartella vetrina in una nuova finestra Cursore.

In alternativa, se è installato Cursor CLI, aprire la finestra utilizzando il comando seguente nel terminale:

cursor .

Avvia il server di sviluppo locale:

npm run start

In un browser, accedi a una pagina di prodotto:

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

Osserva la pagina dei dettagli del prodotto (PDP) della vetrina e osserva la mancanza di valutazioni visive del prodotto.

Chiedi all'agente di effettuare le seguenti operazioni:

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'agente valuta la complessità dell'attività e richiama un flusso di lavoro graduale. Durante la Fase 1 (Raccolta dei requisiti), l'agente crea un documento sui requisiti e pone domande di chiarimento quali:

• Dove deve apparire la valutazione nel PDP?
• Deve trattarsi di un nuovo blocco autonomo o di una personalizzazione degli slot all’interno del componente di rilascio PDP esistente?
• Cosa deve essere il fallback se l’API non è disponibile o non restituisce dati?
• Le valutazioni devono essere visualizzate anche su PLP (elenco prodotti) o solo su PDP?
• Esistono specifiche o modelli di progettazione?

Rispondi a queste domande in base ai requisiti del progetto. L'agente aggiorna il documento sui requisiti e contrassegna la fase come completata.

Durante la Fase 2 (Pianificazione dell'architettura), l'agente cerca la documentazione e la base di codice prima di proporre un'architettura. L'agente dovrà:

• Cerca nella documentazione di Commerce contenitori di rilascio PDP, slot e payload di eventi.
• Analizzare la directory blocks e la cartella scripts/initializers/ per rilevare il codice esistente relativo a PDP.
• Esplora le definizioni TypeScript per i contenitori disponibili e le forme contesto slot.

L’agente presenta quindi opzioni di architettura quali:

• Opzione A: Personalizzare uno slot di rilascio PDP esistente per inserire valutazioni simili al titolo del prodotto, in modo da semplificarne l'aggiornamento.
• Opzione B: Crea un nuovo blocco product-ratings autonomo che recupera dall'API in modo indipendente, più flessibile e disaccoppiato.
• Opzione C: Crea un nuovo blocco che ascolta anche gli eventi di rilascio PDP per lo SKU del prodotto, un approccio ibrido.

Il piano include anche dettagli sull’integrazione API, considerazioni sulle prestazioni (caricamento lento, caching), sicurezza (bonifica degli input) e un approccio di test.

Rivedi il piano dell’architettura e ordina all’agente di procedere.

Durante la Fase 3 (Approccio all'implementazione), l'agente ti chiede di scegliere tra:

• Opzione A: Rivedere un piano di implementazione dettagliato prima della generazione del codice (vedere prima tutti i file, i modelli e la struttura del codice).
• Opzione B: Procedere direttamente alla generazione del codice.

Seleziona l’approccio desiderato.

Durante la fase 4 (implementazione), l'agente genera il codice in base all'architettura scelta. A seconda dell’approccio, l’agente utilizza diverse competenze specializzate:

• Modellazione contenuto: Se è necessario un nuovo blocco, l'agente progetta una struttura di contenuto compatibile con l'autore, ad esempio una tabella di configurazione con l'URL dell'endpoint API.
• Sviluppo del blocco: L'agente crea i file di blocco in base alle convenzioni di Edge Delivery Services, incluse le funzioni di decorazione JavaScript, gli stili CSS con ambito, le etichette ARIA per l'accessibilità e la gestione dello stato di caricamento e di errore.
• Personalizzazione dell'eliminazione: Se l'architettura utilizza la personalizzazione degli slot, l'agente importa il contenitore corretto, utilizza uno slot verificato accanto al titolo del prodotto e si abbona agli eventi dei dati del prodotto per lo SKU corrente.

Guarda il codice generato e fai domande o reindirizza l’agente secondo necessità. Al termine della generazione del codice, l'agente genera un riepilogo della fattibilità di produzione.

Durante la fase 4.5 (test), l'agente offre di testare l'implementazione. Se accetti, l'agente:

• Crea una pagina di test locale con gli script e gli stili appropriati.
• Avvia un server di sviluppo.
• Esegue la verifica basata su browser per il rendering visivo, l’interattività, il comportamento reattivo, l’accessibilità e le prestazioni.
• Genera un report di test strutturato con i risultati.

Segui il comportamento nel browser per confermarlo e segnalare eventuali problemi.

Osserva le modifiche nella base di codice e controlla la pagina del prodotto per gli aggiornamenti.

Dovresti visualizzare le seguenti modifiche nell’ambiente di sviluppo e nel browser:

• Viene creato automaticamente un componente di valutazione del prodotto.
• Il componente è integrato nel PDP utilizzando slot di rilascio o come blocco autonomo, a seconda dell'architettura scelta.
• Le stelle vengono visualizzate con proporzioni di riempimento appropriate in base ai valori di valutazione dell’API.

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

Prima di iniziare: Salva la seguente immagine fittizia e incollala nella chat con il tuo agente storefront.

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

Per creare la distribuzione modale delle valutazioni utilizzando come guida l’immagine di riferimento, segui la procedura riportata di seguito:

• Aggiorna l’API per restituire dati aggiuntivi che rappresentano la distribuzione delle valutazioni.
• Aggiorna il contratto API.
• Aggiorna il contratto nella base di codice della vetrina.
• Chiedi all’agente vetrina di utilizzare l’immagine di riferimento e il contratto API aggiornato per aggiungere la distribuzione delle valutazioni alla pagina PDP.

Osserva le seguenti modifiche nella base di codice e controlla la pagina del prodotto per gli aggiornamenti:

• Come l’agente interpreta il modello visivo
• Indica se viene utilizzata la struttura HTML appropriata per l'accessibilità
• Come gestisce gli stati di posizionamento e interazione