revenue-by-location-report

用途

将订单收入归因到实际发货的履约地点（仓库或履约中心），生成按地点拆分的收入报表。适用于多地点损益（P&L）分析、地点人员配置决策，以及了解需求正在从哪个地点被履约。该技能为只读，不执行任何变更操作。

主要能力

查询活跃履约地点（最多 50 个），获取地点 ID 与名称用于数据丰富。
查询已发货订单（fulfillment_status:shipped），按创建时间回溯指定天数，提取履约记录中的 assignedLocation 与订单金额。
针对未结订单，按地点查询状态为 CLOSED 的履约订单，用于收入归因。
按地点聚合收入；无地点数据的订单归入 "Unknown" 或 "Unassigned"。
输出 CSV 文件，包含 location_id、location_name、order_count、total_revenue、currency、share_pct 列。
支持 human 与 json 两种输出格式。

使用方式

前置条件：

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

参数：

store（字符串，必填）：商店域名，例如 mystore.myshopify.com
days_back（整数，可选，默认 30）：回溯窗口天数
format（字符串，可选，默认 human）：输出格式，human 或 json

工作流程：

查询 locations（first: 50，仅活跃），获取地点 ID 与名称。
查询 orders，条件为 fulfillment_status:shipped created_at:>='<NOW - days_back days>'，first: 250，选取 fulfillments { assignedLocation }、totalPriceSet 及分页游标。
针对未结订单归因，按地点查询 fulfillmentOrders（status: CLOSED，first: 250）。
按地点聚合收入；无地点数据的订单归入 "Unknown"。

GraphQL 操作（已针对 api_version 2025-01 验证）：

# locations:query
query LocationsList {
  locations(first: 50, includeInactive: false) {
    edges {
      node {
        id
        name
      }
    }
  }
}

# orders:query
query RevenueByLocation($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        createdAt
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        fulfillments {
          assignedLocation {
            location {
              id
              name
            }
          }
          status
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# fulfillmentOrders:query
query ClosedFulfillmentOrders($locationId: ID!, $after: String) {
  fulfillmentOrders(
    assignedLocationId: $locationId
    first: 250
    after: $after
    query: "status:closed"
  ) {
    edges {
      node {
        id
        order {
          id
          name
          totalPriceSet {
            shopMoney {
              amount
              currencyCode
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

输出格式

human 格式（默认）示例：

══════════════════════════════════════════════
REVENUE BY LOCATION  (<days_back> days)
  Total revenue:   $<amount>
  Orders included: <n>

  Location                Orders   Revenue    Share
  ─────────────────────────────────────────────────
  Warehouse A             <n>      $<n>       <pct>%
  Warehouse B             <n>      $<n>       <pct>%
  Output: revenue_by_location_<date>.csv
══════════════════════════════════════════════

json 格式示例：

{
  "skill": "revenue-by-location-report",
  "store": "<domain>",
  "period_days": 30,
  "total_revenue": 0,
  "currency": "USD",
  "by_location": [],
  "output_file": "revenue_by_location_<date>.csv"
}

CSV 文件名为 revenue_by_location_<YYYY-MM-DD>.csv，列包括：location_id, location_name, order_count, total_revenue, currency, share_pct。

适用场景

多 3PL 运营：识别某个 3PL 是否承担了不成比例的份额，可能需要产能缓解。
多地点损益分析：按仓库或履约中心查看收入贡献。
地点人员配置决策：了解各地点实际履约吞吐量。
与库存估值报表配合，计算各地点库存周转率（收入 / 库存价值）。

限制与注意事项

收入归因基于履约分配，而非客户收货地址，反映的是各地点运营吞吐量，不是地理需求。
无履约地点的订单（未履约或 POS 订单）归入 "Unassigned"。
单地点商店：所有收入来自一个地点，报表仍然有效，显示完整总额。
错误处理：THROTTLED（API 速率限制）时等待 2 秒，最多重试 3 次。
该技能为只读，不执行任何变更操作，可随时安全运行。

会话跟踪

Claude 必须在每个阶段输出指定内容。开始时输出技能名称、商店域名和启动时间；每步之后输出步骤编号、操作类型、操作名称、参数摘要和结果；完成时按所选格式输出最终报表。