mcpField
B
bagisto-api-shop

bagisto-api-shop

github.com/bagisto开发13221 次安装2 周前更新
代码仓库

关于 bagisto-api-shop

用于基于 Bagisto Shop API 构建面向客户的店铺前端技能。它先确认平台、技术栈和 REST 或 GraphQL 传输方式，再引导开发者查阅各功能的实现参考。

主要功能

  1. 01目录、购物车、结账和账户流程指南
  2. 02REST 与 GraphQL 实现指南
  3. 03按功能划分的 API 参考
  4. 04身份验证与购物车生命周期指南

适用场景

  1. 01构建商品目录与搜索体验
  2. 02实现购物车、结账和订单确认
  3. 03添加客户登录、个人资料与订单历史

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bagisto/agent-skills --skill bagisto-api-shop

安装后在 Claude Code 中输入/bagisto-api-shop确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

reference/
connecting-to-the-api.md
graphql.md
reference/features/
compare.md
contact-us.md
coupons.md
newsletter.md
reviews.md
storefront-context.md
wishlist.md
reference/flows/
account.md
add-to-cart.md
authentication.md
cart.md
checkout.md
customer-orders.md
order-confirmation.md
product-details.md
product-listing.md

详细介绍

在 Bagisto Shop API 上构建店面

在 Bagisto Shop API（/api/shop/* REST + POST /api/graphql）上实现任意面向客户的店面功能——商品目录、购物车、结账、账户、愿望清单、商品对比。此技能是一个路由指南：它会说明流程，并引导你查看各项功能的参考页面；参考页面包含架构、UI/UX、端点和检查清单。

⚠️ 首先加载这些内容（编写任何代码之前）

  1. reference/connecting-to-the-api.md — 身份验证（店面密钥 + 购物车/客户令牌）、{data,meta}/标头分页、错误代码，以及编码前验证流程。
  2. reference/graphql.md — 如果客户端选择了 GraphQL：结果字段/id 规则、camelCase 输入、游标分页。

api-docs 是确切请求/响应格式的权威来源——https://api-docs.bagisto.com 及其 /llms.txt 索引。参考页面会列出端点和流程；编写调用前，请打开链接的文档页面，确认确切的请求体/响应。切勿凭记忆编造请求载荷。

第 1 步——询问客户（关键，开始构建前）

  1. 平台——Web、移动端（原生/跨平台）还是桌面端？
  2. 框架/技术栈——React/Next、Vue/Nuxt、Flutter、React Native、Swift/Kotlin，还是纯 JS？
  3. 传输方式——REST 还是 GraphQL？（简单界面使用 REST；界面需要一次获取多个相关字段时使用 GraphQL。两者都获得全面支持。）
  4. 首个功能/流程——商品目录、购物车+结账、账户，还是其他？

确认后，根据答案定制所有内容。不要假定技术栈。

第 2 步——打开对应功能的参考页面

流程（多步骤旅程/页面）
页面构建内容
reference/flows/product-listing.md分类、商品列表、搜索、筛选
reference/flows/product-details.md商品页面（按类型发现选项、评价、相关商品）
reference/flows/add-to-cart.md按商品类型添加到购物车
reference/flows/cart.md迷你购物车 + 购物车页面（读取/更新/移除/合并/总计）
reference/flows/checkout.md地址 → 配送 → 付款 → 下单
reference/flows/order-confirmation.md下单后的感谢页面
reference/flows/authentication.md注册、登录、注销、验证、忘记/更改密码
reference/flows/account.md个人资料 + 地址簿
reference/flows/customer-orders.md订单历史记录、详情、取消、重新下单、发票、可下载商品
功能（单项能力）
页面构建内容
reference/features/coupons.md应用/移除优惠券
reference/features/wishlist.md愿望清单添加/切换/查看/移至购物车
reference/features/compare.md商品对比列表
reference/features/reviews.md商品评价 + 客户自己的评价
reference/features/newsletter.md订阅新闻简报
reference/features/contact-us.md联系表单
reference/features/storefront-context.md国家/州、渠道、货币、区域设置、CMS 页面、主题

每个页面都包含概述 → 流程架构 → UI/UX → API 分步说明（含确切端点）→ 错误 → 检查清单。请遵循这些内容；确切的数据格式以 api-docs 为准。

汇总的关键规则（容易踩坑的要点）

  • 编码前先验证。 暂停 → 打开端点的文档页面（或查询 MCP）→ 确认方法和字段 → 实现 → 检查类型。不要猜测端点名称或请求体。
  • 不同接口使用不同的身份验证方式。 每次店铺调用都要发送 X-STOREFRONT-KEY；购物车、账户和结账调用还要发送 Authorization: Bearer <cartToken | customerToken>。访客必须先创建购物车令牌（POST /api/shop/cart-tokens）。
  • 修改购物车或结账的调用会返回完整的更新后购物车——根据响应同步更新 UI，不要在本地修改。
  • 登录时合并访客购物车与客户购物车（merge-carts），否则访客的商品会丢失。
  • 下单后清理——清除购物车状态并丢弃访客购物车令牌，否则购物车弹窗会显示过期商品。
  • GraphQL：操作型变更应选择文档中规定的结果字段（success/message/orderId/总计），不要使用通用的 id；输入字段采用 camelCase；每行只写一个字段。参见 reference/graphql.md。
  • 不要硬编码动态数据（配送方式、支付方式、价格、选项）——从 API 获取。

评论

支持 Markdown