order-processing-pipeline

订单处理流水线

概述

每笔电商订单都会经历一个生命周期：已下单 → 已确认付款 → 已开始履行 → 已发货 → 已送达。Shopify、WooCommerce 和 BigCommerce 都将其实现为内置订单状态系统，并在每次状态转换时触发 Webhook 事件。目标是正确配置这些状态转换，将你的 3PL 或履行系统连接到正确的 Webhook，并在每个阶段自动执行后续操作（确认邮件、扣减库存、发送物流跟踪通知）。

只有无头商店或平台无法原生处理的复杂多步骤 B2B 工作流，才需要自定义状态机代码。

何时使用此技能

• 订单状态变得不一致时（例如，已履行的订单仍显示为待处理）
• 实现自动订单路由到 3PL 或履行服务提供商时
• 为 ERP、运输或退货集成添加订单状态 Webhook 时
• 构建自定义无头订单管理系统时

核心说明

步骤 1：了解你所用平台的订单状态和状态转换

平台	订单状态	状态转换机制
Shopify	已开启 → 部分履行 → 已履行 → 已取消；财务状态：待处理 → 已授权 → 已付款 → 已退款	Shopify 管理后台 + Webhook；由 Shopify Payments 和履行应用自动处理
WooCommerce	待处理 → 处理中 → 暂停 → 已完成 → 已取消 → 已退款 → 失败	WooCommerce 状态系统；通过管理后台、插件或 wc_update_order_status() 进行状态转换
BigCommerce	待处理 → 等待付款 → 等待履行 → 等待发货 → 已发货 → 已完成及其他状态	BigCommerce 管理后台 + Orders API Webhook
自定义 / 无头	定义你自己的状态机	通过显式的状态转换验证来构建

步骤 2：配置订单处理自动化

---

Shopify

配置付款 → 订单确认流程：

1. Shopify Payments 确认扣款后，Shopify 会自动将订单从 已开启 转为 已付款
2. 前往 Settings → Notifications，确认已启用 Order confirmation 邮件 — 付款后会自动触发此邮件
3. 对于非 Shopify 付款方式，请确认支付网关向 Shopify 发送付款成功信号；如果付款后订单仍为 待付款，请检查网关设置

为数字产品设置自动履行：

1. 前往 Settings → Shipping and delivery → Fulfillment
2. 对于数字产品，启用 Automatically fulfill the digital items in the order

连接 3PL 或履行中心：

1. 从 Shopify App Store 安装履行服务提供商的 Shopify 应用（ShipBob、ShipHero、Whiplash、Amazon FBA 等）
2. 前往 Settings → Shipping and delivery → Fulfillment services 并添加该服务
3. 该应用会订阅 Shopify 的 Order created 或 Order paid Webhook，并自动接收新订单
4. 3PL 发货后，会通过 Fulfillment API 将物流跟踪号码发送回 Shopify，由此将订单更新为 已履行，并自动发送发货确认邮件

手动履行工作流：

1. 前往 Orders → Unfulfilled 选项卡，查看所有等待履行的订单
2. 点击订单并在发货后选择 Mark as fulfilled；输入物流跟踪号码
3. 订单标记为已履行后，客户会自动收到物流跟踪邮件

为外部系统（ERP 等）设置订单 Webhook：

1. 前往 Settings → Notifications → Webhooks（或使用 Partner Dashboard 设置应用级 Webhook）
2. 添加以下 Webhook：创建订单、订单付款、订单履行、取消订单
3. 每个 Webhook 都会将完整的订单 JSON 发送到你的端点进行处理

WooCommerce

了解默认订单流程：

• Pending payment → 客户已下单，但尚未付款
• Processing → 已收到付款；正在准备订单（已付款订单的默认状态）
• Completed → 订单已送达；手动设置或由配送插件自动设置
• On hold → 付款状态不确定（例如，等待确认的银行转账）

配置自动状态转换：

1. 前往每种付款方式的 WooCommerce → Settings → Payments → [Gateway] → Order status，设置付款后的状态（即时付款方式通常设为“Processing”）
2. 对于虚拟商品或可下载商品订单，前往 WooCommerce → Settings → Products → Downloadable products，并启用“Grant access to downloadable products after payment”，使订单自动变为“Completed”

连接配送/履约插件：

1. 安装配送插件：WooCommerce ShipStation、WooCommerce ShipBob 或 ELEX WooCommerce DHL/FedEx/UPS
2. 配置插件，拉取状态为“Processing”的订单以进行履约
3. 插件发出订单并获取追踪号码后，会自动将订单状态更新为“Completed”并发送追踪邮件

通过钩子自定义状态转换：

// In functions.php or a custom plugin — auto-complete virtual orders
add_action('woocommerce_payment_complete', 'auto_complete_virtual_orders');
function auto_complete_virtual_orders($order_id) {
    $order = wc_get_order($order_id);
    if ($order && $order->get_status() === 'processing') {
        $all_virtual = true;
        foreach ($order->get_items() as $item) {
            $product = $item->get_product();
            if (!$product->is_virtual()) { $all_virtual = false; break; }
        }
        if ($all_virtual) {
            $order->update_status('completed', 'All virtual items — auto-completed.');
        }
    }
}

订单 Webhook： 安装 WooCommerce Webhooks（内置），然后前往 WooCommerce → Settings → Advanced → Webhooks，为订单创建、更新和删除事件添加 Webhook。

BigCommerce

配置订单状态流程：

1. 前往 Orders → View。BigCommerce 会在付款确认后自动将订单设为 Awaiting Fulfillment
2. 配置付款网关的订单状态映射：前往 Settings → Payment Methods → [Gateway]，设置付款后的状态

连接履约服务商：

1. 前往 BigCommerce App Marketplace，安装履约中心的应用（ShipBob、ShipStation 等）
2. 该应用会连接 BigCommerce 的订单 Webhook 并自动拉取新订单
3. 3PL 发货后，会通过 Orders API 更新 BigCommerce，设置追踪号码并将状态改为 Shipped

订单 Webhook： 前往 Settings → Advanced Settings → WebHooks，为订单状态变更添加 Webhook。ERP 和会计系统等集成会使用这些 Webhook。

---

自定义 / 无头架构

对于自定义店面，应实现状态机并明确验证状态转换：

// Valid order state transitions
const VALID_TRANSITIONS = {
  pending:    ['confirmed', 'cancelled'],
  confirmed:  ['processing', 'cancelled'],
  processing: ['shipped', 'cancelled'],
  shipped:    ['delivered', 'returned'],
  delivered:  ['returned', 'refunded'],
  cancelled:  ['refunded'],
};

async function transitionOrder(orderId, newStatus, metadata = {}) {
  return db.$transaction(async (tx) => {
    const order = await tx.orders.findUnique({ where: { id: orderId } });

    if (!VALID_TRANSITIONS[order.status]?.includes(newStatus)) {
      throw new Error(`Invalid transition: ${order.status} → ${newStatus}`);
    }

    const updated = await tx.orders.update({
      where: { id: orderId },
      data: { status: newStatus, [`${newStatus}At`]: new Date() },
    });

    // Append-only event log for audit trail
    await tx.orderEvents.create({
      data: { orderId, fromStatus: order.status, toStatus: newStatus, triggeredBy: metadata.triggeredBy ?? 'system' },
    });

    return updated;
  });
}

// Wire to Stripe webhook — payment confirmation drives the transition
async function onPaymentSucceeded(paymentIntent) {
  const orderId = paymentIntent.metadata.order_id;
  const order = await db.orders.findUnique({ where: { id: orderId } });

  // Idempotency — ignore if already confirmed
  if (order.status !== 'pending') return;

  await transitionOrder(orderId, 'confirmed', { triggeredBy: 'stripe_webhook' });
  await sendOrderConfirmationEmail(orderId);
  await deductInventory(orderId);
}

每次状态转换时的副作用（在数据库事务之外运行，以避免阻塞）：

• confirmed：发送确认邮件、扣减库存、通知履约服务商
• shipped：发送包含追踪号码的配送邮件，在客户门户中更新追踪信息
• delivered：发送送达确认，安排在 3 天后发送评价请求
• cancelled：释放库存预留；如果已付款则发起退款；发送取消邮件

步骤 3：处理最常见的边缘情况

重复投递 Webhook： 所有主要支付处理商都可能多次投递同一个 Webhook。处理状态转换前，务必检查当前订单状态：

if (order.status !== 'pending') return; // Already processed

扣减库存的时机： 仅在付款确认后（即 confirmed 状态转换时）扣减库存，而不是在下单时扣减。如果付款失败，不应让库存一直被预留。

部分履约时取消订单： 如果部分商品已发货，其他商品尚未发货，各平台的处理方式会有所不同。在 Shopify 上，可以仅取消尚未履约的订单项，同时保留已履约的商品。在 WooCommerce 上，安装 WooCommerce Cancel Abandoned Order，或通过 WooCommerce REST API 进行管理。

最佳实践

• 使用平台原生订单管理 — Shopify、WooCommerce 和 BigCommerce 能正确处理付款 → 履约 → 配送的核心流程；应基于它们进行构建，而不是取而代之
• 将履约应用连接到正确的状态触发条件 — 履约服务商应在确认付款后接收订单（Shopify 上为 order.paid，WooCommerce 上为 Processing），而不是在创建订单时接收
• 记录每次状态变更 — 即使使用平台，也应添加订单备注（Shopify 和 WooCommerce 均支持），或记录数据库事件以供审计
• 处理 Webhook 的幂等性 — 应用 Webhook 触发的状态变更前，务必检查当前订单状态
• 为外部集成发送 Webhook — 为所有订单状态变更配置 Webhook，确保 ERP、会计和 CRM 集成保持同步

常见问题

问题	解决方案
Shopify 因 Webhook 重复而重复确认订单	Shopify 会通过幂等性标头进行去重；在你这边，处理前检查 order.financial_status !== 'paid'
PayPal 付款后 WooCommerce 订单仍卡在“Pending payment”状态	必须在 PayPal 账户中启用 PayPal IPN（即时付款通知）；在 WooCommerce → Settings → Payments → PayPal 中检查 IPN URL
只有手动完成订单后才会扣减库存	将库存扣减移至付款确认 Webhook，而不是履约 Webhook
3PL 未自动收到新订单	确认履约应用已订阅正确的订单状态 — 大多数 3PL 应用会拉取“Processing”（WooCommerce）或“Unfulfilled + Paid”（Shopify）状态的订单
订单状态 Webhook 未触发	检查 Shopify → Settings → Notifications → Webhooks 或 WooCommerce → Settings → Advanced → Webhooks 中的 Webhook 注册情况，并确认端点返回 200

相关技能

• @stripe-integration
• @inventory-tracking
• @subscription-billing
• @guest-checkout