inventory-valuation-report

用途

本技能计算库存总价值（现有数量 × 单位成本），并按地点和供应商细分。用于定期资产负债表对账、保险估值和销货成本报告。只读——不执行任何变更操作。

主要能力

按地点和/或供应商汇总库存价值。
支持包含或排除未设置成本的商品（未设置成本的变体以 $0 计入）。
输出人类可读报告或 JSON 格式。
生成 CSV 文件，包含变体 ID、SKU、产品标题、供应商、地点、现有数量、单位成本、总价值和货币。

使用方式

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_products,read_inventory
API 权限范围：read_products、read_inventory
库存项目必须设置单位成本才能准确估值（未设置成本的变体以 $0 计入）

参数

参数	类型	必填	默认值	说明
store	string	是	—	商店域名（例如 mystore.myshopify.com）
breakdown	string	否	both	拆分级别：location、vendor 或 both
include_zero_cost	bool	否	true	是否包含未设置成本的商品（显示为 $0）
format	string	否	human	输出格式：human 或 json

工作流程

locations — 查询：获取所有活跃地点的 ID 和名称（first: 50，仅活跃地点）。
productVariants — 查询：获取所有变体的成本与库存，分页直到 hasNextPage: false（first: 250，选择 sku、inventoryQuantity、product { vendor }、inventoryItem { id, unitCost }）。
inventoryItems — 查询：按库存项目 ID 批量获取每个地点的库存水平。
计算：对每个（变体，地点）组合：价值 = 数量 × 单位成本；按地点和供应商汇总。

GraphQL 操作

# locations:query — validated against api_version 2025-01
query ActiveLocationsForValuation {
  locations(first: 50, includeInactive: false) {
    edges {
      node {
        id
        name
        isActive
      }
    }
  }
}

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

# inventoryItems:query — validated against api_version 2025-01
query InventoryLevelsByLocation($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on InventoryItem {
      id
      sku
      inventoryLevels(first: 20) {
        edges {
          node {
            location {
              id
              name
            }
            quantities(names: ["on_hand"]) {
              name
              quantity
            }
          }
        }
      }
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: Inventory Valuation Report           ║
║  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（默认）：

══════════════════════════════════════════════
INVENTORY VALUATION REPORT
  Total inventory value:  $<amount> <currency>
  SKUs included:          <n>  (of which <n> have no cost)

  By Location:
    Warehouse A          $<amount>
    Warehouse B          $<amount>

  By Vendor:
    Vendor X             $<amount>
    Vendor Y             $<amount>
  Output: inventory_valuation_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "inventory-valuation-report",
  "store": "<domain>",
  "total_value": 0,
  "currency": "USD",
  "skus_included": 0,
  "zero_cost_skus": 0,
  "by_location": [],
  "by_vendor": [],
  "output_file": "inventory_valuation_<date>.csv"
}

输出格式

CSV 文件 inventory_valuation_<YYYY-MM-DD>.csv，列包括： variant_id, sku, product_title, vendor, location, quantity_on_hand, unit_cost, total_value, currency

适用场景

月末资产负债表对账——与会计系统比较以识别差异。
保险估值——将总价值作为最低重置成本基线，如保单要求可加价零售价。
销货成本报告。
与 dead-stock-identifier 配合使用，了解库存价值中有多少被滞销库存占用。

限制

只读技能，不执行任何变更操作。
未设置成本的商品将以 $0 显示，会低估总价值。建议使用输出识别并填补成本缺口。
商店必须配置活跃地点，否则退出并报错。
API 速率限制：遇到 THROTTLED 时等待 2 秒，最多重试 3 次。

错误处理

错误	原因	恢复
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
No unit cost set	变体无成本数据	以 $0 计入，在报告中标记
No active locations	商店未配置地点	退出并报错