shopify-admin-delivery-time-analysis

用途

该技能分析已履约订单，计算从履约创建（fulfillment created）到送达（delivered）的平均运输时间，并按承运商分组。它会呈现哪些承运商持续偏慢，或缺少送达确认。该技能为只读，不执行任何变更操作。

主要能力

按承运商统计平均运输时间（deliveredAt - createdAt）。
识别持续偏慢或缺少送达确认的承运商。
可选按履约地点（location_id）进行细分。
输出 human 或 json 格式，并生成 CSV 文件。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	30	已履约订单的回溯窗口
min_orders	integer	否	5	纳入平均统计的每个承运商最小订单数
location_id	string	否	—	按履约地点筛选（可选）
format	string	否	human	输出格式：human 或 json

安全性

该技能为只读，不执行任何变更操作，可随时安全运行。

工作流程

查询订单：使用查询条件 fulfillment_status:shipped created_at:>='<NOW - days_back days>'，每次取 250 条并分页，直到 hasNextPage 为 false。预期返回包含 fulfillments（createdAt、updatedAt、deliveredAt、trackingInfo.company）的订单。
按承运商计算运输时间：deliveredAt - createdAt（跳过 deliveredAt 为 null 的订单）。
可选查询 fulfillmentOrders：按 assignedLocationId、status: CLOSED 分页，用于按地点细分。

GraphQL 操作

# orders:query — validated against api_version 2025-01
query FulfilledOrders($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        fulfillments {
          id
          createdAt
          updatedAt
          deliveredAt
          status
          trackingInfo {
            company
            number
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# fulfillmentOrders:query — validated against api_version 2025-01
query FulfillmentOrdersByLocation($locationId: ID!, $after: String) {
  fulfillmentOrders(
    assignedLocationId: $locationId
    first: 250
    after: $after
    query: "status:closed"
  ) {
    edges {
      node {
        id
        assignedLocation {
          location {
            id
            name
          }
        }
        order {
          id
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪

Claude 必须在每个阶段输出以下内容，这是强制要求。

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Delivery Time 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（默认）时：

══════════════════════════════════════════════
DELIVERY TIME ANALYSIS  (<days_back> days)
  Orders analyzed:     <n>
  With delivery data:  <n>

  Carrier              Orders  Avg Days  Min  Max
  ─────────────────────────────────────────────
  UPS                  <n>     <d>       <d>  <d>
  USPS                 <n>     <d>       <d>  <d>
  FedEx                <n>     <d>       <d>  <d>
  (carriers below min_orders threshold excluded)
  Output: delivery_analysis_<date>.csv
══════════════════════════════════════════════

format 为 json 时输出：

{
  "skill": "delivery-time-analysis",
  "store": "<domain>",
  "period_days": 30,
  "carriers": [
    { "name": "UPS", "orders": 0, "avg_days": 0, "min_days": 0, "max_days": 0 }
  ],
  "output_file": "delivery_analysis_<date>.csv"
}

输出格式

CSV 文件 delivery_analysis_<YYYY-MM-DD>.csv，列包括：order_name, fulfillment_id, carrier, fulfilled_at, delivered_at, transit_days。

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
deliveredAt is null	承运商尚未确认送达	从平均值中排除，计为“运输中”
No fulfilled orders in window	周期太短或没有订单	以摘要退出：0 个订单

最佳实践

将 min_orders 设为 10 以获得具有统计意义的平均值——订单数更少的承运商会使结果产生偏差。
deliveredAt 仅在承运商通过跟踪事件确认送达时才会填充；部分承运商不上报此信息，因此 null 值属预期情况。
每月运行一次，以跟踪承运商随时间的表现，并为承运商合同谈判提供依据。
可与 wismo-bulk-status-report 技能交叉参考，将配送偏慢的承运商与 WISMO 工单量关联起来。

适用场景

电商运营人员需要评估不同承运商的配送时效。
需要按履约地点分析配送表现。
需要为承运商合同谈判提供数据支持。
需要将配送时效与客户咨询（WISMO）关联分析。

限制

只读，不执行任何变更。
需要已认证的 Shopify CLI 会话和 read_orders 权限。
deliveredAt 可能为 null，部分承运商不上报送达确认。
订单数低于 min_orders 的承运商会被排除在平均值之外。