collection-reorganization

用途

该技能用于在不打开 Shopify 管理后台的情况下，按库存水平重排手动（自定义）集合中的商品顺序。可替代 Reputon Collection Sort 之类的应用或手动拖拽排序。它会查询集合中的所有商品，按 totalInventory 计算目标排序，并通过单次 collectionReorderProducts 变更应用结果。

注意：仅适用于手动（自定义）集合，Shopify 规则管理的智能集合不受支持。

前置条件

已认证的 Shopify CLI 会话：shopify auth login --store <domain>
API 权限范围：read_products、write_products

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	仅预览操作而不执行变更
collection_id	string	是	—	手动集合的 GID（例如 gid://shopify/Collection/123）
sort_by	string	否	inventory_desc	inventory_desc（库存最高在前）或 inventory_asc（库存最低在前）

安全性

第 2 步执行的 collectionReorderProducts 会立即改变商品展示顺序。该排序可逆——用相反的 sort_by 再运行一次即可恢复，但原有自定义顺序一旦被覆盖将无法恢复。传给变更的 moves 数组必须完整，部分 moves 会产生不确定的顺序。请始终先以 dry_run: true 运行，确认计算出的排序后再提交。

collectionReorderProducts 仅适用于手动（自定义）集合。若集合的 sortOrder 不是 MANUAL，技能须中止并给出明确提示：“Cannot reorder: collection sort order is not MANUAL. Switch the collection to manual sorting in the Shopify admin first.”

工作流程步骤

OPERATION：collection — query
- 输入：id: <collection_id>、first: 250、分页游标
- 预期输出：集合元数据（title、sortOrder）以及所有带 totalInventory 的商品节点；校验 sortOrder == "MANUAL"，否则中止；分页拉取直到获取全部商品
OPERATION：collectionReorderProducts — mutation
- 输入：id: <collection_id>、按 sort_by 参数依 totalInventory 排序的 moves 数组——每个 move 为 {id: <product_id>, newPosition: "<index>"}（从 0 开始的索引字符串）
- 预期输出：job.id 和 job.done；userErrors

GraphQL 操作

# collection:query — validated against api_version 2025-01
query CollectionProducts($id: ID!, $first: Int!, $after: String) {
  collection(id: $id) {
    id
    title
    sortOrder
    products(first: $first, after: $after) {
      edges {
        node {
          id
          title
          totalInventory
          variants(first: 100) {
            edges {
              node {
                inventoryQuantity
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

# collectionReorderProducts:mutation — validated against api_version 2025-01
mutation CollectionReorderProducts($id: ID!, $moves: [MoveInput!]!) {
  collectionReorderProducts(id: $id, moves: $moves) {
    job {
      id
      done
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: collection-reorganization            ║
║  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>

若 dry_run: true，则在每个变更步骤前加 [DRY RUN] 前缀，且不执行该步。

完成时输出：

format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Collection:          <title>
  Products reordered:  <n>
  Sort order:          <inventory_desc|inventory_asc>
  Errors:              0
  Output:              none
══════════════════════════════════════════════

format: json 时输出：

{
  "skill": "collection-reorganization",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "CollectionProducts", "type": "query", "params_summary": "collection_id: <gid>, first: 250", "result_summary": "<n> products fetched", "skipped": false },
    { "step": 2, "operation": "CollectionReorderProducts", "type": "mutation", "params_summary": "sort_by: inventory_desc, <n> moves", "result_summary": "job submitted", "skipped": false }
  ],
  "outcome": {
    "collection_title": "<title>",
    "products_reordered": 0,
    "sort_by": "inventory_desc",
    "errors": 0,
    "output_file": null
  }
}

输出格式

无 CSV 输出。该技能在会话完成摘要中报告新的排序顺序。使用 dry_run: true 可预览计算出的位置列表而不提交。

错误处理

错误	原因	恢复方式
sortOrder 不是 MANUAL	集合是智能/自动集合	在 Shopify 管理后台将集合切换为手动排序
mutation 中的 userErrors	商品 ID 或位置无效	检查所有商品 ID 是否属于该集合
找不到集合	集合 GID 无效	在 Shopify 管理后台核验 GID
速率限制（429）	分页请求过多	将 first 减少为 100 后重试

最佳实践

始终先运行 dry_run: true——技能会打印建议的商品顺序，便于提交前核验。
collectionReorderProducts 是异步的——job.done 可能立即为 false。排序会在数秒内完成；刷新店铺前台以核验。
使用 sort_by: inventory_asc 可将缺货商品推到集合页面底部，减少顾客不满。
对于大型集合（250+ 商品），分页会自动进行但会增加执行时间。可考虑在非高峰时段运行。
该技能仅从 products 节点读取 totalInventory——不按仓库位置聚合。若需按仓库位置排序，可使用 low-inventory-restock 技能确定优先补货商品。