评级扩展教程

导航到​Cursor > Settings > Cursor Settings > Tools & MCP，并验证commerce-extensibility工具集是否已启用且未出现错误。 如果看到错误，请关闭和打开工具集。

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

禁用光标上下文中的任何文档：

• 导航到​Cursor > Settings > Cursor Settings > Indexing & Docs​并删除列出的任何文档。

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

为产品评级扩展生成代码：

• 从Cursor chat窗口中，选择​ Agent ​模式。
• 输入以下提示：

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

准确地回答座席的问题以帮助其生成最佳代码。

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

使用以下示例文本回答座席的问题，以设置随机评级数据：

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.

代理将创建一个requirements.md文件，用作实现的真实来源。

AI代理创建的 {width="600" modal="regular"}

查看requirements.md文件并验证计划。

如果一切看起来都正确，请指示代理移至​阶段2 — 架构计划。

查看体系结构计划。

指示代理继续生成代码。

代理程序会生成必要的代码并提供详细的摘要，其中包含后续步骤。

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

请求代理帮助您在本地测试代码。

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

按照代理的说明操作，并确认API在本地工作。

用于本地API测试的 {width="600" modal="regular"}

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

验证生成的代码后，使用以下提示部署扩展：

Deploy the ratings API.

代理在部署之前执行部署前就绪性评估。

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

如果对评估结果有信心，请指示代理继续部署。

代理使用MCP工具包自动验证、构建和部署。

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

导航到storefront文件夹：

cd storefront

在新的“光标”窗口中打开店面文件夹。

或者，如果您安装了Cursor CLI，请在终端中使用以下命令打开该窗口：

cursor .

启动本地开发服务器：

npm run start

在浏览器中，导航到产品页面：

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

观察样板店面的产品详细信息页面(PDP)，并注意缺少可视产品评级。

对代理使用以下提示：

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

座席会评估任务的复杂性并调用分阶段的工作流。 在​ 阶段1（要求收集） ​期间，代理会创建一个要求文档，并询问澄清以下问题：

• PDP上的哪个位置应该显示评级？
• 这应该是一个新的独立块，还是现有PDP插入组件中的插槽自定义？
• 如果API不可用或未返回任何数据，则应该进行何种回退？
• 评级应该同时出现在PLP（产品列表）上，还是仅出现在PDP上？
• 有没有设计规格或模型？

根据您的项目要求回答这些问题。 代理程序将更新需求文档并将阶段标记为完成。

在​ 第2阶段（体系结构规划） ​期间，代理在建议体系结构之前会研究文档和您的代码库。 希望代理能够：

• 在Commerce文档中搜索PDP放置容器、插槽和事件负载。
• 扫描您的blocks目录和scripts/initializers/文件夹以查找现有的PDP相关代码。
• 浏览可用容器和槽上下文形状的TypeScript定义。

然后，代理会显示体系结构选项，例如：

• 选项A：​自定义现有的PDP插入式插槽，以在产品标题附近插入评级 — 触摸更轻，更便于升级。
• 选项B：​创建独立从API获取的新独立product-ratings块 — 更加灵活和分离。
• 选项C：​创建一个同时侦听产品SKU的PDP插入事件的新块 — 一种混合方法。

该计划还包括有关API集成、性能注意事项（延迟加载、缓存）、安全性（输入清理）和测试方法的详细信息。

查看体系结构计划并指示代理继续。

在​ 阶段3（实施方法） ​期间，代理要求您选择：

• 选项A：​在代码生成之前查看详细的实施计划（首先查看所有文件、模式和代码结构）。
• 选项B：​直接继续生成代码。

选择您首选的方法。

在​ 阶段4（实现） ​期间，代理会根据所选架构生成代码。 根据具体方法，工程师会使用多种专业技能：

• 内容建模：​如果需要新块，代理将设计一个易于作者使用的内容结构，如带有API端点URL的配置表。
• 块开发：​代理按照Edge Delivery Services约定创建块文件，包括JavaScript修饰函数、作用域CSS样式、用于辅助功能的ARIA标签以及加载和错误状态处理。
• 插入式自定义：​如果体系结构使用插槽自定义，则代理将导入正确的容器，使用产品标题附近的验证插槽，并订阅当前SKU的产品数据事件。

观察生成的代码并提问或根据需要重定向代理。 代理在代码生成完成后生成生产就绪摘要。

在​ 阶段4.5（测试） ​期间，代理提供测试实现的功能。 如果您接受，代理程序：

• 使用正确的脚本和样式创建本地测试页。
• 启动开发服务器。
• 运行基于浏览器的可视化渲染、交互、响应行为、可访问性和性能验证。
• 生成包含结果的结构化测试报告。

在浏览器中关注以确认行为并报告任何问题。

观察代码库中的变化，并观察产品页面以了解更新。

您应在开发环境和浏览器中看到以下更改：

• 系统会自动创建产品评级组件。
• 组件使用插入式插槽集成到PDP中，或者作为独立块，具体取决于选择的体系结构。
• 星标以适当的填充比例显示，填充比例基于API中的评级值。

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

开始之前：​保存以下模拟图像并将其粘贴到与店面代理的聊天中。

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

请按照以下步骤使用参考图像作为指南来创建评级分布模式：

• 更新API以返回表示评级分布的附加数据。
• 更新API合同。
• 更新店面代码库中的合同。
• 要求店面代理使用参考图像和更新的API合同将评级分发添加到PDP页面。

观察代码库中的以下更改，并查看产品页面以了解更新：

• 代理如何解释可视化模型
• 它是否使用适当的HTML结构来实现辅助功能
• 如何处理定位和交互状态