用途
该技能计算一个周期内所有已完成退货从退货请求创建到退款发放之间的时间。它会给出平均处理时长，识别超出可配置 SLA 阈值的订单，并列出等待最久的未退款退货。整个过程为只读，不执行任何变更操作。
主要能力
- 计算已完成退货的处理天数（processing_days = refund.createdAt - return.createdAt）。
- 统计平均处理时间、SLA 内完成数量与比例、SLA 违约数量与比例。
- 列出超过 SLA 仍未退款的未结退货订单。
- 输出 CSV 文件 return_sla_<YYYY-MM-DD>.csv，包含列：return_id, order_name, return_requested_at, refunded_at, processing_days, sla_breach, return_status。
- 支持 human（默认）与 json 两种输出格式。
使用方式
前置条件：已认证的 Shopify CLI 会话，命令为 shopify store auth --store <domain> --scopes read_orders,read_returns；API 权限范围为 read_orders、read_returns。
参数：
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
- days_back（整数，可选，默认 30）：退货请求的回溯窗口。
- sla_days（整数，可选，默认 5）：从请求到退款可接受的最大天数。
- format（字符串，可选，默认 human）：输出格式，human 或 json。
工作流程：
- 查询 returns，条件为 created_at:>='<NOW - days_back days>'，每页 250 条，使用分页游标。返回字段包括 createdAt、status、refunds { createdAt }、order { name }。
- 对每个已完成退货计算 processing_days。
- 识别 SLA 违约：processing_days > sla_days。
- 查询 orders，筛选 return_status:open 以找出超过 SLA 的未结退货。
GraphQL 操作已针对 api_version 2025-01 验证，包含 returns:query 与 orders:query 两个查询。
运行时会输出会话跟踪信息：开始时输出技能名称、店铺域名与启动时间；每步输出 [N/TOTAL] 操作名、参数摘要与结果；完成时按所选格式输出汇总。human 格式输出分析退货数、平均处理时间、SLA 内数量与比例、SLA 违约数量与比例、未结退货数、等待最久的未退款退货列表以及输出文件名。json 格式输出 skill、store、period_days、sla_days、returns_analyzed、avg_processing_days、within_sla_count、sla_breach_count、open_pending_count、output_file 等字段。
适用场景
- 将 sla_days 设置为与已公布的退货政策一致（例如“退款在 5 个工作日内处理”）。
- 利用未结退货列表主动联系等待超过 sla_days 的客户，减少“我的退款在哪里”类工单。
- 每周作为退货运营健康检查运行，可与 return-reason-analysis 配合，将慢处理与特定退货原因类型关联。
限制
- 只读技能，不执行任何变更操作。
- processing_days 按自然日计算；如果团队仅在工作日处理退货，需相应调整 SLA 阈值。
- 错误处理：THROTTLED（API 速率限制）时等待 2 秒并最多重试 3 次；已完成退货无退款（仅换货解决）时从时间计算中排除并标记为 exchange；窗口内无退货时以 0 条退货的汇总退出。