shopify-admin-order-cancellation-analysis

用途

该技能计算可配置时间窗口内的订单取消率（取消订单数 / 总订单数），并按 cancelReason（CUSTOMER、FRAUD、INVENTORY、DECLINED、OTHER、STAFF）进行拆分。它能够揭示取消模式的变化——例如，INVENTORY 取消激增表明库存数据完整性问题，而 FRAUD 取消激增则表明可能存在协同攻击。该技能为只读操作，不执行任何变更。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	30	分析所包含订单的回溯窗口
bucket	string	否	day	时间分桶：day、week 或 month
min_value	float	否	0	仅包含总价值高于此值的订单
reason_filter	string	否	—	可选，筛选单个 cancelReason
format	string	否	human	输出格式：human 或 json

安全性

ℹ️ 只读技能——不执行任何变更。可随时安全运行。分析使用 Shopify 或员工在取消时记录的 cancelReason——准确性取决于员工是否选择了正确的原因。

工作流程步骤

OPERATION: orders — 查询
- 输入：query: "created_at:>='<NOW - days_back days>'", first: 250, select cancelledAt, cancelReason, displayFinancialStatus, totalPriceSet, pagination cursor
- 预期输出：窗口内创建的所有订单（已取消和未取消），用于计算取消率；分页直到 hasNextPage: false
将订单划分为已取消（cancelledAt != null）和未取消。计算总体取消率 = 已取消 / 总数。
对于已取消订单，按 cancelReason 和时间分桶进行分组。计算每个分桶和每个原因的取消率。
识别任何单一原因超过其过去 7 个分桶平均值 2 倍的时间分桶——标记为异常。

GraphQL 操作

# orders:query — 已针对 api_version 2025-01 验证
query OrdersForCancellationAnalysis($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        cancelledAt
        cancelReason
        displayFinancialStatus
        displayFulfillmentStatus
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        customer {
          id
          numberOfOrders
        }
        staffMember {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段发出以下输出。这是强制性的。

开始时，发出：

╔══════════════════════════════════════════════╗
║  SKILL: Order Cancellation 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（默认）：

══════════════════════════════════════════════
CANCELLATION ANALYSIS  (<days_back> days, by <bucket>)
  Total orders:        <n>
  Cancelled orders:    <n>  (<pct>%)
  Lost revenue:        $<amount>

  By reason:
    CUSTOMER     <n>  (<pct>%)
    FRAUD        <n>  (<pct>%)
    INVENTORY    <n>  (<pct>%)
    DECLINED     <n>  (<pct>%)
    OTHER        <n>  (<pct>%)

  Anomaly buckets (>2x trailing avg):
    <bucket-key>  reason=<reason>  rate=<pct>%
  Output: cancellation_analysis_<date>.csv
══════════════════════════════════════════════

对于 format: json，发出：

{
  "skill": "order-cancellation-analysis",
  "store": "<domain>",
  "period_days": 30,
  "bucket": "day",
  "total_orders": 0,
  "cancelled_orders": 0,
  "cancellation_rate": 0,
  "lost_revenue": 0,
  "currency": "USD",
  "by_reason": {
    "CUSTOMER": 0, "FRAUD": 0, "INVENTORY": 0, "DECLINED": 0, "OTHER": 0
  },
  "anomalies": [],
  "output_file": "cancellation_analysis_<date>.csv"
}

输出格式

CSV 文件 cancellation_analysis_<YYYY-MM-DD>.csv，包含列： bucket_start, bucket_end, total_orders, cancelled_orders, rate_pct, reason_customer, reason_fraud, reason_inventory, reason_declined, reason_other, lost_revenue, currency

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
已取消订单的 cancelReason 为 null	早于原因字段的旧订单	归入 OTHER，记录数量
窗口内无订单	空店铺或测试域名	以摘要退出：0 订单，0% 取消率
已取消订单创建于窗口之外	取消发生在窗口内但订单更早	按设计排除——分析创建队列

最佳实践

1–3% 的基准取消率是典型的；超过 5% 的激增值得调查。
持续的 INVENTORY 取消表明店面库存与仓库之间存在同步问题——将此技能与 multi-location-inventory-audit 配合使用。
持续的 FRAUD 取消表明欺诈过滤器正在改善（好）或存在协同攻击（坏）——与 order-risk-report 交叉参考。
高 DECLINED 率通常与结账摩擦或过期的支付方式相关——结合结账放弃数据一起调查。
每周运行以尽早发现原因组合的变化；在每次大型促销后运行以确认取消没有激增。