用途
该技能用于查询某个履约地点下所有处于 OPEN 状态的履约订单，并在单个工作流中批量创建带物流单号的履约记录。它不需要第三方应用，只负责履约创建这一层；承运商面单生成需要单独的工具或承运商集成。
主要能力
- 按地点查询所有 OPEN 状态的履约订单，支持分页（每页 250 条，直到 hasNextPage 为 false）。
- 通过 fulfillmentCreate 变更为每个履约订单创建履约记录，可附带 trackingInfo（company、number、url）。
- 支持部分履约（partial fulfillment）。
- 支持客户通知开关（notify_customer，默认 true）。
- 支持 dry_run 预览（默认 true），在真正执行前确认待履约订单列表。
- 输出 CSV 文件 fulfillment_batch_<YYYY-MM-DD>.csv，列为 order_name、fulfillment_order_id、fulfillment_id、tracking_number、carrier、notify_customer、status。
- 支持 human 或 json 两种输出格式。
使用方式
前置条件：
- 已认证的 Shopify CLI 会话：shopify store auth --store <domain> --scopes read_orders,write_fulfillments
- API 权限范围：read_orders、write_fulfillments
参数：
- store（string，必填）：店铺域名，例如 mystore.myshopify.com
- location_id（string，必填）：履约地点的 GID，例如 gid://shopify/Location/123
- tracking_numbers（array，可选，默认 []）：由 {fulfillment_order_id, tracking_number, tracking_url, carrier} 对象组成的列表
- notify_customer（bool，可选，默认 true）：是否向客户发送发货确认邮件
- dry_run（bool，可选，默认 true）：预览履约而不执行变更
- format（string，可选，默认 human）：输出格式，human 或 json
工作流步骤：
- OPERATION: fulfillmentOrders — 查询。输入 assignedLocationId、status: OPEN、first: 250 及分页游标；输出 OPEN 状态的履约订单列表，包含 id、order { name }、lineItems，并分页直到 hasNextPage 为 false。
- OPERATION: fulfillmentCreate — 变更。对每个履约订单输入 fulfillmentOrderId、trackingInfo { company, number, url }、notifyCustomer；输出 fulfillment { id, status, trackingInfo } 与 userErrors。
GraphQL 操作（已针对 api_version 2025-01 验证）：
fulfillmentOrders:query
query OpenFulfillmentOrders($locationId: ID!, $after: String) { fulfillmentOrders( assignedLocationId: $locationId first: 250 after: $after query: "status:open" ) { edges { node { id status order { id name } lineItems(first: 10) { edges { node { id remainingQuantity variant { sku title } } } } } } pageInfo { hasNextPage endCursor } } }
fulfillmentCreate:mutation
mutation FulfillmentCreate($fulfillment: FulfillmentInput!) { fulfillmentCreate(fulfillment: $fulfillment) { fulfillment { id status trackingInfo { company number url } } userErrors { field message } } }
会话跟踪：技能要求在开始、每步之后和完成时输出指定格式的进度信息。若 dry_run 为 true，每个变更步骤需加 [DRY RUN] 前缀且不执行。完成时按 format 输出 human 或 json 结果摘要。
适用场景
- 需要为某个履约地点下所有待处理订单批量创建履约记录。
- 已有物流单号，希望一次性写入并可选通知客户。
- 需要部分履约或对 B2B 订单关闭客户通知。
- 希望在执行前用 dry_run 预览待履约订单。
限制与安全
- fulfillmentCreate 不可逆：已履约订单无法通过 API 取消履约。建议先用 dry_run: true 确认列表。
- 每次变更会为每个履约订单创建一条履约记录。
- 承运商面单生成不在本技能范围内，需要单独工具或承运商集成。
- 大批量（100+ 订单）会触发速率限制，技能会自动以 2 秒退避重试。
- 未提供物流单号的订单仍会创建履约记录，需确认是否符合预期。
错误处理
- THROTTLED：API 速率超限，等待 2 秒，最多重试 3 次。
- fulfillmentCreate 的 userErrors：已履约或物流单号无效，记录错误、跳过该订单并继续。
- FULFILLMENT_ORDER_LINE_ITEM_QUANTITY_MISMATCH：部分履约数量不匹配，记录警告并尝试部分履约。
- 地点无 OPEN 订单：以摘要退出，0 个订单。
最佳实践
- 始终先以 dry_run: true 运行，因为履约无法通过 Admin API 撤销。
- 批量测试或 B2B 订单（客户不期望单独发货邮件）时传 notify_customer: false。
- 运行前在 tracking_numbers 参数中提供物流单号；无单号的未履约订单仍会创建履约记录，需确认是否有意为之。
- 大批量（100+ 订单）时变更循环会触及速率限制，技能会自动以 2 秒退避重试。