shopify-admin-cogs-completeness-audit

用途

该技能扫描店铺目录中的每个变体，找出 inventoryItem.unitCost 缺失或为零的变体。销货成本（COGS）是利润报告、基于利润的定价决策和库存估值的基础——单个缺失的成本会静默地破坏所有下游计算。该技能为只读操作，不执行任何变更。

主要能力

查询所有匹配的变体，支持按产品状态（ACTIVE、DRAFT、ARCHIVED、ALL）和供应商筛选。
批量查询库存项目的 unitCost 信息。
筛选出 unitCost 为 null 或金额为 0 的变体（当 include_zero_cost 为 true 时）。
计算缺失成本变体的潜在利润缺口（价格 - 0 = 价格），即下游报告将显示的虚构利润。
汇总缺失数量、占目录百分比、总库存价值影响（缺失行中 inventoryQuantity * price 的总和）。
输出人类可读摘要或 JSON，并生成 CSV 文件。

使用方式

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
status_filter	string	否	ACTIVE	要审计的变体产品状态：ACTIVE、DRAFT、ARCHIVED 或 ALL
vendor_filter	string	否	—	可选的供应商，用于限定审计范围
include_zero_cost	bool	否	true	将 unitCost = 0 视为缺失（推荐；零成本很少是有意为之）
only_stocked	bool	否	true	仅限 inventoryQuantity > 0 的变体
format	string	否	human	输出格式：human 或 json

工作流程

使用 productVariants 查询获取所有匹配的变体，分页直到 hasNextPage: false。
使用 inventoryItems 查询批量获取库存项目的 unitCost（每批最多 100 个 ID）。
筛选出 unitCost 为 null 或金额为 0 的变体（当 include_zero_cost 为 true 时）。计算潜在利润缺口。
汇总：缺失数量、占目录百分比、总库存价值影响。

GraphQL 操作

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

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

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: COGS Completeness 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（默认）：

══════════════════════════════════════════════
COGS COMPLETENESS AUDIT
  Variants audited:        <n>
  Missing unit cost:       <n>  (<pct>%)
  Stocked + missing cost:  <n>
  Catalog value at risk:   $<amount> (priced, not costed)

  Top vendors by missing variants:
    <vendor>  Missing: <n>  Stocked: <n>
  Output: cogs_audit_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "cogs-completeness-audit",
  "store": "<domain>",
  "variants_audited": 0,
  "missing_cost": 0,
  "missing_cost_pct": 0,
  "stocked_missing": 0,
  "value_at_risk": 0,
  "currency": "USD",
  "output_file": "cogs_audit_<date>.csv"
}

输出格式

CSV 文件 cogs_audit_<YYYY-MM-DD>.csv，包含列： variant_id, inventory_item_id, sku, product_title, vendor, product_status, price, unit_cost, inventory_quantity, value_at_price, currency

错误处理

错误	原因	恢复
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
inventoryItem is null	变体没有库存项目（罕见）	跳过，在错误计数中记录
unitCost.currencyCode 与店铺货币不同	多货币成本捕获	视为存在；不标记，单独显示货币不匹配
所有变体都有成本	健康目录	退出并显示摘要：0 缺失，100% 完整

适用场景

每月运行一次；每当有新供应商或产品线上线时，在激活第一天运行，以便在利润报告被信任之前发现缺失成本。
按 vendor_filter 筛选，将修复工作分配给负责该供应商数据的采购员。
与 inventory-valuation-report 配合使用——除非此审计干净，否则该报告会静默地将缺失成本的 SKU 视为无价值库存。
默认将 unitCost = 0 视为缺失。真正的零成本 SKU（免费样品、赠品）很少见；用 zero-cost-intentional 产品标签标记这些，并通过 vendor_filter 或下游过滤将其排除在审计之外。
将 CSV 用作工作清单：交给商品团队进行成本捕获，然后每周重新运行，直到缺失数量为零。

限制

只读技能，不执行任何变更。该技能标记缺失数据；修复应通过您控制的后续工作流进行。
需要已认证的 Shopify CLI 会话和 read_products、read_inventory 权限范围。
其他限制暂未提供。