用途
该技能用于量化一个时间窗口内退货的完整成本，而不仅仅是退款金额。它将退款总额、丢失的运费收入、不可重新入库商品（如 DEFECTIVE）的 COGS、以及重新入库人工成本合并为按原因和按产品的退货损益。该技能为只读操作，不会执行任何数据变更。可用于确定哪些退货原因或产品线最值得进行运营修复，例如改进包装、尺码指南或商品描述准确性。
主要能力
- 按指定回溯窗口（默认 90 天）查询退货记录，包含行项目定价、产品/变体、库存项目 ID。
- 查询相关订单的退款信息，将退款金额映射到行项目。
- 批量查询库存项目的单位成本（unitCost）。
- 按行项目计算：退款金额（按退货数量比例匹配退款行项目）、运费损失（整单退货时按行项目价值占比分摊订单运费，否则为 0）、COGS 冲销（仅当退货原因在 writeoff_reasons 中时，按 unitCost × 数量计算）、重新入库人工（flat_restocking_cost × 数量）。
- 按 group_by 参数聚合汇总，支持 reason、product、sku 或 reason_x_product。
- 输出 CSV 文件，包含分组键、退货次数、数量、退款金额、运费损失、COGS 冲销、重新入库人工、总成本、平均每次退货成本、主要退货原因、货币。
使用方式
前置条件：需要 Shopify 店铺认证，命令为 shopify store auth --store <domain> --scopes read_orders,read_returns,read_inventory。API 权限范围：read_orders、read_returns、read_inventory。
参数：
- store（字符串，必填）：店铺域名，例如 mystore.myshopify.com。
- format（字符串，可选，默认 human）：输出格式，human 或 json。
- days_back（整数，可选，默认 90）：退货回溯窗口。
- group_by（字符串，可选，默认 reason）：聚合层级，reason、product、sku 或 reason_x_product。
- min_returns（整数，可选，默认 3）：摘要中包含的每组最小退货次数。
- writeoff_reasons（数组，可选，默认 ["DEFECTIVE"]）：视为不可重新入库（全额 COGS 冲销）的退货原因。
- flat_restocking_cost（浮点数，可选，默认 5.00）：每个退货行项目的平均人工成本，用于建模重新入库工作量。
工作流程：
- 查询 returns，条件为
created_at:>='<NOW - days_back days>'，获取窗口内所有退货及其行项目定价。 - 对每个退货的 order.id 查询 orders 的 refunds，获取退款金额并映射到行项目。
- 批量查询 inventoryItems 的 unitCost。
- 按行项目计算各项成本并汇总。
该技能在执行过程中会输出会话跟踪信息，包括开始时的技能标识、每步操作后的进度，以及完成时的汇总结果（human 格式为文本摘要，json 格式为结构化 JSON）。
适用场景
- 识别成本最高的退货原因或产品线，优先进行运营改进。
- 使用 group_by: reason_x_product 发现“致命组合”，例如 DEFECTIVE × 主力 SKU，从而在源头解决供应商质量问题。
- 在 unitCost 更新后重新运行，因为过时的成本数据最常导致 COGS 冲销偏差。
- 与 return-reason-analysis 配合使用，对比“退货最多”与“成本最高”的差异。
限制
- 该技能为只读，不执行任何变更操作。
- 成本数字为估算值，基于 unitCost、退款总额和 flat_restocking_cost 推导，在将输出视为会计真相之前，需要根据实际运营校准 flat-cost 数值。
- 缺少 unitCost 时，COGS 按 0 处理并标记该行。
- 退款尚未处理时，使用行项目折扣总额作为估算。
- 一个退货对应多个退款时，汇总与该退货行项目关联的退款。
- 无运费成本（免运费）时，运费损失为 0。
- 遇到 THROTTLED 错误时，等待 2 秒后重试，最多 3 次。