shopify-admin-collection-membership-audit

用途

该技能用于识别两类商品集合归属问题：

• 孤儿商品（orphans）：未加入任何集合的商品，在店铺导航中不可见。
• 过度归集商品（over-collected）：出现在异常多集合中的商品，可能造成陈列噪音。

该技能为只读操作，不执行任何变更。

主要能力

• 查询商品及其集合归属，分页直到 hasNextPage: false。
• 对每个商品统计集合数量，若为 0 则标记为孤儿，若超过 max_collections 则标记为过度归集。
• 查询集合元数据（id、title、productsCount）以丰富报告。
• 输出 CSV 文件 collection_audit_<YYYY-MM-DD>.csv，列包括：product_id, title, handle, status, collection_count, collections, issue。
• 支持 human 或 json 输出格式。

使用方式

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
max_collections	integer	否	10	超过此集合数量的商品会被标记
status_filter	string	否	active	扫描的商品状态：active、draft 或 all
format	string	否	human	输出格式：human 或 json

工作流程

1. products 查询：输入 query: "status:<status_filter>"、first: 250、选择 collections { edges { node { id } } }、分页游标。输出商品及其集合归属，分页直到 hasNextPage: false。
2. 对每个商品统计集合数量，标记孤儿或过度归集。
3. collections 查询：输入 first: 250、选择 id, title, productsCount。输出集合元数据用于丰富报告。

GraphQL 操作

# products:query — validated against api_version 2025-01
query ProductCollectionMembership($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        collections(first: 30) {
          edges {
            node {
              id
              title
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# collections:query — validated against api_version 2025-01
query CollectionOverview($after: String) {
  collections(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        productsCount {
          count
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

会话跟踪输出

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Collection Membership Audit          ║
║  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>

完成时，human 格式输出：

══════════════════════════════════════════════
COLLECTION MEMBERSHIP AUDIT
  Products scanned:      <n>
  Orphan products (0 collections):     <n>
  Over-collected (> <max_collections>): <n>

  Orphan products (sample):
    "<title>" — <status>
  Output: collection_audit_<date>.csv
══════════════════════════════════════════════

json 格式输出：

{
  "skill": "collection-membership-audit",
  "store": "<domain>",
  "products_scanned": 0,
  "orphan_count": 0,
  "over_collected_count": 0,
  "output_file": "collection_audit_<date>.csv"
}

适用场景

• 季节性目录更新后运行，确保所有新商品被分配到正确的集合。
• 定期检查目录卫生，发现导航中不可见的孤儿商品。
• 识别过度归集商品，减少陈列噪音。

限制与注意事项

• 只读技能，不执行任何变更，可随时安全运行。
• 孤儿活跃商品在店铺导航中不可见，顾客只能通过直接 URL 或搜索找到，应优先修复。
• 自动化集合（基于规则）可能根据标签或条件自动拉取商品，手动集合中的孤儿商品仍可能出现在自动化集合中，需同时检查两者。
• 对于导航严格精选的店铺，可使用 max_collections: 5；对于市场型店铺（交叉上架是有意为之），可使用更高阈值。
• 错误处理：THROTTLED（API 速率限制超出）时等待 2 秒，最多重试 3 次；未发现孤儿时以 ✅ no orphans found 退出。