用途
基于每个 SKU 的历史销售速度、趋势分析以及可选的季节调整，预测未来需求。计算补货点（何时下单）和建议补货数量（下单多少），并计入供应商交货周期与安全库存。该技能为只读操作，不执行任何数据变更。
前置条件
已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,read_products,read_inventory
API 权限范围：read_orders、read_products、read_inventory
参数
- store（string，必填）：店铺域名
- days_back（integer，可选，默认 90）：用于计算销售速度的历史销售窗口
- forecast_days（integer，可选，默认 30）：需要预测需求的天数
- lead_time_days（integer，可选，默认 14）：默认供应商交货周期（天）
- safety_stock_days（integer，可选，默认 7）：额外的安全库存缓冲天数
- vendor_filter（string，可选）：限定到特定供应商
- only_low_stock（boolean，可选，默认 false）：仅显示预计在预测窗口内售罄的商品
- format（string，可选，默认 human）：输出格式，human 或 json
安全性
ℹ️ 只读技能 — 不执行任何变更操作，可随时安全运行。
工作流程
- 查询订单：输入查询条件 created_at:>='<NOW - days_back days>'，每页 250 条，获取 createdAt、lineItems { variant { id }, quantity }，使用分页游标；预期输出为用于计算销售速度的全部订单及行项目。
- 计算每个变体的销售速度：
- 每日销售率 = 总售出单位数 / days_back
- 周趋势：比较最近 30 天与前 30 天，判断趋势方向
- 预测需求 = 每日销售率 × forecast_days × 趋势乘数
- 查询 productVariants：输入所有有销售历史的变体 ID，每页 250 条，使用分页游标；预期输出为变体详情（SKU、标题、产品标题、供应商）。
- 查询 inventoryLevels：输入有库存变体的库存项目 ID；预期输出为各位置的当前可用数量。
- 计算补货指标：
- 库存天数 = 当前库存 / 每日销售率
- 补货点 = (lead_time_days + safety_stock_days) × 每日销售率
- 补货数量 = forecast_days × 每日销售率 + 安全库存 - 当前库存
- 缺货日期 = 今天 + (当前库存 / 每日销售率) 天
- 下单截止日期 = 缺货日期 - lead_time_days
- 按紧急程度排序：最接近缺货的商品排在最前。
GraphQL 操作
代码内容保持原样：
orders:query — validated against api_version 2025-01
query SalesHistory($query: String!, $after: String) { orders(first: 250, after: $after, query: $query) { edges { node { createdAt lineItems(first: 50) { edges { node { quantity variant { id } } } } } } pageInfo { hasNextPage endCursor } } }
productVariants:query — validated against api_version 2025-01
query VariantInfo($ids: [ID!]!) { nodes(ids: $ids) { ... on ProductVariant { id sku title product { id title vendor } inventoryQuantity inventoryItem { id } } } }
inventoryItems:query — validated against api_version 2025-01
query InventoryItemDetails($ids: [ID!]!) { nodes(ids: $ids) { ... on InventoryItem { id unitCost { amount currencyCode } tracked inventoryLevels(first: 10) { edges { node { quantities(names: ["available"]) { name quantity } location { id name } } } } } } }
inventoryLevels:query — validated against api_version 2025-01
query LocationInventory($locationId: ID!, $after: String) { location(id: $locationId) { inventoryLevels(first: 250, after: $after) { edges { node { quantities(names: ["available"]) { name quantity } item { id variant { id sku product { title } } } } } pageInfo { hasNextPage endCursor } } } }
会话跟踪
Claude 必须在每个阶段输出以下内容，此为强制要求。
开始时输出：
╔══════════════════════════════════════════════╗ ║ SKILL: Demand Forecast & Reorder Planner ║ ║ 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（默认）时：
══════════════════════════════════════════════ DEMAND FORECAST & REORDER PLAN (<days_back>d history → <forecast_days>d forecast) SKUs analyzed: <n> Avg daily velocity: <n> units/day ───────────────────────────── ⚠️ URGENT (stockout <7 days): "<product>" SKU:<sku> Stock:<n> Days left:<n> ORDER BY: <date> Reorder qty: <n> units Est. cost: $<n>
⏰ PLAN AHEAD (stockout 7-30 days): "<product>" SKU:<sku> Stock:<n> Days left:<n> ORDER BY: <date>
✅ HEALTHY (>30 days stock): <n> SKUs with adequate stock
Output: reorder_plan_<date>.csv ══════════════════════════════════════════════
format 为 json 时输出：
{ "skill": "demand-forecast-reorder", "store": "<domain>", "history_days": 90, "forecast_days": 30, "lead_time_days": 14, "skus_analyzed": 0, "urgent_reorders": [], "planned_reorders": [], "healthy_skus": 0, "output_file": "reorder_plan_<date>.csv" }
输出格式
CSV 文件 reorder_plan_<YYYY-MM-DD>.csv，包含以下列：variant_id、sku、product_title、vendor、current_stock、daily_velocity、trend、days_of_stock、stockout_date、reorder_point、reorder_qty、order_by_date、est_cost。
错误处理
- THROTTLED：API 限流，等待 2 秒后重试，最多 3 次
- 销售速度为零：商品在窗口期内从未售出，跳过并标记为“无需求数据”
- 无库存跟踪：变体未启用跟踪，跳过，无法预测未跟踪商品
最佳实践
- 尽可能按供应商设置 lead_time_days；默认 14 天较为保守。
- 对高价值或发货缓慢的商品使用 safety_stock_days: 14。
- 每周运行一次，并将输出接入采购订单工作流。
- 可与 stock-velocity-report 交叉验证销售速度。
- 可配合 dead-stock-identifier 使用，避免补货滞销商品。
- 对于季节性商品，使用更长的 days_back（180-365）以捕捉季节性模式。