用途：在开发 Spree 6 可选 Next.js 商店前端（apps/storefront/，github.com/spree/storefront）时使用。该前端通过 @spree/sdk 2.x 调用 v3 Store API（/api/v3/store/*），技术栈为 Next.js 16、React 19、Tailwind 4；商店前端是可选的，任何前端都可用同一 Store API。
主要能力与架构：采用服务端优先模式，浏览器→Server Action（src/lib/data/*）→@spree/sdk→Store API，JWT、刷新令牌、购物车令牌、国家/语言等放在 httpOnly cookie 中，浏览器不直接调用 Spree，发布密钥仅服务端使用（SPREE_PUBLISHABLE_KEY，不加 NEXT_PUBLIC_）。src/lib/spree/ 提供 getClient()、cookie 助手、withAuthRefresh()、getLocaleOptions()、getCartOptions()、中间件、渠道面与 webhook。
用法要点：必填环境变量 SPREE_API_URL、SPREE_PUBLISHABLE_KEY；可选含默认国家/语言、站点 URL、批发渠道与密钥、webhook 密钥、Resend 邮件配置。SDK 支持 products.list/get、carts.create、carts.items.create、customer.orders.list 等；响应为扁平结构，价格用 Price 对象（如 product.price.display_amount），不在客户端计算金额。认证分发布密钥、spreeToken 访客购物车、JWT 客户三种模式。
购物车到订单：Spree 6 将可变 Cart（cart_）与完成后生成的不可变 Order（or_）分开，无结账状态机；通过 cart.requirements[]（含 step、field、code、message）驱动 UI，完成是唯一硬门槛。配送用 fulfillments.update，支付会话用 paymentSessions.create/complete，非会话方式用 payments.create，最后 carts.complete 返回 Order 或 OrderGroup，且幂等。完成后改用 orders.get。
多区域与批发：路由位于 src/app/[country]/[locale]/…，由 src/proxy.ts 的 createSpreeMiddleware 处理重定向、国家/语言检测与 cookie 同步。批发门户仅在设置 SPREE_WHOLESALE_CHANNEL 时启用，按渠道绑定客户端与购物车 cookie。
Webhook 与邮件：src/app/api/webhooks/spree/route.ts 用 createWebhookHandler 校验 X-Spree-Webhook-Signature 并按事件分发；事件名用 order.placed、order.fulfilled 等新名，旧别名将在 6.1 停止。若前端负责客户邮件，需关闭后端 send_consumer_transactional_emails。
测试与限制：单元/集成用 Vitest（pnpm test），E2E 用 Playwright 配合 Docker 后端（pnpm e2e:up、pnpm test:e2e、pnpm e2e:down）。限制：密钥 sk_ 不得放入前端；购物车令牌须存 httpOnly cookie；只缓存目录，不缓存购物车/结账；不要假设结账步骤顺序；本地化由请求头驱动而非 Accept-Language。资料未提供收费、价格与效果信息。