用途
按客户生命周期消费额与订单频率进行排名，识别前 N%（可按金额、频率或两者综合评分），输出 VIP 候选名单 CSV。可选地通过 customerUpdate 为符合条件的客户打上 VIP 标签。用于构建忠诚度细分、优先提供白手套服务或为专属访问活动筛选种子客户。生命周期消费额与订单数直接来自 Shopify 客户聚合数据，无需外部 CRM。
主要能力
- 按消费额（生命周期价值）、订单频率或两者综合评分进行排名。
- 可设置最低订单数（min_orders，默认 2）与最低消费额（min_spend，默认 0）作为资格门槛。
- 通过 top_pct 参数指定前百分之几为 VIP（默认 5，即前 5%）。
- 输出 CSV 文件，列包括：customer_id、name、email、lifetime_spend、currency、orders_count、last_order_date、composite_score、rank、tag_applied。
- 可选为合格客户打标签（tag_customers，默认 false；标签默认 vip）。
- 支持 human 与 json 两种输出格式。
使用方式
前置条件：已认证的 Shopify CLI 会话，命令为 shopify store auth --store <domain> --scopes read_customers,read_orders,write_customers；API 范围需 read_customers、read_orders，若打标签则需 write_customers。
参数说明：
- store（字符串，必填）：店铺域名，如 mystore.myshopify.com。
- format（字符串，可选，默认 human）：输出格式 human 或 json。
- dry_run（布尔，可选，默认 true）：预览 VIP 名单而不实际打标签。
- rank_by（字符串，可选，默认 spend）：排名策略，可选 spend（生命周期价值）、frequency（订单数）或 both（综合评分）。
- top_pct（浮点数，可选，默认 5）：前百分之几可获 VIP 资格。
- min_orders（整数，可选，默认 2）：有资格的最低生命周期订单数。
- min_spend（浮点数，可选，默认 0）：有资格的最低生命周期消费额（店铺币种）。
- tag_customers（布尔，可选，默认 false）：为 true 时通过 customerUpdate 为合格客户打 VIP 标签。
- tag（字符串，可选，默认 vip）：打标签时使用的标签字符串。
工作流程步骤：
- customers 查询：first: 250，query: "orders_count:>=<min_orders>"，选择 id、displayName、defaultEmailAddress { emailAddress }、numberOfOrders、amountSpent { amount currencyCode }、tags 及分页游标；分页直到 hasNextPage: false。
- orders 查询（仅在按频率排名时用于最近订单标注）：对每位顶级候选者执行 query: "customer_id:<id>"、first: 1、sortKey: CREATED_AT、reverse: true。
- 过滤 amountSpent.amount >= min_spend；评分规则：spend → 消费额；frequency → 订单数；both → 0.6 × 归一化消费额 + 0.4 × 归一化频率；取前 top_pct%。
- customerUpdate 变更（仅当 tag_customers: true 且 dry_run: false）：input: { id: <customer_id>, tags: [...existing_tags, <tag>] }；返回 customer.id、customer.tags、userErrors。
适用场景
- 构建忠诚度细分，识别高价值客户。
- 优先为 VIP 提供专属支持服务。
- 为专属访问或独家活动筛选种子客户。
- 配合客户挽回技能，标记不活跃 VIP 进行高优先级再互动。
限制与安全
- 当 tag_customers: true 时，会执行 customerUpdate 变更客户标签列表；标签会持续到手动移除。
- 默认 dry_run: true，必须显式设置 dry_run: false 和 tag_customers: true 才会应用标签。
- 多币种店铺需按店铺默认币种转换后再排名。
- 若合格客户数少于 top_pct% 对应数量，可降低 min_orders/min_spend。
- API 限流时等待 2 秒并重试最多 3 次；customerUpdate 的 userErrors 会记录并跳过。
- 最佳实践：使用 rank_by: both 平衡大额消费者与忠诚客户；季度性重新运行并使用带日期的标签（如 vip-2026-Q2），使失效 VIP 自动退出。
GraphQL 操作
所有查询与变更均针对 api_version 2025-01 验证，包含 customers:query、orders:query、customerUpdate:mutation。