用途
该技能用于分析 Shopify 店铺的退货处理结果，计算退货中换货（收入保留）、店铺积分（收入递延）与退款（收入损失）之间的比例，并将其作为收入挽回指标随时间进行跟踪。该技能为只读操作，不会执行任何数据变更。
主要能力
- 查询指定回溯窗口内的退货记录，读取退货状态、换货行项目、退款金额及退货行项目等信息。
- 将每条退货处理结果归类：
- 换货：退货包含数量大于 0 的 exchangeLineItems。
- 店铺积分：退货包含以礼品卡或店铺积分方式支付的退款。
- 退款：退货包含现金/银行卡退款且没有换货。
- 计算收入挽回率（换货 + 店铺积分占全部退货的百分比）。
- 可选对比前期数据，用于计算趋势。
- 输出 human 或 json 格式的结果，并生成 CSV 文件。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：
shopify store auth --store <domain> --scopes read_orders,read_returns - API 权限范围：read_orders、read_returns
参数：
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
- days_back（整数，可选，默认 30）：退货处理结果的回溯窗口。
- compare_days_back（整数，可选，默认 0）：可选的对比前期（0 表示不对比）。
- format（字符串，可选，默认 human）：输出格式，human 或 json。
工作流程：
- 执行 returns 查询，输入查询条件
created_at:>='<NOW - days_back days>'，first: 250，使用分页游标。预期输出包含退款（totalRefundedSet）、exchangeLineItems 及处理状态的退货记录。 - 对每条退货处理结果进行分类（换货、店铺积分、退款）。
- 若 compare_days_back > 0，则对前期执行 orders 查询，使用相同逻辑计算趋势。
GraphQL 操作（已针对 api_version 2025-01 验证）：
returns:query：
query ReturnResolutions($query: String!, $after: String) {
returns(first: 250, after: $after, query: $query) {
edges {
node {
id
status
createdAt
totalQuantity
order {
id
name
}
exchangeLineItems(first: 10) {
edges {
node {
id
quantity
lineItem {
variant {
id
title
}
}
}
}
}
refunds(first: 5) {
id
totalRefundedSet {
shopMoney {
amount
currencyCode
}
}
}
returnLineItems(first: 20) {
edges {
node {
refundableQuantity
returnReason
}
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
orders:query：
query OrdersInPeriod($query: String!, $after: String) {
orders(first: 250, after: $after, query: $query) {
edges {
node {
id
name
totalPriceSet {
shopMoney {
amount
currencyCode
}
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
会话跟踪：
Claude 必须在每个阶段输出以下内容（强制要求）。
开始时输出：
╔══════════════════════════════════════════════╗
║ SKILL: Exchange vs Refund Ratio ║
║ 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（默认）时：
══════════════════════════════════════════════
EXCHANGE vs REFUND RATIO (<days_back> days)
Total returns resolved: <n>
Resolution breakdown:
Exchange (revenue kept): <n> (<pct>%)
Store credit (deferred): <n> (<pct>%)
Refund (revenue lost): <n> (<pct>%)
Revenue recovery rate: <pct>%
(exchanges + store credit as % of all returns)
Output: exchange_refund_ratio_<date>.csv
══════════════════════════════════════════════
format 为 json 时：
{
"skill": "exchange-vs-refund-ratio",
"store": "<domain>",
"period_days": 30,
"total_returns": 0,
"exchanges": { "count": 0, "pct": 0 },
"store_credit": { "count": 0, "pct": 0 },
"refunds": { "count": 0, "pct": 0 },
"revenue_recovery_rate_pct": 0,
"output_file": "exchange_refund_ratio_<date>.csv"
}
输出格式：
生成 CSV 文件 exchange_refund_ratio_<YYYY-MM-DD>.csv，列包括：return_id, order_name, resolution_type, exchange_sku, refund_amount, currency, created_at。
错误处理：
- THROTTLED：API 速率限制超出。等待 2 秒，最多重试 3 次。
- No resolved returns in window：该期间没有已完成的退货。以摘要退出：0 条退货。
- Exchange line items empty but status indicates exchange：换货进行中。计为待处理，从比例中排除。
适用场景
- 衡量店铺的退货收入挽回情况，跟踪换货与退款比例随时间的变化。
- 使用 compare_days_back 跟踪退货政策变化（例如“仅换货”时期）是否提升了挽回率。
- 与 return-reason-analysis 配合使用：高“尺码错误”退货原因搭配低换货率，可能表明商品列表中的尺码指引存在问题。
- 在推出换货激励（例如换货而非退款可获额外店铺积分）前后运行，以衡量影响。
限制
- 该技能为只读，不执行任何变更，可随时安全运行。
- 需要已认证的 Shopify CLI 会话及 read_orders、read_returns 权限。
- 收入挽回率高于 30%（换货 + 店铺积分）通常对时尚/服装类是一个强信号；应根据自身品类设定基准。
- 换货进行中（exchangeLineItems 为空但状态指示换货）的记录计为待处理，不计入比例。