用途
该技能用于计算平均订单价值（AOV），支持按可配置的时间桶（日、周、月）统计，并按新客户与回头客对结果进行细分。它通过追踪 AOV 趋势，帮助衡量追加销售计划、捆绑优惠或免运费门槛调整等举措带来的影响。该技能为只读操作，不执行任何写操作（no mutations）。
前置条件
需要已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_customers
API 权限范围：read_orders、read_customers
参数
store（字符串，必填，无默认值）：店铺域名，例如 mystore.myshopify.com
days_back（整数，可选，默认 90）：总回溯窗口
bucket（字符串，可选，默认 week）：时间桶，可选 day、week 或 month
format（字符串，可选，默认 human）：输出格式，可选 human 或 json
安全性
该技能为只读技能，不执行任何写操作，可随时安全运行。
工作流程步骤
-
操作 orders — 查询：输入 query: "created_at:>='<NOW - days_back days>'", first: 250, select totalPriceSet, customer { id, numberOfOrders }, createdAt, pagination cursor。预期输出：窗口内所有订单；分页直到 hasNextPage: false。
-
对每个订单进行分类：如果 customer.numberOfOrders == 1，则为新客户订单；否则为回头客订单。
-
操作 customers — 查询（可选的队列上下文补充）：输入近期客户，用于验证新客户与回头客的细分。
-
按时间桶对订单分组；计算每个时间桶及每个客户细分的 AOV。
GraphQL 操作
orders:query — 已针对 api_version 2025-01 验证：
query AOVData($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { id name createdAt totalPriceSet { shopMoney { amount currencyCode } } customer { id numberOfOrders } } } pageInfo { hasNextPage endCursor } } }
customers:query — 已针对 api_version 2025-01 验证：
query NewVsReturningCustomers($query: String!, $after: String) { customers(first: 250, after: $after, query: $query) { edges { node { id numberOfOrders createdAt } } pageInfo { hasNextPage endCursor } } }
会话追踪
Claude 必须在每个阶段输出以下内容，这是强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Average Order Value Trends ║ ║ 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（默认）：
══════════════════════════════════════════════ AOV TRENDS (<days_back> days, bucket: <bucket>) Orders analyzed: <n> Overall AOV: $<amount> New customer AOV: $<amount> Returning AOV: $<amount>
Period Orders AOV New AOV Returning AOV ──────────────────────────────────────────────────── 2026-W14 <n> $<n> $<n> $<n> Output: aov_trends_<date>.csv ══════════════════════════════════════════════
对于 format: json，输出：
{ "skill": "average-order-value-trends", "store": "<domain>", "period_days": 90, "overall_aov": 0, "new_customer_aov": 0, "returning_customer_aov": 0, "by_period": [], "output_file": "aov_trends_<date>.csv" }
输出格式
CSV 文件 aov_trends_<YYYY-MM-DD>.csv，包含列：period, order_count, aov, new_customer_orders, new_customer_aov, returning_orders, returning_aov, currency
错误处理
THROTTLED：API 速率限制超出。恢复方式：等待 2 秒，最多重试 3 次。
访客结账订单：无客户记录。恢复方式：计入总数，但从新客户/回头客细分中排除。
窗口内无订单：新店铺或淡季。恢复方式：以 0 AOV 退出。
最佳实践
免运费门槛提高或引入捆绑销售后，应在发布的当周/当月体现出 AOV 提升——可使用此报告衡量影响。
回头客 AOV 通常高于新客户——差距缩小可能表明忠诚度下降。
bucket: week 最适合衡量营销活动；bucket: month 适合长期趋势追踪。
访客结账订单无法按新客户与回头客细分——对于访客结账率高的店铺，细分会低估新客户数量。