order-notes-and-attributes-report

用途

该技能查询近期订单，提取订单级备注（note）以及行项目自定义属性（例如礼品留言、个性化文字、特殊说明、刻字文本），生成报表供运营和履约团队在拣货/打包环节处理特殊请求。全程只读，不执行任何变更操作。

主要能力

查询订单的 note、customAttributes 以及 lineItems 的 customAttributes。
支持分页，直到 hasNextPage 为 false。
可按 only_with_notes 过滤，仅保留有备注或属性的订单。
可按 attribute_keys 过滤行项目属性，只提取指定键（如 gift_message、engraving）。
输出人类可读摘要或 JSON，并生成 CSV 文件。

使用方式

前置条件：

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

参数：

store（string，必填）：店铺域名，例如 mystore.myshopify.com
days_back（integer，可选，默认 1）：回溯窗口，默认最近 24 小时，适合日常运营
attribute_keys（array，可选，默认 []）：要提取的特定行项目属性键，例如 ["gift_message", "engraving"]；为空表示全部
only_with_notes（bool，可选，默认 false）：仅包含有备注或属性的订单
format（string，可选，默认 human）：输出格式，human 或 json

工作流程：

执行 orders 查询，输入 query: "created_at:>='<NOW - days_back days>'", first: 250，选择 note、customAttributes、lineItems { customAttributes }，使用分页游标。
若 only_with_notes 为 true，过滤出 note 非空或 customAttributes 非空的订单。
若指定 attribute_keys，仅保留匹配键的行项目属性。

GraphQL 操作（针对 api_version 2025-01 验证）：

query OrderNotesAndAttributes($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        displayFulfillmentStatus
        note
        customAttributes {
          key
          value
        }
        lineItems(first: 20) {
          edges {
            node {
              id
              title
              quantity
              variant {
                sku
              }
              customAttributes {
                key
                value
              }
            }
          }
        }
        shippingAddress {
          firstName
          lastName
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪：技能要求在开始、每步之后和完成时输出指定格式的跟踪信息（开始横幅、步骤进度、完成摘要）。

输出格式：

生成 CSV 文件 order_notes_<YYYY-MM-DD>.csv，列包括：order_name, order_id, created_at, fulfillment_status, customer_name, order_note, line_item_title, line_sku, attribute_key, attribute_value。

human 格式完成摘要示例：

══════════════════════════════════════════════
ORDER NOTES & ATTRIBUTES REPORT  (<days_back> day(s))
  Orders queried:         <n>
  Orders with notes:      <n>
  Orders with attributes: <n>

  #<name>  <customer>  [<status>]
    Note: "<note text>"
    Line: "<product>"  gift_message: "Happy Birthday!"
  Output: order_notes_<date>.csv
══════════════════════════════════════════════

json 格式完成输出示例：

{
  "skill": "order-notes-and-attributes-report",
  "store": "<domain>",
  "period_days": 1,
  "orders_queried": 0,
  "orders_with_notes": 0,
  "orders_with_attributes": 0,
  "output_file": "order_notes_<date>.csv"
}

适用场景

在每个履约班次开始时运行（例如 days_back: 1），让拣货/打包人员在开始前拿到打印的特殊说明清单。
节假日期间使用 attribute_keys: ["gift_message"] 聚焦礼品订单。
同时有备注和行项目属性的订单表示高接触履约需求，可标记给资深员工复核。
打印或导出 CSV 并附在拣货单上，便于履约时高效处理特殊需求。

限制与错误处理

该技能为只读，不执行任何变更。
THROTTLED：API 速率限制超出，等待 2 秒后重试，最多 3 次。
No orders with notes：静默期或未收集备注；若 only_with_notes 为 true，则以 0 结果退出。

安全说明

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