split-shipment-planner

用途

Split Shipment Planner 用于将一个包含多个行项目的履约订单（fulfillment order）拆分为两个或多个独立的履约订单，每个拆分后的订单都可以单独发货，并拥有各自的物流追踪号。它适用于以下场景：订单中的商品需要从不同地点发货、在不同日期发货，或需要不同承运商。该技能替代了在 Shopify 后台手动处理拆分发货的操作。

主要能力

查询指定订单的履约订单及其行项目信息（包括行项目 ID、剩余数量、总数量、SKU、标题等）。
根据用户定义的拆分分组（split_groups），将履约订单拆分为多个独立履约订单。
支持 dry_run 预览模式，在真正执行拆分前确认分组方案。
支持 human 和 json 两种输出格式。
提供会话跟踪输出，在每个阶段输出操作进度与结果。

使用方式

前置条件

已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,write_fulfillments
API 权限范围：read_orders、write_fulfillments
目标履约订单必须处于 OPEN 状态

参数

参数	类型	必填	默认值	说明
store	string	是	—	店铺域名（例如 mystore.myshopify.com）
fulfillment_order_id	string	是	—	要拆分的履约订单 GID
split_groups	array	是	—	定义每个发货分组的列表，格式为 {line_item_ids: [], quantities: []}
dry_run	bool	否	true	预览拆分而不执行变更
format	string	否	human	输出格式：human 或 json

工作流程

查询履约订单（OPERATION: fulfillmentOrders）：按订单 ID 查询特定履约订单，筛选状态为 OPEN，获取所有行项目信息（id、remainingQuantity、variant 的 sku 与 title）。
校验 split_groups：确认所有行项目 ID 均存在于该履约订单中，且数量不超过剩余数量。
执行拆分（OPERATION: fulfillmentOrderSplit）：传入 fulfillmentOrderId 和每个拆分组的 fulfillmentOrderLineItems，返回新的履约订单数组及 userErrors。

GraphQL 操作

查询（针对 api_version 2025-01 验证）：

query FulfillmentOrderLines($orderId: ID!) {
  order(id: $orderId) {
    id
    name
    fulfillmentOrders(first: 10) {
      edges {
        node {
          id
          status
          lineItems(first: 50) {
            edges {
              node {
                id
                remainingQuantity
                totalQuantity
                variant {
                  id
                  sku
                  title
                }
              }
            }
          }
        }
      }
    }
  }
}

变更（针对 api_version 2025-01 验证）：

mutation FulfillmentOrderSplit($fulfillmentOrderId: ID!, $fulfillmentOrderLineItems: [FulfillmentOrderLineItemInput!]!) {
  fulfillmentOrderSplit(
    fulfillmentOrderId: $fulfillmentOrderId
    fulfillmentOrderLineItems: $fulfillmentOrderLineItems
  ) {
    fulfillmentOrders {
      id
      status
      lineItems(first: 50) {
        edges {
          node {
            id
            remainingQuantity
            variant {
              sku
              title
            }
          }
        }
      }
    }
    userErrors {
      field
      message
    }
  }
}

会话跟踪

技能在每个阶段必须输出跟踪信息。启动时输出包含技能名称、店铺域名和开始时间的横幅；每步之后输出步骤编号、操作类型、操作名称、参数摘要和结果；若 dry_run 为 true，每个变更步骤前加 [DRY RUN] 前缀且不执行；完成时按 human 或 json 格式输出结果摘要。

适用场景

订单商品需从不同仓库或地点发货。
订单商品需在不同日期发货。
订单商品需使用不同承运商。
需要为同一订单的不同部分生成独立物流追踪号。

限制与安全注意事项

⚠️ fulfillmentOrderSplit 不可逆：拆分后的履约订单无法合并回原订单，原履约订单会被多个新订单取代。建议先以 dry_run: true 运行，确认分组方案后再提交。
确保 split_groups 中的所有 line_item_ids 都属于目标履约订单。
建议确保 split_groups 覆盖履约订单中的所有行项目；任何未分配的项目将保留在原（剩余）履约订单中。
对于商品需从不同仓库发货的订单，可在拆分后使用 fulfillment-location-routing 技能将拆分组移动到正确的地点。

错误处理

错误	原因	恢复方式
THROTTLED	API 速率限制超出	等待 2 秒后重试
userErrors — invalid line item	行项目 ID 不在履约订单中	中止并报告不匹配
userErrors — quantity exceeds remaining	拆分数量大于剩余数量	中止并按行项目报告
Fulfillment order not OPEN	已履约或已取消	中止并报告状态

输出格式

人类可读的拆分摘要。无 CSV 输出——拆分结果可在 Shopify 后台订单的履约标签页中查看。