ecommerce-platform-specialist

Name: ecommerce-platform-specialist
Author: qodex-ai

github.com/qodex-ai开发47657 次安装42 周前更新

代码仓库

关于 ecommerce-platform-specialist

ecommerce-platform-specialist 是面向 Shopify 开发的技能，依据 Shopify 文档解答实现问题。涵盖应用与主题开发、API、结账和无头电商。

主要功能

01Shopify API 和应用开发指导
02使用 Liquid 开发主题
03定制结账和 Shopify Functions
04Hydrogen 无头电商指导
05认证与 Webhook 实践
06搜索和查阅文档

适用场景

01构建 Shopify 应用和 API 集成
02定制 Liquid 主题与结账流程
03实现认证和 Webhook 处理
04使用 Hydrogen 开发无头电商

安装

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

$npx skills add https://github.com/qodex-ai/ai-agent-skills --skill ecommerce-platform-specialist

安装后在 Claude Code 中输入/ecommerce-platform-specialist确认已加载。

详细介绍

Shopify 开发专家

目的

基于 24+ 份官方文档，为 Shopify 平台开发提供全面、准确的指导。涵盖应用开发、主题自定义、API 集成、结账扩展和电子商务功能的各个方面。

文档覆盖范围

可完整访问官方 Shopify 文档（如有）：

位置： docs/shopify/
文件： 25 个 Markdown 文件
覆盖范围： 完整的 API 参考、指南、最佳实践和实现模式

注意： 需单独拉取文档：

pipx install docpull
docpull https://shopify.dev/docs -o .claude/skills/shopify/docs

主要领域：

GraphQL Admin API（产品、订单、客户、库存）
Storefront API（购物车、结账、客户账户）
REST Admin API（旧版支持）
应用开发（身份验证、webhook、扩展）
主题开发（Liquid、版块、区块）
无头商务（Hydrogen、Oxygen）
结账自定义（UI 扩展、验证）
Shopify Functions（折扣、配送、支付）
POS 扩展（线下销售）
订阅和销售计划
元字段和自定义数据
Shopify Flow 自动化
CLI 和开发工具
隐私与合规
性能优化

何时使用

用户提到以下内容时调用：

平台： Shopify、电子商务、在线商店、商家
API： GraphQL、REST、Storefront API、Admin API
产品： 产品管理、系列、变体、库存
订单： 订单处理、履行、配送
客户： 客户数据、账户、身份验证
结账： 结账自定义、支付方式、配送选项
主题： Liquid 模板、主题开发、版块、区块
应用： 应用开发、扩展、webhook、OAuth
无头： Hydrogen、React、无头商务、Oxygen
Functions： Shopify Functions、自定义逻辑、折扣
订阅： 定期计费、销售计划、订阅
工具： Shopify CLI、开发工作流
POS： 销售点、零售、线下支付

如何使用文档

回答问题时：

搜索特定主题：

# Use Grep to find relevant docs
grep -r "checkout" .claude/skills/shopify/docs/ --include="*.md"

阅读特定文档：

# API docs
cat .claude/skills/shopify/docs/shopify/api-admin-graphql.md
cat .claude/skills/shopify/docs/shopify/api-storefront.md

查找实现指南：

# List all guides
ls .claude/skills/shopify/docs/shopify/

核心身份验证

OAuth 2.0 流程

// Redirect to Shopify OAuth
const authUrl = `https://${shop}/admin/oauth/authorize?` +
  `client_id=${process.env.SHOPIFY_API_KEY}&` +
  `scope=read_products,write_products&` +
  `redirect_uri=${redirectUri}&` +
  `state=${nonce}`;

// Exchange code for access token
const response = await fetch(
  `https://${shop}/admin/oauth/access_token`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.SHOPIFY_API_KEY,
      client_secret: process.env.SHOPIFY_API_SECRET,
      code
    })
  }
);

const { access_token } = await response.json();

会话令牌（现代嵌入式应用）

import { shopifyApi } from '@shopify/shopify-api';

const shopify = shopifyApi({
  apiKey: process.env.SHOPIFY_API_KEY,
  apiSecretKey: process.env.SHOPIFY_API_SECRET,
  scopes: ['read_products', 'write_products'],
  hostName: process.env.HOST,
  isEmbeddedApp: true,
});

GraphQL Admin API

查询产品

query {
  products(first: 10) {
    edges {
      node {
        id
        title
        handle
        priceRange {
          minVariantPrice {
            amount
            currencyCode
          }
        }
        variants(first: 5) {
          edges {
            node {
              id
              sku
              inventoryQuantity
            }
          }
        }
      }
    }
  }
}

创建产品

mutation {
  productCreate(input: {
    title: "New Product"
    vendor: "My Store"
    productType: "Apparel"
    variants: [{
      price: "29.99"
      sku: "PROD-001"
    }]
  }) {
    product {
      id
      title
    }
    userErrors {
      field
      message
    }
  }
}

获取订单

query {
  orders(first: 25, query: "fulfillment_status:unfulfilled") {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          email
        }
        lineItems(first: 10) {
          edges {
            node {
              title
              quantity
            }
          }
        }
      }
    }
  }
}

Storefront API

创建购物车

mutation {
  cartCreate(input: {
    lines: [{
      merchandiseId: "gid://shopify/ProductVariant/123"
      quantity: 1
    }]
  }) {
    cart {
      id
      checkoutUrl
      cost {
        totalAmount {
          amount
          currencyCode
        }
      }
    }
  }
}

更新购物车

mutation {
  cartLinesUpdate(
    cartId: "gid://shopify/Cart/xyz"
    lines: [{
      id: "gid://shopify/CartLine/abc"
      quantity: 2
    }]
  ) {
    cart {
      id
      lines(first: 10) {
        edges {
          node {
            quantity
          }
        }
      }
    }
  }
}

Webhook

设置 Webhook

// Register webhook via API
const webhook = await shopify.webhooks.register({
  topic: 'ORDERS_CREATE',
  address: 'https://your-app.com/webhooks/orders-create',
  format: 'json'
});

验证 Webhook

import crypto from 'crypto';

function verifyWebhook(body, hmacHeader, secret) {
  const hash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('base64');

  return hash === hmacHeader;
}

// In webhook handler
app.post('/webhooks/orders-create', async (req, res) => {
  const hmac = req.headers['x-shopify-hmac-sha256'];
  const body = await req.text();

  if (!verifyWebhook(body, hmac, process.env.SHOPIFY_API_SECRET)) {
    return res.status(401).send('Invalid HMAC');
  }

  const order = JSON.parse(body);
  // Process order...

  res.status(200).send('OK');
});

Liquid 模板

基础 Liquid


{{ product.title }}


{% if product.available %}
  <button>Add to Cart</button>
{% else %}
  <span>Sold Out</span>
{% endif %}


{% for variant in product.variants %}
  <option value="{{ variant.id }}">
    {{ variant.title }} - {{ variant.price | money }}
  </option>
{% endfor %}

自定义版块

{% schema %}
{
  "name": "Featured Product",
  "settings": [
    {
      "type": "product",
      "id": "product",
      "label": "Product"
    }
  ]
}
{% endschema %}

{% if section.settings.product %}
  {% assign product = section.settings.product %}
  <div class="featured-product">
    <img src="{{ product.featured_image | img_url: '500x' }}" alt="{{ product.title }}">
    <h2>{{ product.title }}</h2>
    <p>{{ product.price | money }}</p>
  </div>
{% endif %}

Shopify Functions

折扣函数

// Function to apply volume discount
export default (input) => {
  const quantity = input.cart.lines.reduce((sum, line) => sum + line.quantity, 0);

  let discountPercentage = 0;
  if (quantity >= 10) discountPercentage = 20;
  else if (quantity >= 5) discountPercentage = 10;

  if (discountPercentage > 0) {
    return {
      discounts: [{
        message: `${discountPercentage}% volume discount`,
        targets: [{
          orderSubtotal: {
            excludedVariantIds: []
          }
        }],
        value: {
          percentage: {
            value: discountPercentage.toString()
          }
        }
      }]
    };
  }

  return { discounts: [] };
};

配送自定义

// Hide specific delivery options
export default (input) => {
  const operations = [];

  // Hide express shipping for orders under $100
  const cartTotal = parseFloat(input.cart.cost.subtotalAmount.amount);

  if (cartTotal < 100) {
    const expressOptions = input.cart.deliveryGroups[0].deliveryOptions
      .filter(option => option.title.toLowerCase().includes('express'));

    expressOptions.forEach(option => {
      operations.push({
        hide: {
          deliveryOptionHandle: option.handle
        }
      });
    });
  }

  return { operations };
};

Hydrogen（无头商务）

产品页面

// app/routes/products.$handle.tsx
import {json, LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData} from '@remix-run/react';

export async function loader({params, context}: LoaderFunctionArgs) {
  const {product} = await context.storefront.query(PRODUCT_QUERY, {
    variables: {handle: params.handle},
  });

  return json({product});
}

export default function Product() {
  const {product} = useLoaderData<typeof loader>();

  return (
    <div>
      <h1>{product.title}</h1>
      <img src={product.featuredImage.url} alt={product.title} />
      <p>{product.description}</p>
      <AddToCartButton productId={product.id} />
    </div>
  );
}

const PRODUCT_QUERY = `#graphql
  query Product($handle: String!) {
    product(handle: $handle) {
      id
      title
      description
      featuredImage {
        url
        altText
      }
      variants(first: 10) {
        nodes {
          id
          price {
            amount
            currencyCode
          }
        }
      }
    }
  }
`;

Shopify CLI

常用命令

# Create new app
shopify app init

# Start development server
shopify app dev

# Deploy app
shopify app deploy

# Create extension
shopify app generate extension

# Create theme
shopify theme init

# Serve theme locally
shopify theme dev --store=your-store.myshopify.com

# Push theme
shopify theme push

# Pull theme
shopify theme pull

测试

测试商店

创建 Partner 账户：https://partners.shopify.com
创建开发商店
安装你的应用
测试功能

测试数据

// Create test product
const product = await shopify.rest.Product.save({
  session,
  title: "Test Product",
  body_html: "<strong>Test description</strong>",
  vendor: "Test Vendor",
  product_type: "Test Type",
  variants: [{
    price: "19.99",
    sku: "TEST-001"
  }]
});

// Create test order
const order = await shopify.rest.Order.save({
  session,
  line_items: [{
    variant_id: 123456789,
    quantity: 1
  }],
  customer: {
    email: "[email protected]"
  }
});

安全最佳实践

API 密钥：
- 存储在环境变量中
- 切勿提交到版本控制系统
- 为每个环境使用单独的密钥
- 如果密钥泄露，请轮换密钥
Webhook：
- 始终验证 HMAC 签名
- 仅使用 HTTPS 端点
- 立即返回 200
- 异步处理
访问范围：
- 仅申请所需的最小范围
- 说明申请每个范围的原因
- 定期检查
速率限制：
- 遵守 API 速率限制
- 实施指数退避
- 监控 API 使用情况

常见错误

API 身份验证

Invalid access token - 检查令牌是否有效且具有正确的访问范围
Shop not found - 验证商店域名格式
Missing access token - 添加 X-Shopify-Access-Token 标头

GraphQL 错误

User errors - 检查响应中的 userErrors 字段
Throttled - 降低请求速率
Field not found - 确认 API 版本支持该字段

Webhook 问题

Invalid HMAC - 检查 webhook 密钥和验证逻辑
Delivery failed - 确保端点在超时时间内返回 200
Not receiving webhooks - 检查 webhook 注册情况和端点 URL

资源

控制面板： https://partners.shopify.com
文档： https://shopify.dev
GraphiQL Admin： https://shopify.dev/docs/apps/tools/graphiql-admin-api
社区： https://community.shopify.com
状态： https://www.shopifystatus.com

文档快速参考

需要查找特定内容？

# Search all docs
grep -r "search term" .claude/skills/shopify/docs/

# Find specific topics
ls .claude/skills/shopify/docs/shopify/

# Read specific guide
cat .claude/skills/shopify/docs/shopify/webhooks.md

常见文档文件：

api-admin-graphql.md - GraphQL Admin API
api-storefront.md - Storefront API
authentication.md - OAuth 和身份验证流程
webhooks.md - Webhook 处理
apps.md - 应用开发
themes.md - 主题开发
liquid.md - Liquid 参考
hydrogen.md - 无头商务
checkout.md - 结账定制
functions.md - Shopify Functions
cli.md - CLI 命令

支持 Markdown

登录后评论

基本信息

作者: qodex-ai
仓库: qodex-ai/ai-agent-skills
分类: 开发
安装次数: 657
GitHub Stars: 47

报告问题