fulfillment-status-digest

用途

该技能用于生成每日运营分流摘要（triage digest），覆盖所有未履约（unfulfilled）和部分履约（partially-fulfilled）的订单，并按照订单已等待的时长进行分段。它会标记出处于活动保留状态的订单。该技能替代了人工在 Shopify 管理后台订单页面滚动查找超龄订单和异常订单的流程：它会抓取所有开放订单，计算订单年龄，将其分入可配置的时间分段桶，并展示当前处于履约保留状态的订单，从而以单次只读操作为运营团队提供完整的异常队列。

前提条件

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

参数

store（字符串，必填，无默认值）：店铺域名（例如 mystore.myshopify.com）
format（字符串，可选，默认 human）：输出格式，human 或 json
dry_run（布尔值，可选，默认 false）：预览操作而不执行变更
aging_thresholds_days（数组，可选，默认 [1, 3, 7]）：年龄分桶的天数边界（例如 [1,3,7] 会生成：0–1d、1–3d、3–7d、7d+）
include_holds（布尔值，可选，默认 true）：是否在单独区块中包含处于活动履约保留状态的订单
limit（整数，可选，默认 250）：每页最多抓取的订单数

工作流程步骤

操作 1：orders — 查询

输入：first: <limit>，query: "fulfillment_status:unfulfilled OR fulfillment_status:partial"，按 CREATED_AT 升序排序（最早优先），分页直至完成
预期输出：所有开放订单及其 createdAt、name、displayFulfillmentStatus；计算年龄 = 当前时间 − createdAt（天）；按 aging_thresholds_days 分段分桶

操作 2：fulfillmentOrders — 查询（通过嵌套的 order.fulfillmentOrders）

输入：对步骤 1 的每个订单，调用 fulfillmentOrders(first: 5) 检查 status 和 requestStatus；标记任何 status: ON_HOLD 的订单
预期输出：每个订单的保留状态，以及设置的 holdUntil；用于生成摘要中的保留区块

GraphQL 操作

# orders:query — 已针对 api_version 2025-01 验证
query FulfillmentStatusDigest($first: Int!, $after: String, $query: String) {
  orders(first: $first, after: $after, query: $query, sortKey: CREATED_AT) {
    edges {
      node {
        id
        name
        createdAt
        displayFulfillmentStatus
        displayFinancialStatus
        totalPriceSet {
          shopMoney { amount currencyCode }
        }
        customer {
          id
          firstName
          lastName
        }
        fulfillmentOrders(first: 5) {
          edges {
            node {
              id
              status
              requestStatus
              fulfillAt
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

注：fulfillmentOrders 是 Order 类型上的嵌套字段——fulfillmentOrders:query frontmatter 条目说明该操作会访问履约订单数据。

会话跟踪

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

启动时输出：

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

══════════════════════════════════════════════
OUTCOME SUMMARY
  Total open orders:          <n>
  By age bucket (0-1d):       <n>
  By age bucket (1-3d):       <n>
  By age bucket (3-7d):       <n>
  By age bucket (7d+):        <n>
  Orders on hold:             <n>
  Errors:                     0
  Output:                     none
══════════════════════════════════════════════

当 format 为 json 时，输出：

{
  "skill": "fulfillment-status-digest",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "FulfillmentStatusDigest", "type": "query", "params_summary": "limit: <n>, query: fulfillment_status:unfulfilled OR partial", "result_summary": "<n> orders fetched", "skipped": false },
    { "step": 2, "operation": "fulfillmentOrders", "type": "query", "params_summary": "nested per order, first: 5", "result_summary": "<n> orders on hold", "skipped": false }
  ],
  "outcome": {
    "total_open_orders": 0,
    "buckets": [
      { "label": "0-1d", "count": 0 },
      { "label": "1-3d", "count": 0 },
      { "label": "3-7d", "count": 0 },
      { "label": "7d+", "count": 0 }
    ],
    "orders_on_hold": 0,
    "errors": 0,
    "output_file": null
  }
}

输出格式

Fulfillment Age Digest — <store> — <date>

Age Bucket
Order Count
Oldest Order

0–1 days
n
#XXXX

1–3 days
n
#XXXX

3–7 days
n
#XXXX

7+ days
n
#XXXX (⚠️ review)

Orders On Hold (if include_holds: true and holds exist):

Order
Hold Since
Fulfillment Status

#XXXX
3 days
ON_HOLD

错误处理

No orders returned：原因—系统中无开放订单；恢复—店铺已完全履约，无需操作
fulfillmentOrders returns empty：原因—订单尚未分配履约任务；恢复—该订单可能尚未分配到某个地点
Rate limit (429)：原因—订单量大且需要分页；恢复—将 limit 减小到 100

最佳实践

每天早上处理任何订单之前首先运行此摘要——它在一屏中给出异常队列。
7d+ 分桶中的订单是最高优先级；调查并要么履约，要么带原因显式保留。
使用 format: json 将摘要管道接入 Slack 通知或仪表盘脚本。
结合 order-hold-and-release，无需离开 CLI 即可对摘要中发现的异常采取行动。
对于拥有 500+ 开放订单的店铺，设置 limit: 100 并预期分页——摘要仍会在所有页面间正确聚合。

技能介绍