shopify-admin-return-fraud-detector

用途

该技能用于发现退货行为在统计上偏离店铺基线的客户，让客服和运营团队在批准下一次退货前进行人工复核。它检测三种模式：

高退货率：退货订单占比达到或超过设定阈值（默认 40%）。
Wardrobing：收货后短时间内发起整单退货（默认窗口 14 天）。
连续退货者：长期累计退货次数达到阈值（默认 5 次）。

该技能为只读操作，输出的是候选名单，而非自动封禁名单。

前置条件

已认证的 Shopify CLI 会话： shopify store auth --store <domain> --scopes read_orders,read_returns,read_customers
API 权限范围：read_orders、read_returns、read_customers

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
days_back	integer	否	365	订单和退货的回溯窗口
min_orders	integer	否	3	客户被评估所需的最低历史订单数（避免因一次性意外而误判）
return_rate_threshold	float	否	0.40	标记为高退货率的退货订单占比（默认 40%）
wardrobing_window_days	integer	否	14	从妥投到发起退货之间的窗口，用于标记 wardrobing
serial_threshold	integer	否	5	标记为连续退货者所需的最低总退货次数

安全说明

该技能为只读，不执行任何变更操作。输出仅标记候选客户供人工复核，绝不自动封禁或限制客户。误报很常见（如真实的尺码问题、地址更正退货等），采取行动前应先调查。

工作流程

查询订单：按 created_at 过滤回溯窗口内的订单，分页获取，按 customer.id 分组。
查询退货：使用相同日期过滤，关联到客户。
查询客户：仅针对被标记的候选客户，获取身份字段和标签。

对每个客户计算：total_orders、total_returns、return_rate、wardrobing_count（在 wardrobing 窗口内妥投后退货，且退货数量总和 ≥ 订单数量总和）。标记规则：

high_return_rate：订单数 ≥ min_orders 且退货率 ≥ return_rate_threshold
wardrobing：次数 ≥ 2
serial_returner：退货数 ≥ serial_threshold

GraphQL 操作

订单查询（针对 api_version 2025-01 验证）：

query OrdersForReturnFraud($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        processedAt
        displayFulfillmentStatus
        totalPriceSet { shopMoney { amount currencyCode } }
        customer { id }
        lineItems(first: 50) {
          edges { node { id quantity } }
        }
        fulfillments {
          deliveredAt
          status
          displayStatus
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

退货查询（针对 api_version 2025-01 验证）：

query ReturnsForFraud($query: String!, $after: String) {
  returns(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        status
        createdAt
        totalQuantity
        order { id name customer { id } }
        returnLineItems(first: 50) {
          edges { node { id quantity returnReason } }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

客户查询（针对 api_version 2025-01 验证）：

query CustomerContactBatch($query: String!) {
  customers(first: 250, query: $query) {
    edges {
      node {
        id
        displayName
        firstName
        lastName
        defaultEmailAddress { emailAddress }
        phone
        numberOfOrders
        amountSpent { amount currencyCode }
        tags
      }
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Return Fraud 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（默认）时：

══════════════════════════════════════════════
RETURN FRAUD CANDIDATES  (<days_back> days)
  Customers evaluated:      <n>
  Flagged candidates:       <n>

  By rule:
    High return rate (≥<pct>%):  <n>
    Wardrobing pattern:           <n>
    Serial returner (≥<n>):       <n>

  Top suspects (by composite risk):
    <name>  <email>  Orders: <n>  Returns: <n>  Rate: <pct>%  Flags: <list>
  Output: return_fraud_candidates_<date>.csv
══════════════════════════════════════════════

format 为 json 时：

{
  "skill": "return-fraud-detector",
  "store": "<domain>",
  "period_days": 365,
  "customers_evaluated": 0,
  "flagged_candidates": 0,
  "by_rule": {
    "high_return_rate": 0,
    "wardrobing": 0,
    "serial_returner": 0
  },
  "output_file": "return_fraud_candidates_<date>.csv"
}

输出格式

CSV 文件 return_fraud_candidates_<YYYY-MM-DD>.csv，包含列： customer_id, name, email, phone, total_orders, total_returns, return_rate_pct, wardrobing_count, flags, lifetime_spend, last_return_date, tags

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
订单上 Customer 为 null	访客结账	跳过——无法将多个订单关联到访客
退货缺少 order.customer	已匿名化或已删除	跳过该退货
deliveredAt 缺失	订单尚未妥投	跳过该订单的 wardrobing 标记

最佳实践

将输出视为复核队列，绝不自动执行操作——在打标签或限制任何账户前先人工验证。
根据品类基线调整 return_rate_threshold。服装店退货率通常在 20–30%，在 40% 标记可挑出异常值。对于电子产品或家居用品，可降至 15–20%。
与 return-reason-analysis 交叉参考——如果退货集中在某一产品，问题可能是产品质量而非滥用。
结合 duplicate-customer-finder 的客户合并候选——欺诈者常创建重复账户以规避退货率标记。
每季度运行一次并使用 12 个月窗口以获得稳定信号；每月运行会因新客户仅一次退货而产生噪声标记。