shopify-admin-refund-rate-analysis

用途

该技能用于分析带有退款的订单，按商品、时间段和渠道计算退款率，揭示哪些商品或商品组产生了最多的退款活动。它是只读的，不会执行任何变更操作。

主要能力

按商品、供应商（vendor）或时间段（period）对退款数据进行分组统计。
计算退款率：refund_rate = refunded_units / total_units_sold × 100。
输出整体退款率、退款订单数、退款总额等汇总信息。
生成 CSV 文件，包含分组、分组名称、总售出件数、退款件数、退款率、退款总额、货币等列。
支持 human（默认）和 json 两种输出格式。

使用方式

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	30	回溯窗口
group_by	string	否	product	分组方式：product、vendor 或 period
min_orders	integer	否	5	纳入退款率计算的最小订单数
format	string	否	human	输出格式：human 或 json

工作流程

查询订单：使用查询条件 created_at:>='<NOW - days_back days>'，每次取 250 条，选择 refunds { refundLineItems }、lineItems，并使用分页游标，直到 hasNextPage: false。
对每个退款行项目记录：商品、供应商、退款数量、退款金额。
按 group_by 聚合，计算退款率。

GraphQL 操作

# orders:query — validated against api_version 2025-01
query OrdersWithRefunds($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        lineItems(first: 50) {
          edges {
            node {
              id
              quantity
              product {
                id
                title
                vendor
              }
              variant {
                id
                sku
              }
            }
          }
        }
        refunds {
          id
          createdAt
          totalRefundedSet {
            shopMoney {
              amount
              currencyCode
            }
          }
          refundLineItems(first: 50) {
            edges {
              node {
                quantity
                lineItem {
                  product {
                    id
                    title
                    vendor
                  }
                  variant {
                    id
                    sku
                  }
                }
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

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

开始时输出：

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

══════════════════════════════════════════════
REFUND RATE ANALYSIS  (<days_back> days)
  Orders analyzed:       <n>
  Orders with refunds:   <n>
  Overall refund rate:   <pct>%
  Total refunded:        $<amount>

  By <group_by>:
    "<name>"   Sold: <n>  Refunded: <n>  Rate: <pct>%
  Output: refund_rate_<date>.csv
══════════════════════════════════════════════

format 为 json 时输出：

{
  "skill": "refund-rate-analysis",
  "store": "<domain>",
  "period_days": 30,
  "orders_analyzed": 0,
  "orders_with_refunds": 0,
  "overall_refund_rate_pct": 0,
  "total_refunded": 0,
  "currency": "USD",
  "output_file": "refund_rate_<date>.csv"
}

输出格式

CSV 文件 refund_rate_<YYYY-MM-DD>.csv，列包括： group, group_name, total_units_sold, refunded_units, refund_rate_pct, total_refund_amount, currency

适用场景

识别退款率异常偏高的商品或商品组。
按供应商分组，判断质量问题是否集中在某个供应商。
在季度供应商评审前运行，为关于商品质量和退单的数据驱动讨论提供支持。
与 return-reason-analysis 交叉参考，判断问题属于商品质量、尺码错误还是客户预期不符。

限制与安全

只读技能，不执行任何变更操作，可随时安全运行。
需要已认证的 Shopify CLI 会话和 read_orders 权限。
错误处理：
- THROTTLED（API 速率限制）：等待 2 秒，最多重试 3 次。
- 窗口内无退款：正常情况，以 0% 退款率退出。
- 退款行项目上的商品已删除：在分组中记录为 "deleted product"。

最佳实践

特定商品退款率高于 5–10% 通常意味着商品详情页、质量或预期不符问题。
使用 group_by: vendor 识别质量问题是否集中在特定供应商。
与 return-reason-analysis 交叉参考，理解问题根源。
在季度供应商评审前运行，支持数据驱动的对话。