用途
在指定日期窗口内查询所有退货请求，并按退货原因代码、商品和 SKU 进行聚合。呈现哪些商品的退货率最高，以及哪些原因（尺码不对、损坏、与描述不符等）最为常见。只读操作，不执行任何变更。
主要能力
- 在时间窗口内查询退货请求，将退货原因、商品、SKU 分桶聚合并计算每个桶的退货数量与占总退货的百分比。
- 同时查询同一时间窗口的订单总数，作为计算退货率的分母。
- 输出按退货原因和按商品两个维度的排名，并生成 CSV 文件。
- 列出退货量最高的商品（含 SKU）。
参数
- store（字符串，必填，无默认值）：商店域名，例如 mystore.myshopify.com。
- days_back（整数，可选，默认 30）：退货请求的回溯窗口。
- min_returns（整数，可选，默认 3）：商品被纳入输出所需的最小退货数。
- format（字符串，可选，默认 human）：输出格式，human 或 json。
前置条件
- 已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_returns
- API 权限范围：read_orders、read_returns
使用方式
该技能基于 GraphQL 操作对 API 版本 2025-01 进行校验。执行流程包括：
- OPERATION: returns — query。输入：query: "created_at:>='<NOW - days_back days>'", first: 250, 分页游标。预期输出：带有 returnLineItems（含 returnReason、refundableQuantity、fulfillmentLineItem.lineItem 下的 product.title 与 variant.sku）的 Return 对象；持续分页直到 hasNextPage: false。
- 按退货原因 → 商品 → SKU 聚合，计算每个桶的退货数量及占总退货的百分比。
- OPERATION: orders — query（用于退货率背景）。输入：同一日期窗口，first: 250；统计订单总数作为退货率计算的分母。
运行期间会输出会话跟踪信息（开始横幅、每步的 [N/TOTAL] 操作与结果、完成汇总）。
完成时，若 format 为 human（默认），输出总退货数、总订单数、退货率、Top Reasons（如 Wrong size/fit、Not as described、Damaged/defective、Changed mind、Other），以及 Top Products by Return Volume，并生成文件 return_reasons_<date>.csv。
若 format 为 json，输出包含 skill、store、period_days、total_returns、total_orders、return_rate_pct、by_reason、by_product、output_file 的 JSON 对象。
输出格式
CSV 文件 return_reasons_<YYYY-MM-DD>.csv，列为：return_id, order_name, product_title, sku, quantity, return_reason, reason_note, created_at。
错误处理
- THROTTLED：API 速率限制超出，等待 2 秒，最多重试 3 次。
- No returns in window：该期间无退货请求，以汇总 0 returns 退出。
- Missing product/variant on line item：商品已删除，记录为 "deleted product"，并计入原因统计。
适用场景与最佳实践
适合用于发现商品质量或商品页面问题：可将高退货商品与其商品描述和图片交叉对照，“与描述不符”的退货往往意味着文案或摄影存在问题。对较大规模的商店，可使用 min_returns: 10 以聚焦具有统计显著性的模式而非一次性投诉。建议每月运行并做同比/环比比较，以跟踪商品运营或质量改进是否降低了特定退货原因。可与 exchange-vs-refund-ratio 配合使用，了解高退货商品是否通过换货挽回了收入。
限制
该技能为只读，不执行任何变更。使用前需完成 Shopify CLI 认证并具备 read_orders、read_returns 权限。其余平台兼容性、收费与价格等信息暂未提供。