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 Admin 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>

完成时输出：

对于 format: 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
══════════════════════════════════════════════

对于 format: 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 和营销分群影响最大。
重复项的常见原因：访客结账后又创建账户、手动导入客户，或客户使用多个邮箱地址。