开发 Medusa storefront 前端集成时：用…

在规划、实现或探索 Medusa storefront 功能，需要调用自定义 API routes、集成 SDK、使用 React Query 做数据获取与变更时使用。

适用场景

解决思路

1. 在编写 storefront 集成代码前，必须先加载 references/frontend-integration.md；快速参考不足以用于实现。
2. 调用 API routes 时，必须先加载 references/frontend-integration.md。
3. 使用 SDK 时，必须先加载 references/frontend-integration.md。
4. 实现 React Query 时，必须先加载 references/frontend-integration.md。
5. 按优先级处理规则类别：1 SDK Usage（CRITICAL），2 React Query Patterns（HIGH），3 Data Display（HIGH，含 CRITICAL price rule），4 Error Handling（MEDIUM）。
6. SDK Usage：始终使用 Medusa JS SDK 处理所有 API 请求，绝不使用普通 fetch()。
7. SDK Usage：对内置 endpoints，使用已有 SDK 方法，例如 sdk.store.product.list()、sdk.admin.order.retrieve()。
8. SDK Usage：对自定义 API routes，使用 sdk.client.fetch()。
9. SDK Usage：依赖 SDK 自动添加所需 headers（store 的 publishable API key、admin 的 auth）；普通 fetch() 缺少这些 headers 会导致错误。
10. SDK Usage：绝不对 body 使用 JSON.stringify()；SDK 会自动处理序列化。
11. SDK Usage：向 body 传普通 JavaScript 对象，而不是字符串。
12. SDK Usage：使用 SDK 前，始终先定位项目中 SDK 实例化的位置。
13. React Query：GET 请求（数据获取）使用 useQuery。
14. React Query：POST/DELETE 请求（mutations）使用 useMutation。
15. React Query：在 onSuccess 中 invalidate queries，以便 mutations 后刷新数据。
16. React Query：将 query keys 结构化成分层结构，以实现有效缓存管理。
17. React Query：始终处理 isLoading、isPending、isError 状态。
18. Data Display：显示 Medusa 价格时直接显示原值（$49.99 = 49.99，不是 cents）；绝不要除以 100。
19. Error Handling：在 mutations 中实现 onError callback 处理失败。
20. Error Handling：当 mutations 失败时，向用户展示错误消息。
21. Error Handling：使用带错误回滚的 optimistic updates，以改善 UX。
22. 关键 SDK 模式：始终向 SDK 传普通对象；绝不要使用 JSON.stringify()。正确示例：await sdk.client.fetch('/store/reviews', { method: 'POST', body: { product_id: 'prod_123', rating: 5 } })。错误示例：body: JSON.stringify({ product_id: 'prod_123', rating: 5 })。
23. 关键 SDK 模式原因：SDK 自动处理 JSON 序列化；使用 JSON.stringify() 会双重序列化并破坏请求；服务器无法解析 body。
24. 实现前检查 SDK Usage：不要用普通 fetch() 替代 Medusa JS SDK（会导致 missing header 错误）。
25. 实现前检查 SDK Usage：对内置 endpoints，不要不用已有 SDK 方法（例如不要用 sdk.client.fetch('/store/products') 代替 sdk.store.product.list()）。
26. 实现前检查 SDK Usage：不要在 body parameter 上使用 JSON.stringify()。
27. 实现前检查 SDK Usage：不要手动设置 Content-Type headers（SDK 会添加）。
28. 实现前检查 SDK Usage：不要硬编码 SDK import paths（先定位项目中的位置）。
29. 实现前检查 SDK Usage：自定义 routes 不要不用 sdk.client.fetch()。
30. 实现前检查 React Query：mutations 后不要不 invalidate queries。
31. 实现前检查 React Query：不要用 flat query keys，而要用 hierarchical query keys。
32. 实现前检查 React Query：不要不处理 loading 和 error states。
33. 实现前检查 React Query：不要在 mutations 期间忘记禁用按钮（isPending）。
34. 实现前检查 Data Display：显示价格时绝不要除以 100（价格按原样存储：$49.99 = 49.99，不是 cents）。
35. 实现前检查 Error Handling：不要不实现 onError callbacks。
36. 实现前检查 Error Handling：不要不向用户展示错误消息。
37. 实现前检查 Error Handling：不要不优雅处理 network failures。
38. 要获取详细模式和示例，加载 reference file：references/frontend-integration.md，其中包含 SDK 使用、React Query 模式、API 集成。
39. references/frontend-integration.md 包含：逐步 SDK 集成模式、完整 React Query 示例、正确与错误代码示例、query key 最佳实践、optimistic update 模式、错误处理策略。
40. 将本技能作为主要来源，用于：如何从 storefront 调用自定义 API routes、SDK 使用模式（sdk.client.fetch）、React Query 集成模式、常见错误和反模式。
41. 将 MedusaDocs MCP server 作为次要来源，用于：内置 SDK 方法（sdk.admin.*、sdk.store.*）、官方 Medusa SDK API 参考、框架特定配置选项。
42. 优先使用技能：技能包含 MCP 未强调的关键模式（如「不要使用 JSON.stringify」）；技能展示正确与错误模式，MCP 展示可能性；规划需要理解模式，而不只是 API 参考。
43. 跨 backend 和 frontend 构建功能时：Backend 使用 building-with-medusa skill，按 Module → Workflow → API Route。
44. 跨 backend 和 frontend 构建功能时：Storefront 使用本技能，按 SDK → React Query → UI Components。
45. 跨 backend 和 frontend 构建功能时，连接方式：内置 endpoints 使用已有 SDK 方法（sdk.store.product.list()）。
46. 跨 backend 和 frontend 构建功能时，连接方式：自定义 API routes 使用 sdk.client.fetch('/store/my-route')。
47. 跨 backend 和 frontend 构建功能时，连接方式：绝不使用普通 fetch()，因为缺少 publishable API key 会导致错误。
48. 理解 SDK 必需原因：Store routes 需要 x-publishable-api-key header；Admin routes 需要 Authorization 和 session headers；SDK 自动处理所有必需 headers；普通 fetch() 没有 headers 会导致 authentication/authorization 错误。
49. 后端 API route 模式参见 building-with-medusa。

适用边界 · 注意事项

• 开发非 Medusa storefront，或不需要调用 Medusa API 时，不应套用本经验。
• 只需要查阅官方 Medusa SDK API 参考或框架特定配置选项时，应优先使用 MedusaDocs MCP server 作为补充。
• 构建 Medusa 后端 API routes 时，应配合 building-with-medusa skill，而不是只依赖本技能。