用途
该技能用于将一个含多个行项目的履约单拆分成两个或更多独立履约单，使它们可以分别发货、分别使用追踪号。适用于订单内商品从不同地点发出、在不同日期发货或需要不同承运商的场景，用于替代 Shopify Admin 中的手动拆分发货操作。
前置条件
需要已认证的 Shopify CLI 会话，命令为：shopify store auth --store <domain> --scopes read_orders,write_fulfillments。
所需 API 权限范围：read_orders、write_fulfillments。
目标履约单必须处于 OPEN 状态。
参数
store：字符串，必填，无默认值，店铺域名（例如 mystore.myshopify.com）。 fulfillment_order_id：字符串，必填，无默认值，要拆分的履约单 GID。 split_groups：数组，必填，无默认值，由 {line_item_ids: [], quantities: []} 组成的列表，用于定义每个发货分组。 dry_run：布尔值，非必填，默认 true，用于在不执行 mutation 的情况下预览拆分。 format：字符串，非必填，默认 human，输出格式可选 human 或 json。
安全性
fulfillmentOrderSplit 不可逆，已拆分的履约单无法合并回原状，原履约单会被多个新履约单替代。建议先用 dry_run: true 确认分组意图后再提交。需确保 split_groups 中的所有 line_item_ids 都属于目标履约单。
工作流程
- 执行 fulfillmentOrders 查询：按订单 ID 查询指定履约单，并按 status: OPEN 过滤。预期输出为包含所有 lineItems 的履约单，字段为 { id, remainingQuantity, variant { sku, title } }。
- 校验 split_groups：确认所有行项目 ID 都存在于该履约单中，且数量不超过剩余数量。
- 执行 fulfillmentOrderSplit mutation：入参为 fulfillmentOrderId 以及每个分组对应的 fulfillmentOrderLineItems 数组。预期输出为新的 fulfillmentOrders 数组 { id, lineItems } 以及 userErrors。
GraphQL 操作
源码中包含两个已针对 api_version 2025-01 校验的操作，保持不变如下：
fulfillmentOrders:query — validated against 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 } } } } } } } } }
fulfillmentOrderSplit:mutation — validated against 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 } } }
会话追踪
技能要求在每一阶段输出指定信息。开始时输出带边框的会话信息，包含技能名 Split Shipment Planner、店铺域名与开始时间（YYYY-MM-DD HH:MM UTC）。每完成一步后输出：[N/TOTAL] <QUERY|MUTATION> <OperationName>，并附带参数简要说明与结果数量或结果。若 dry_run: true，则每个 mutation 步骤前加前缀 [DRY RUN] 且不执行。完成时，若 format 为 human（默认），输出 OUTCOME SUMMARY，包含原履约单 id、拆分为几个发货、错误数以及各 shipment 的行项目摘要；若 format 为 json，则输出包含 skill、store、started_at、completed_at、dry_run、original_fulfillment_order_id、resulting_fulfillment_orders、errors 的 JSON 对象。
输出格式
输出为人类可读的拆分摘要。不提供 CSV 输出，拆分结果可在 Shopify Admin 订单的履约标签页中查看。
错误处理
THROTTLED：API 速率超限，等待 2 秒后重试。userErrors — invalid line item：行项目 ID 不在该履约单中，终止并报告不匹配。userErrors — quantity exceeds remaining：拆分数量大于剩余数量，终止并按行项目报告。Fulfillment order not OPEN：已履约或已取消，终止并输出状态报告。
最佳实践
在拆分前使用 dry_run: true 预览将要生成的发货分组，因为拆分无法撤销。确保 split_groups 覆盖履约单中的所有行项目，任何未分配的项目会保留在原（剩余）履约单中。对于商品从不同仓库发出的订单，可在拆分后使用 fulfillment-location-routing 技能将各拆分分组移动到正确的地点。