shopify-admin-duplicate-customer-finder

用途

扫描客户数据库，使用邮箱、电话和姓名匹配查找疑似重复记录。重复的客户记录会导致订单历史分散、LTV 计算不正确以及营销分群不正确。本技能为只读模式，不执行任何数据变更。

前置条件

已认证的 Shopify CLI 会话：

shopify store auth --store <domain> --scopes read_customers

API 权限范围：read_customers

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
match_on	string	否	email	匹配策略：email、phone、name 或 all
min_orders	integer	否	0	仅标记至少一条记录达到此订单数的重复项
format	string	否	human	输出格式：human 或 json

安全性

ℹ️ 只读技能——不执行任何变更操作，可随时安全运行。Shopify 管理 API 不支持重复客户合并——被标记的重复项必须在 Shopify 管理后台手动合并。

工作流程

OPERATION: customers — 查询输入：first: 250，选择 email、phone、firstName、lastName、numberOfOrders、totalSpentV2、分页游标预期输出：包含联系方式和订单数据的所有客户；持续分页直到 hasNextPage: false

构建内存查找映射：

email → [customer_ids]
phone → [customer_ids]（若 match_on 包含 phone）
"firstName lastName" → [customer_ids]（若 match_on 包含 name）

将每个键下超过 1 个客户的组报告为疑似重复项。

GraphQL 操作

# customers:query — 已针对 api_version 2025-01 验证
query CustomersForDeduplication($after: String) {
  customers(first: 250, after: $after) {
    edges {
      node {
        id
        displayName
        firstName
        lastName
        defaultEmailAddress {
          emailAddress
        }
        phone
        numberOfOrders
        amountSpent {
          amount
          currencyCode
        }
        createdAt
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话追踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Duplicate Customer Finder            ║
║  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>

完成时输出：

格式为 human（默认）时：

══════════════════════════════════════════════
DUPLICATE CUSTOMER REPORT
  Customers scanned:       <n>
  Duplicate groups found:  <n>
  Customers affected:      <n>

  Duplicate groups (sample):
    Email: user@example.com
      Customer A — <n> orders, $<n> spent, created <date>
      Customer B — <n> orders, $<n> spent, created <date>
  Output: duplicate_customers_<date>.csv
══════════════════════════════════════════════

格式为 json 时输出：

{
  "skill": "duplicate-customer-finder",
  "store": "<domain>",
  "customers_scanned": 0,
  "duplicate_groups": 0,
  "customers_affected": 0,
  "output_file": "duplicate_customers_<date>.csv"
}

输出格式

CSV 文件 duplicate_customers_<YYYY-MM-DD>.csv，包含列： duplicate_group_id, match_key, match_type, customer_id, name, email, phone, number_of_orders, total_spent, created_at

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
No duplicates found	客户数据库干净	以 ✅ 未发现重复项退出

最佳实践

Shopify 不提供原生合并 API——被标记的重复项必须在 Shopify 管理后台手动解决（Customers → Merge）。
match_on: email 能找到最可靠的重复项；match_on: name 会产生更多误报（常见姓名）。
优先处理至少有一条记录已有订单的重复项——这些对 LTV 和营销分群影响最大。
重复项的常见原因：访客结账后又创建账户、手动导入客户，或客户使用多个邮箱地址。

适用场景

适合需要清理 Shopify 客户数据、排查重复客户记录、修复 LTV 计算和营销分群问题的运营与数据人员。需要在已认证的 Shopify CLI 环境中运行，并要求 read_customers 权限。

限制

只读技能，不执行任何数据变更。
不支持通过 Shopify 管理 API 自动合并重复客户，需在管理后台手动合并。
使用姓名匹配时可能产生误报。