multi-location-inventory-audit

用途

该技能用于发现跨地点的库存同步差异，具体是标记出可用数量（available）为负、或已承诺数量（committed）大于现有库存（on_hand）的变体。这些情况表明 Shopify 的已承诺计数器与实际物理库存之间存在漂移。常见原因包括：第三方物流延迟过账退货、仓储管理系统扣减与 Shopify 已承诺计数叠加，或多店铺同步问题。该技能为只读操作，不执行任何变更，可替代手动库存对账表格，并免去在 Shopify 后台逐个地点查看的麻烦。

前置条件

执行 shopify auth login --store <domain>
API 权限范围：read_products、read_inventory、read_locations

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
location_ids	array	否	—	要审计的特定地点 GID（默认：所有活跃地点）
flag_negative_available	bool	否	true	标记 available < 0 的变体
flag_committed_exceeds_onhand	bool	否	true	标记 committed > on_hand 的变体
include_untracked	bool	否	false	包含已禁用库存跟踪的变体

工作流程步骤

OPERATION: locations — 查询
- 输入：first: 50, query: "is_active:true"
- 预期输出：活跃地点 ID 和名称列表；如果提供了 location_ids 参数则按此过滤
OPERATION: inventoryItems — 查询（通过 location.inventoryLevels）
- 输入：每个地点获取每个变体的库存水平，包含 available、committed、onHand 数量
- 预期输出：每个地点的库存矩阵；计算差异；收集被标记的变体

GraphQL 操作

# locations:query — 已针对 api_version 2025-01 验证
query ActiveLocations($first: Int!) {
  locations(first: $first, query: "is_active:true") {
    edges {
      node {
        id
        name
        isActive
        inventoryLevels(first: 250) {
          edges {
            node {
              id
              available
              item {
                id
                sku
                tracked
                variant {
                  id
                  displayName
                  product {
                    id
                    title
                  }
                }
              }
            }
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  }
}

# inventoryItems:query — 已针对 api_version 2025-01 验证
query InventoryItemLevels($id: ID!, $after: String) {
  location(id: $id) {
    id
    name
    inventoryLevels(first: 250, after: $after) {
      edges {
        node {
          id
          available
          item {
            id
            sku
            tracked
            inventoryLevel(locationId: $id) {
              available
              incoming
            }
            variant {
              id
              displayName
              inventoryQuantity
              product {
                id
                title
              }
            }
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}

注意：frontmatter 中的 inventoryItems:query 表示通过地点库存水平查询库存项目数据。Shopify Admin API 通过 location.inventoryLevels 呈现每个地点的库存。

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: multi-location-inventory-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>

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Locations audited:          <n>
  Variants scanned:           <n>
  Discrepancies found:        <n>
  Negative available:         <n>
  Committed > On Hand:        <n>
  Errors:                     0
  Output:                     inventory-audit-<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "multi-location-inventory-audit",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "ActiveLocations", "type": "query", "params_summary": "first: 50, is_active: true", "result_summary": "<n> locations", "skipped": false },
    { "step": 2, "operation": "InventoryItemLevels", "type": "query", "params_summary": "per location, first: 250", "result_summary": "<n> variants scanned", "skipped": false }
  ],
  "outcome": {
    "locations_audited": 0,
    "variants_scanned": 0,
    "discrepancies_found": 0,
    "negative_available_count": 0,
    "committed_exceeds_onhand_count": 0,
    "errors": 0,
    "output_file": "inventory-audit-<date>.csv"
  }
}

输出格式

CSV 文件 inventory-audit-<YYYY-MM-DD>.csv，列包括：location_name、product_title、variant_title、sku、available、flag。

同时显示内联摘要表：

Location	Variants Scanned	Discrepancies	Negative Available	Committed > On Hand

错误处理

错误	原因	恢复方法
未返回地点	未找到活跃地点	在 Shopify 后台验证至少有一个活跃地点
某地点的 inventoryLevels 为空	该地点未分配库存	对于仅配送或虚拟地点属预期情况
速率限制（429）	大量库存 + 多个地点	将每个地点的分页大小减少到 100
所有变体的 item.tracked: false	店铺使用未跟踪库存	启用跟踪或设置 include_untracked: true

最佳实践

每周运行此审计——库存漂移会逐渐累积，在复合之前最容易修复。
可用数量为负并不总是表示存在真实问题——在闪购期间可能合法出现。在进行手动更正前，请与订单量交叉核对。
将 CSV 输出与 inventory-adjustment 技能配合使用，在审计发现差异后立即应用更正。
在第三方物流退货批次过账前后运行审计，以衡量退货库存是否被正确计入。
过滤到单个 location_id 进行针对性审计（例如仅主仓库），以减少大型目录的 API 调用。