shopify-admin-duplicate-sku-barcode-detector

用途

扫描所有产品变体，识别重复的 SKU 或条形码——即两个或多个变体共用同一标识符的情况。重复 SKU 会导致库存同步失败、订单路由错误和账务不匹配。本技能为只读操作，不执行任何变更。

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products
API 权限范围：read_products

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
check_skus	bool	否	true	是否检查重复 SKU
check_barcodes	bool	否	true	是否检查重复条形码
include_blank	bool	否	false	是否标记 SKU 为空白/null 的变体
format	string	否	human	输出格式：human 或 json

安全性

ℹ️ 只读技能——不执行任何变更操作，可随时安全运行。

工作流程

操作：productVariants — 查询
- 输入：first: 250，选择 sku、barcode、product { title }，分页游标
- 预期输出：所有变体的 SKU 和条形码值；持续分页直到 hasNextPage: false
在内存中构建 sku → [变体] 和 barcode → [变体] 的映射
报告所有对应多个变体的键（重复项）
若 include_blank 为真：额外标记 sku 为 null 或空字符串的变体

GraphQL 操作

# productVariants:query — 已针对 api_version 2025-01 验证
query VariantIdentifiers($after: String) {
  productVariants(first: 250, after: $after) {
    edges {
      node {
        id
        sku
        barcode
        title
        product {
          id
          title
          handle
          status
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，此为强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Duplicate SKU/Barcode Detector       ║
║  Store: <store domain>                       ║
║  Started: <YYYY-MM-DD HH:MM UTC>             ║
╚══════════════════════════════════════════════╝

每步之后输出：

[N/TOTAL] <QUERY|MUTATION>  <OperationName>
          → Params: <brief summary of key inputs>
          → Result: <count or outcome>

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
DUPLICATE SKU / BARCODE REPORT
  Variants scanned:      <n>
  Duplicate SKUs found:  <n> groups
  Duplicate barcodes:    <n> groups
  Blank SKUs:            <n>

  Duplicate SKU groups:
    SKU "ABC-123"  — used by 2 variants:
      Product A / Blue / L
      Product B / Navy / XL
  Output: duplicates_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "duplicate-sku-barcode-detector",
  "store": "<domain>",
  "variants_scanned": 0,
  "duplicate_sku_groups": 0,
  "duplicate_barcode_groups": 0,
  "blank_skus": 0,
  "output_file": "duplicates_<date>.csv"
}

输出格式

CSV 文件 duplicates_<YYYY-MM-DD>.csv，包含列： issue_type, duplicate_value, variant_id, product_title, variant_title, sku, barcode

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
No duplicates found	目录干净	以 ✅ 无问题退出

最佳实践

每次批量导入产品后运行此技能——导入是重复 SKU 最常见的来源。
跨产品共用 SKU 仅在有意为再版或变体使用相同 SKU 时才有效——大多数情况属于数据错误。
空白 SKU 不算重复，但可能导致需要每个变体都有 SKU 的 3PL 和履约系统出现问题——使用 include_blank: true 将其暴露出来。
识别重复项后，使用 Shopify 管理界面或 productVariantsBulkUpdate 变更来修正 SKU 值。