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

安全性

ℹ️ 只读技能——不执行任何变更。可随时安全运行。

工作流步骤

OPERATION: productVariants — query
- 输入：first: 250，query: <vendor_filter if set>，选择 sku、inventoryQuantity、inventoryItem { id }、分页游标
- 预期输出：所有带库存水平的变体；分页直到 hasNextPage: false
筛选出 inventoryQuantity >= min_quantity 的变体
OPERATION: orders — query
- 输入：query: "created_at:>='<NOW - days_back days>'"，first: 250，选择 lineItems { variant { id }, quantity }、分页游标
- 预期输出：窗口期内售出的所有行项目，用于构建“已售变体 ID”集合
OPERATION: inventoryItems — query
- 输入：有库存变体的 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 应用降价标签，然后创建清仓集合。