shopify-admin-address-correction

用途

该技能用于更正未履约订单的收货地址，无需通过 Shopify 后台界面导航操作。当客户在下单后提供更正信息（例如街道地址拼写错误或邮政编码错误）时，此技能非常有用。它通过 Admin API 直接执行地址更新，替代 Shopify 后台中手动编辑地址的流程。更新必须在订单履约之前执行；如果订单已履约或部分履约，该技能会报错中止。一旦开始履约，Shopify 订单记录便无法通过此技能更新。

前置条件

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

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
format	string	否	human	输出格式：human 或 json
dry_run	bool	否	false	预览操作而不执行变更
order_id	string	是	—	订单的 GID（例如 gid://shopify/Order/12345）
new_address	object	是	—	新收货地址：address1、address2（可选）、city、province、country、zip、phone（可选）、first_name、last_name

安全说明

⚠️ 第 2 步执行 orderUpdate，会立即更改记录中的收货地址。如果订单已在履约合作方处，需另行通知他们——此技能仅更新 Shopify 记录。如果 displayFulfillmentStatus 不是 UNFULFILLED，此技能会报错中止。地址更改不能应用于部分或完全履约的订单。

工作流步骤

步骤 1：OPERATION: order — query

输入：id: <order_id>
预期输出：订单名称、displayFulfillmentStatus、当前 shippingAddress；如果 displayFulfillmentStatus != "UNFULFILLED"，则以消息中止："Cannot update address: order has already been fulfilled."

步骤 2：OPERATION: orderUpdate — mutation

输入：input.id: <order_id>、input.shippingAddress: <new_address object>
预期输出：订单上更新后的 shippingAddress、userErrors

GraphQL 操作

# order:query — validated against api_version 2025-01
query OrderForAddressCheck($id: ID!) {
  order(id: $id) {
    id
    name
    displayFulfillmentStatus
    shippingAddress {
      address1
      address2
      city
      province
      country
      zip
      phone
      firstName
      lastName
    }
  }
}

# orderUpdate:mutation — validated against api_version 2025-01
mutation OrderUpdate($input: OrderInput!) {
  orderUpdate(input: $input) {
    order {
      id
      shippingAddress {
        address1
        address2
        city
        province
        country
        zip
        phone
      }
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

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

开始时输出：

╔══════════════════════════════════════════════╗
║  SKILL: address-correction                   ║
║  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，则为每个 mutation 步骤添加 [DRY RUN] 前缀，且不执行该步骤。

完成时输出：

format: human（默认）：

══════════════════════════════════════════════
OUTCOME SUMMARY
  Order:          <name>
  Address updated: yes
  Errors:          0
  Output:          none
══════════════════════════════════════════════

format: json：

{
  "skill": "address-correction",
  "store": "<domain>",
  "started_at": "<ISO8601>",
  "completed_at": "<ISO8601>",
  "dry_run": false,
  "steps": [
    { "step": 1, "operation": "OrderForAddressCheck", "type": "query", "params_summary": "order_id: <id>", "result_summary": "UNFULFILLED, address confirmed", "skipped": false },
    { "step": 2, "operation": "OrderUpdate", "type": "mutation", "params_summary": "order_id: <id>, new_address: <summary>", "result_summary": "address updated", "skipped": false }
  ],
  "outcome": {
    "order_name": "<name>",
    "address_updated": true,
    "errors": 0,
    "output_file": null
  }
}

输出格式

无 CSV 输出。该技能在会话完成摘要中报告更新后的地址。新地址显示在 [2/2] 步骤输出中。

错误处理

错误	原因	恢复方式
displayFulfillmentStatus != UNFULFILLED	订单已履约或部分履约	无法更新地址；请直接联系承运商
来自 orderUpdate 的 userErrors	地址字段无效（例如国家代码无效）	验证 ISO 国家代码及省/州格式
Order not found	订单 GID 无效	使用 order-lookup-and-summary 技能查找正确的订单 ID

最佳实践

始终先运行 dry_run: true——步骤 1 会显示当前地址以供确认，然后再由步骤 2 提交更改。
国家必须使用 ISO 3166-1 alpha-2 代码（例如 US、CA、GB）——而非完整国家名称。
此技能仅更新 Shopify 订单记录。如果使用第三方履约服务商，还需在他们的系统中更新地址。
电话字段请使用 E.164 格式（例如 +15551234567）。
更新后，使用 order-lookup-and-summary 技能确认地址更改已生效。