shopify-admin-customer-timeline-export

用途

为单个客户生成完整、按时间顺序排列的档案。拉取客户记录（身份信息、营销同意状态、终身消费总额、标签、备注、地址）以及该客户下的所有订单（含行项目、履约、退款和退货），合并输出一份 CSV 文件，并生成人类可读的时间线。适用于客服处理升级工单、数据导出请求，或在账户合并、删除前留存原始记录。只读操作，不执行任何变更。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
customer_id	string	是	—	客户的 GID（例如 gid://shopify/Customer/12345）
include_line_items	bool	否	true	是否在 CSV 中包含逐行项目行（每个行项目一行）
include_refunds	bool	否	true	是否在时间线中将退款和退货作为单独行包含
max_orders	integer	否	250	拉取订单数量上限（按最新优先）；0 表示不设上限

安全性

只读技能，不执行任何变更，可随时安全运行。输出包含个人身份信息，请像处理任何客户导出一样谨慎对待生成的 CSV，并在支持工单关闭后删除。

工作流程

customer — query：输入 id: <customer_id>，选择身份字段、终身聚合、标签、备注、营销同意、地址、createdAt。预期输出：客户头部记录；若为 null 则中止并给出明确错误。
orders — query：输入 query: "customer_id:<numeric_id>"、first: 250、sortKey: CREATED_AT、reverse: true，选择订单字段、行项目、履约、退款及分页游标（若设置了 max_orders 则停止）。预期输出：包含嵌入退款和履约的完整按时间顺序的订单列表。
构建合并时间线事件：客户创建 → 每个订单 → 每个订单的每次退款/退货。所有事件按日期时间升序排序，用于人类可读摘要；CSV 同样按升序排序。

GraphQL 操作

customer:query（已针对 api_version 2025-01 验证）

query CustomerHeaderForTimeline($id: ID!) {
  customer(id: $id) {
    id
    displayName
    firstName
    lastName
    defaultEmailAddress { emailAddress }
    phone
    note
    tags
    numberOfOrders
    amountSpent { amount currencyCode }
    emailMarketingConsent { marketingState marketingOptInLevel consentUpdatedAt }
    smsMarketingConsent { marketingState marketingOptInLevel consentUpdatedAt }
    addresses(first: 25) {
      id firstName lastName address1 address2 city provinceCode countryCodeV2 zip phone
    }
    defaultAddress { id }
    createdAt
    updatedAt
  }
}

orders:query（已针对 api_version 2025-01 验证）

query CustomerOrdersForTimeline($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query, sortKey: CREATED_AT, reverse: true) {
    edges {
      node {
        id
        name
        createdAt
        processedAt
        displayFinancialStatus
        displayFulfillmentStatus
        cancelledAt
        cancelReason
        totalPriceSet { shopMoney { amount currencyCode } }
        totalShippingPriceSet { shopMoney { amount currencyCode } }
        totalDiscountsSet { shopMoney { amount currencyCode } }
        lineItems(first: 50) {
          edges { node {
            id title quantity sku
            discountedTotalSet { shopMoney { amount currencyCode } }
            variant { id sku }
          } }
        }
        fulfillments {
          id status deliveredAt
          trackingInfo { number url company }
        }
        refunds {
          id
          createdAt
          totalRefundedSet { shopMoney { amount currencyCode } }
          refundLineItems(first: 50) {
            edges { node {
              quantity
              lineItem { id title }
              subtotalSet { shopMoney { amount currencyCode } }
            } }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Customer Timeline Export             ║
║  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（默认）：

══════════════════════════════════════════════
CUSTOMER TIMELINE
  Customer:        <name> (<email>)  ID: <customer_id>
  Joined:          <createdAt>
  Lifetime spend:  $<amount> <currency>   Total orders: <n>   Refunds total: $<amount>
  Tags:            <list>
  Email consent:   <state> (since <date>)   SMS consent: <state> (since <date>)

  Recent timeline (most recent first):
    <date>  ORDER   <name>  $<amount>  <financial> / <fulfillment>
    <date>  REFUND  <id>    $<amount>
    <date>  RETURN  <id>    items: <n>
    ...
  Output: customer_timeline_<customer_id>_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "customer-timeline-export",
  "store": "<domain>",
  "customer_id": "<gid>",
  "header": {
    "name": "<string>", "email": "<string>", "phone": "<string>",
    "joined": "<ISO8601>", "lifetime_spend": 0, "currency": "USD",
    "total_orders": 0, "tags": [],
    "email_consent": "<state>", "sms_consent": "<state>"
  },
  "totals": { "orders": 0, "refunds_count": 0, "refunds_amount": 0 },
  "output_file": "customer_timeline_<customer_id>_<date>.csv"
}

输出格式

CSV 文件 customer_timeline_<customer_id>_<YYYY-MM-DD>.csv，包含列： event_datetime, event_type, event_id, order_name, line_item_title, sku, quantity, amount, currency, financial_status, fulfillment_status, tracking_number, notes

事件类型包括：customer_created、order_placed、order_fulfilled、order_delivered、order_cancelled、refund_issued、return_initiated。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
Customer not found	GID 错误	使用 order-lookup-and-summary 查找最近订单，然后读取 customer.id
0 orders	新账户或仅访客	输出仅含头部的时间线
Order anonymized	GDPR 数据清除	跳过行项目；输出占位行
Pagination beyond max_orders	达到上限	停止，设置 truncated: true

最佳实践

在任何合并、删除或升级之前运行——一旦合并提交，合并前状态将无法重建。
对于高交易量客户，设置 max_orders: 50；单个支持工单很少需要完整终身记录。
CSV 按事件排序，因此下游透视无需重新整形。
与 customer-merge 配合使用：在合并前对胜出方和失败方都运行，以留存永久合并前记录。