SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场saleor-paper-storefront

saleor-paper-storefront

前端与建站

查看项目

更新于 10-16 04:12

技能介绍

用途

Saleor Paper Storefront 是一份项目专属指南，面向使用 Next.js 16、TypeScript 和 Tailwind CSS 构建、并通过 Saleor GraphQL API 获取数据的 Saleor Paper 电商前端。它包含 8 个类别共 32 条规则，帮助开发者在该代码库中遵循既定模式。

使用前提：本技能依赖 saleor-storefront 技能来获取通用 Saleor API 知识（数据模型、权限、结账生命周期、渠道），需与本技能一同安装。

主要能力（规则类别）

规则按优先级分为以下类别：

  • 优先级 0 架构（CRITICAL，前缀 paper-）：paper-architecture 为入口，说明 Next.js 立场、支柱、非目标及后续阅读方向；paper-vercel-cost 涵盖 Vercel 计费模型、成本不变量（私有状态不做全局失效、分片列表标签、采样、图片防护）及扩展手册。
  • 优先级 1 数据层（CRITICAL，前缀 data-）：data-caching（Cache Components/PPR、三层页面模型、缓存清单、webhook）、data-auth-routes（BFF 认证、resolveSessionUser、账户 PPR、头部刷新）、data-redirect-security（认证邮件、结账/账户流程的重定向 URL 白名单、Host/Origin 欺骗防护）、data-graphql（两套代码生成设置，结账类型通过 server actions 而非 urql 运行时）、data-storefront-content（与提供商无关的文案层、合并语义、缓存标签、接线）、data-storefront-content-saleor（Saleor Models、slug 栈、渠道覆盖、Configurator）、data-storefront-content-attributes（属性 inputTypes、目录引用、标量路线图）。
  • 优先级 2 商品页（HIGH，前缀 product-）：product-pdp（ProductShell 与动态岛、图库、LCP 预加载、加入购物车）、product-variants（变体选择状态机、控件阶梯、选择索引、部分选择）、product-high-cardinality（上限、购买框策略、?variant=/?sku=、PLP 分面别名 OR）、references/variant-selector-ui.md（边框状态、胶囊/圆形尺寸、渲染器路由）、product-filtering（服务端分类/价格/排序 + PLP_FACETS / ProductWhereInput）。
  • 优先级 3 结账流程（HIGH，前缀 checkout-）：paper-surfaces（两个界面、路由、v2 数据流、会话交接）、checkout-design-principles（基于证据的 UX 原则：访客优先、移动端、定价、快捷支付）、checkout-management（生命周期、RSC 同步、浅步骤、支付过渡 UX）、checkout-payment-gateways（支付应用注册表、提交模式、Stripe Express Checkout 钱包、新增网关）、checkout-components（可复用结账 UI：SignInForm、AddressSelector、账单、集成支付 UI）。
  • 优先级 4 设计与组合（HIGH，前缀 ui-/design-/page-）：ui-design-system（设计入口，令牌词汇：颜色、流体字号、宽度、节奏、圆角、阴影、动效 + cva 变体矩阵）、design-quality-rubric（世界级标准：层级、留白、允许全宽条款、移动端不可妥协项、自检）、ui-sections（营销区块目录：HeroBanner、FeaturedCollection、ImageWithText 等，选择指南、区块编写模式）、page-composition（在 PPR 轨道内塑造 PDP/首页：静态外壳与动态岛）、design-from-image（提示/图片 → 简报 → 令牌 → 区块 → 组合 → 验证）、design-verification（门禁：硬失败令牌 lint、建议性 PPR/LCP/客户端 JS、无障碍通过）。
  • 优先级 5 UI 与渠道（MEDIUM，前缀 ui-）：references/code-conventions.md（kebab-case 文件、PascalCase 导出、@/ 导入）、ui-components（设计令牌、shadcn/ui 原语、组件位置）、ui-images（Saleor 缩略图与 Vercel 优化器、尺寸规范、图片成本预算）、ui-channels（渠道白名单、履约三角、多币种、渠道选择器）、ui-locale-routing（/{locale}/{channel}/ 路由、中间件重定向、路径辅助函数）、ui-i18n（next-intl 命名空间、服务端/客户端模式、ADR 0002 边界）。
  • 优先级 6 SEO（MEDIUM，前缀 seo-）：seo-metadata（JSON-LD 结构化数据、元数据辅助函数、OG 图片生成）。
  • 优先级 7 开发（MEDIUM，前缀 dev-）：dev-local（ngrok/LAN 真机测试、allowedDevOrigins、开发与生产 QA）、dev-investigation（Saleor API 源码调查方法）、third-party-embeds（通过 next/script 引入外部组件脚本如评论、Yotpo，环境变量键、客户端叶子组件）。

使用方式

阅读各规则文件以获取详细说明和代码示例，例如 rules/data-caching.md、rules/product-variants.md。每个规则文件包含：为何重要的简要说明、文件位置与架构图、代码示例（正确与错误模式）、应避免的反模式。

迁移（fork 升级）：为落后于上游 Paper 的 fork 提供按时间顺序的升级提示，不适用于全新项目。任务位置：应用待处理升级见 migrations/SKILL.md，迁移注册表见 migrations/manifest.json，fork 基线见仓库根目录 paper-version.json。触发短语包括 "upgrade Paper"、"apply Paper migrations"、"catch up with upstream caching"、"checkout v2"、"paper-version"。重要迁移：2026-06-checkout-v2 为子系统替换（先采纳再重放，而非增量移植），使用 RSC + server actions，需要 2026-06-account-ppr-auth，详见 migrations/references/checkout-v2-overview.md。

完整编译文档（仅限人工/离线）：AGENTS.md 将所有规则拼接为约 75k token 的单文件，供离线阅读和单文件技能导出。智能体不应加载它，而应阅读 frontmatter 描述与任务匹配的单个 rules/<task>.md。可用 node scripts/compile-agents.mjs 从 rules/ 重新生成编译文档。

适用场景

在以下情况参考这些指南：处理商品详情页（PDP）、变体选择、高基数目录或筛选；修改结账流程或支付集成；编辑 GraphQL 查询或重新生成类型；调试缓存、陈旧内容或重新验证；优化 Vercel 成本、失效范围或流量扩展；编辑营销文案、首页内容或 CONTENT_PROVIDER=saleor；为店铺内容播种或扩展 Saleor Models（Configurator）；在 Cache Components/PPR 下迁移已认证路由（账户、会话 cookie）；升级 fork 的商店；塑造 PDP 或首页布局/设计，或根据提示或参考图片进行设计；使用设计令牌创建 UI 组件；添加区域/渠道路由、市场选择器、next-intl 消息或 i18n URL 结构；添加 SEO 元数据、JSON-LD 或 OG 图片；编写测试或调查 Saleor API 行为；在 pnpm dev 运行时通过 ngrok 或 LAN 在真机上测试。

限制

本技能为项目专属指南，依赖 saleor-storefront 技能提供通用 Saleor API 知识。迁移部分仅适用于落后于上游的 fork，不适用于全新项目。AGENTS.md 编译文档仅供人工离线阅读，智能体不应加载。