shopify-admin-dead-stock-identifier

用途

识别手头有正库存、但在可配置回溯窗口内未售出任何单位的 SKU。死库存会占用资金、仓储空间和持有成本。该技能为只读，不执行任何变更操作，为降价或清仓决策提供数据基础。

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,read_orders,read_inventory
API 权限范围：read_products、read_orders、read_inventory

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	90	销售回溯窗口——在此期间无销售的 SKU 会被标记
min_quantity	integer	否	1	纳入的最小在手数量（排除真正零库存）
vendor_filter	string	否	—	可选，限定审计范围的供应商
format	string	否	human	输出格式：human 或 json

安全性

只读技能——不执行任何变更操作，可随时安全运行。

工作流程

productVariants — 查询
- 输入：first: 250、query: <vendor_filter if set>、选择 sku、inventoryQuantity、inventoryItem { id }、分页游标
- 预期输出：所有带库存水平的变体；分页直到 hasNextPage: false
筛选出 inventoryQuantity >= min_quantity 的变体
orders — 查询
- 输入：query: "created_at:>='<NOW - days_back days>'"、first: 250、选择 lineItems { variant { id }, quantity }、分页游标
- 预期输出：窗口内售出的所有行项目，用于构建“已售变体 ID”集合
inventoryItems — 查询
- 输入：有库存变体的 inventoryItemIds 批次
- 预期输出：用于死库存价值计算的库存项目成本数据
交叉比对：第 2 步中的变体若不在第 3 步的已售集合中 → 死库存

GraphQL 操作

# productVariants:query — validated against api_version 2025-01
query VariantsWithStock($query: String, $after: String) {
  productVariants(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        sku
        inventoryQuantity
        product {
          id
          title
          vendor
          status
        }
        inventoryItem {
          id
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# orders:query — validated against api_version 2025-01
query OrderLineItemsInPeriod($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        lineItems(first: 50) {
          edges {
            node {
              quantity
              variant {
                id
              }
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# inventoryItems:query — validated against api_version 2025-01
query InventoryItemCosts($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on InventoryItem {
      id
      unitCost {
        amount
        currencyCode
      }
      tracked
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Dead Stock Identifier                ║
║  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（默认）：

══════════════════════════════════════════════
DEAD STOCK REPORT  (no sales in <days_back> days)
  SKUs with stock:       <n>
  SKUs with zero sales:  <n>  (<pct>%)
  Est. dead stock value: $<amount>

  Top dead stock by value:
    "<product>"  SKU: <sku>  Qty: <n>  Value: $<n>
  Output: dead_stock_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "dead-stock-identifier",
  "store": "<domain>",
  "period_days": 90,
  "stocked_skus": 0,
  "dead_stock_skus": 0,
  "dead_stock_pct": 0,
  "estimated_value": 0,
  "currency": "USD",
  "output_file": "dead_stock_<date>.csv"
}

输出格式

CSV 文件 dead_stock_<YYYY-MM-DD>.csv，列包括： variant_id, sku, product_title, vendor, quantity_on_hand, days_since_last_sale, unit_cost, total_cost_value

错误处理

错误	原因	恢复方式
THROTTLED	超出 API 速率限制	等待 2 秒，最多重试 3 次
No orders in window	新店铺或销售极慢的时期	所有有库存的 SKU 都会被标记——符合预期
Variant without inventory item	捆绑或虚拟产品	跳过库存成本，仍列入清单

最佳实践

季节性产品使用 days_back: 90；常青目录使用 days_back: 180 或 days_back: 365。
按 total_cost_value 降序排序，以便按资金影响优先安排降价决策。
与 stock-velocity-report 交叉比对，以区分真正的死库存和仍偶尔销售的慢动销品。
将结果作为折扣活动的输入：使用 product-tag-bulk-update 应用降价标签，然后创建清仓集合。