shopify-admin-fulfillment-status-digest

用途

该技能生成每日运营分诊摘要，汇总所有未履约（unfulfilled）和部分履约（partially-fulfilled）的订单，并按订单等待时长进行分段。它会标记处于活跃履约保留（hold）状态的订单，替代手动滚动 Shopify 后台订单页查找积压订单和异常订单的流程。技能会拉取每个未结订单、计算其账龄、将其归入可配置的时间段，并呈现当前处于履约保留的订单，让运营团队在一次只读操作中获得完整的异常队列。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
aging_thresholds_days	array	否	[1, 3, 7]	账龄分桶的天数边界（例如 [1,3,7] 生成：0–1d、1–3d、3–7d、7d+）
include_holds	bool	否	true	是否在单独区块中包含处于活跃履约保留的订单
limit	integer	否	250	每页拉取的最大订单数

工作流程

1. OPERATION: orders — query

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

2. OPERATION: fulfillmentOrders — query（通过嵌套的 order.fulfillmentOrders）

   • 输入：对第 1 步的每个订单执行 fulfillmentOrders(first: 5) 以检查 status 和 requestStatus；标记任何 status 为 ON_HOLD 的订单
   • 预期输出：每个订单的保留状态、holdUntil（如已设置）；用于摘要的 Holds 区块

GraphQL 操作

# orders:query — validated against 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 类型上的嵌套字段——frontmatter 中的 fulfillmentOrders:query 条目记录该操作会访问履约订单数据。

会话跟踪

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 并预期分页——摘要仍会跨所有页面正确聚合。