shopify-admin-partial-refund-pattern-detector

用途

扫描近期订单，提取每一笔退款，标记满足以下任一条件的订单：(a) 存在两笔或以上部分退款，或 (b) 部分退款占订单总额的比例超过可配置阈值。这些模式通常暗示友好欺诈（分次索赔）、不满的回头客模式，或员工工作流程缺口（零散退款而非一次性全额退款）。只读——不执行任何变更。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	90	分析订单的回溯窗口
min_partials	integer	否	2	标记订单所需的最少部分退款笔数
ratio_threshold	float	否	0.5	当总退款额 / 订单总额超过此比例时标记（仍为部分退款，即低于 1.0）
min_order_value	float	否	25	跳过低于此金额的低价值订单
format	string	否	human	输出格式：human 或 json

安全性

ℹ️ 只读技能——不执行任何变更，可随时安全运行。被标记的订单仅为提示——在对客户账户采取行动前，请结合退款备注与客户历史进行确认。

工作流程

操作：orders — 查询
- 输入：query: "created_at:>='<NOW - days_back days>' financial_status:partially_refunded"，first: 250，select refunds { id, createdAt, totalRefundedSet, note }, totalPriceSet, customer, 分页游标
- 预期输出：所有部分退款订单及其完整退款历史；分页直到 hasNextPage: false
对每个订单，统计退款笔数并汇总 totalRefundedSet.shopMoney.amount。计算比例 = 总退款额 / 订单总额。
标记满足任一条件的订单：refund_count >= min_partials 或 ratio >= ratio_threshold（且 ratio < 1.0，以排除已全额退款的订单）。
按 customer.id 对被标记订单分组，以发现重复出现的客户（窗口内有多于一个被标记订单）。

GraphQL 操作

# orders:query — validated against api_version 2025-01
query PartialRefundPatterns($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFinancialStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        totalRefundedSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        refunds {
          id
          createdAt
          note
          totalRefundedSet {
            shopMoney {
              amount
              currencyCode
            }
          }
          refundLineItems(first: 50) {
            edges {
              node {
                quantity
                lineItem {
                  id
                  title
                  sku
                }
              }
            }
          }
        }
        customer {
          id
          displayName
          defaultEmailAddress {
            emailAddress
          }
          numberOfOrders
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Partial Refund Pattern 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（默认）：

══════════════════════════════════════════════
PARTIAL REFUND PATTERN REPORT  (<days_back> days)
  Partially refunded orders:   <n>
  Flagged (multi-refund):      <n>
  Flagged (high ratio):        <n>
  Repeat-flagged customers:    <n>

  Top flagged customers by amount:
    <customer>  Orders: <n>  Refunded: $<n>  Ratio: <pct>%
  Output: partial_refund_patterns_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "partial-refund-pattern-detector",
  "store": "<domain>",
  "period_days": 90,
  "partially_refunded_orders": 0,
  "flagged_multi_refund": 0,
  "flagged_high_ratio": 0,
  "repeat_flagged_customers": 0,
  "output_file": "partial_refund_patterns_<date>.csv"
}

输出格式

CSV 文件 partial_refund_patterns_<YYYY-MM-DD>.csv，包含列：

order_name, order_id, customer_email, customer_lifetime_orders, order_total, total_refunded, refund_ratio, refund_count, flag_reason, first_refund_at, last_refund_at

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
订单有退款但 totalRefundedSet 为零	退款记录为 $0（仅备注，无资金流动）	从比例计算中跳过，仍计入退款笔数
客户为 null（访客订单）	未关联客户	改为按邮箱分组
无部分退款订单	窗口干净	以摘要退出：0 个被标记

最佳实践

组合使用 min_partials: 2 与 ratio_threshold: 0.5 可获得最有用的信号——单笔小额部分退款通常是合法的。
按 refund_ratio 降序排序：高价值订单上的高比例是最强的欺诈信号。
重复被标记且 numberOfOrders > 5 的客户往往是长期投诉者，而非欺诈者——采取行动前请查看退款备注。
每季度将此技能与 order-risk-report 配合使用，以发现结账时欺诈过滤器遗漏的购后欺诈。
退款备注内容常能揭示模式（例如重复出现三次“商品缺失”）——在标记客户前请阅读备注。