shopify-admin-high-risk-order-tagger

用途

该技能查询近期的高风险订单，并执行两种保护性操作：为订单添加标签以便员工可见，以及可选地设置履约保留，防止订单在审核前发货。它与仅做读取的 order-risk-report 技能互补，通过写入操作创建一个可审核的队列。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
days_back	integer	否	1	回溯窗口（默认：最近 24 小时）
min_order_value	float	否	0	仅标记高于此金额的订单
tag	string	否	fraud-review	应用于被标记订单的标签
hold_fulfillment	bool	否	true	是否同时对被标记订单设置履约保留
hold_reason	string	否	UNKNOWN_PAYMENT_RISK	履约保留原因
dry_run	bool	否	true	仅预览，不执行变更
format	string	否	human	输出格式：human 或 json

安全提示

⚠️ fulfillmentOrderHold 会阻止订单被履约，直到保留被显式释放。客户在保留期间将经历发货延迟。如果只想添加标签而不阻止履约，请使用 hold_fulfillment: false。使用 dry_run: true 在提交前确认订单列表。审核后可使用 order-hold-and-release 技能释放保留。

工作流程步骤

OPERATION: orders — 查询
- 输入：query: "risk_level:high created_at:>='<NOW - days_back days>'", first: 250, select riskLevel, fulfillmentOrders, totalPriceSet
- 预期输出：窗口内的高风险订单
OPERATION: tagsAdd — 变更
- 输入：Order id, tags: [<tag>]
- 预期输出：更新后的订单标签；userErrors
OPERATION: fulfillmentOrderHold — 变更（如果 hold_fulfillment: true）
- 输入：fulfillmentOrderId, reason: <hold_reason>, reasonNotes: "High-risk order — awaiting fraud review"
- 预期输出：heldFulfillmentOrder { id, status }, userErrors

GraphQL 操作

# orders:query — validated against api_version 2025-01
query HighRiskOrders($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        name
        riskLevel
        totalPriceSet {
          shopMoney {
            amount
            currencyCode
          }
        }
        tags
        fulfillmentOrders(first: 5) {
          edges {
            node {
              id
              status
            }
          }
        }
        customer {
          id
          displayName
          numberOfOrders
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# tagsAdd:mutation — validated against api_version 2025-01
mutation TagsAdd($id: ID!, $tags: [String!]!) {
  tagsAdd(id: $id, tags: $tags) {
    node {
      id
    }
    userErrors {
      field
      message
    }
  }
}

# fulfillmentOrderHold:mutation — validated against api_version 2025-01
mutation FulfillmentOrderHold($id: ID!, $fulfillmentHold: FulfillmentOrderHoldInput!) {
  fulfillmentOrderHold(id: $id, fulfillmentHold: $fulfillmentHold) {
    fulfillmentOrder {
      id
      status
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: High Risk Order Tagger               ║
║  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>

如果 dry_run: true，在每个变更步骤前加上 [DRY RUN] 前缀，并且不执行它。

完成时输出：

对于 format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  High-risk orders found:  <n>
  Orders tagged:           <n>
  Fulfillment holds placed: <n>
  Errors:                  <n>
  Output:                  risk_tagging_<date>.csv
══════════════════════════════════════════════

对于 format: json，输出：

{
  "skill": "high-risk-order-tagger",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "dry_run": true,
  "outcome": {
    "orders_found": 0,
    "tagged": 0,
    "holds_placed": 0,
    "errors": 0,
    "output_file": "risk_tagging_<date>.csv"
  }
}

输出格式

CSV 文件 risk_tagging_<YYYY-MM-DD>.csv，包含列： order_name, order_id, risk_level, total_price, currency, tag_applied, hold_placed, customer_name

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒，最多重试 3 次
userErrors on hold	订单已履约或保留已存在	记录为跳过，继续
No high-risk orders	无风险期间	以 0 标记退出

最佳实践

在订单下达后 1–2 小时内运行——大多数欺诈订单会在当天被下达并期望发货。
设置保留后，使用 order-risk-report 详细审查风险指标，再决定取消或释放。
使用 order-hold-and-release 技能释放合法订单，以尽量减少发货延迟。
回头客（numberOfOrders > 3）的订单不太可能是欺诈性的——考虑通过 min_order_value 或单独查询将其过滤掉。