如何让WooCommerce插件支持离线使用并在联网后自动同步订单

核心实现逻辑 #

依托浏览器端PWA能力实现离线数据存储，网络恢复后批量推送至WooCommerce系统，核心依赖三个技术点：Service Worker缓存静态资源、IndexedDB存储待同步订单、网络状态监听触发同步动作。

具体实现步骤 #

1. 前端离线能力改造 #

• 给POS前端注册Service Worker，提前缓存下单所需的所有静态资源：商品SKU、售价、库存快照、已登录用户信息，每次联网时自动更新本地缓存的基础数据，避免离线下单时数据偏差
• 修改下单逻辑增加网络状态判断，断网场景下将完整订单数据（包含唯一客户端订单标识client_order_key、商品明细、金额、用户ID、下单时间戳）写入IndexedDB的pending_orders表，同时给用户弹出离线订单已保存，联网后将自动同步的提示
• 全局绑定网络状态监听事件，网络恢复后自动读取IndexedDB内所有待同步订单，按生成时间顺序依次上传；每次POS页面加载时也主动触发一次待同步订单校验，避免断网时关闭页面导致的订单遗漏

参考代码示例：

// 离线订单存储逻辑
if (!navigator.onLine) {
  // 生成唯一客户端订单号用于后端去重
  const clientOrderKey = `offline_${Date.now()}_${currentWpUser.id}`
  const pendingOrder = {
    client_order_key: clientOrderKey,
    line_items: currentCart.items,
    customer_id: currentWpUser.id,
    total: currentCart.total_amount,
    created_at: new Date().toISOString()
  }
  // 写入本地IndexedDB
  const dbOpen = indexedDB.open('wc_pos_local_db', 1)
  dbOpen.onsuccess = (e) => {
    const db = e.target.result
    const transaction = db.transaction('pending_orders', 'readwrite')
    transaction.objectStore('pending_orders').add(pendingOrder)
    transaction.oncomplete = () => {
      console.log('离线订单已存入本地')
      alert('离线订单已保存，联网后将自动同步')
    }
  }
  return
}

// 网络恢复同步逻辑
window.addEventListener('online', async () => {
  const dbOpen = indexedDB.open('wc_pos_local_db', 1)
  dbOpen.onsuccess = async (e) => {
    const db = e.target.result
    const transaction = db.transaction('pending_orders', 'readwrite')
    const orderStore = transaction.objectStore('pending_orders')
    const pendingOrders = await orderStore.getAll()
    
    for (const order of pendingOrders) {
      try {
        // 调用WooCommerce原生订单接口上传
        await fetch('/wp-json/wc/v3/orders', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            'X-WC-API-Consumer-Key': wcPosApiKey
          },
          body: JSON.stringify(order)
        })
        // 上传成功删除本地订单
        await orderStore.delete(order.client_order_key)
      } catch (err) {
        console.error('订单同步失败', err)
        alert(`订单${order.client_order_key}同步失败，请手动检查后重试`)
      }
    }
  }
})

2. 后端接口适配 #

• 在WooCommerce订单创建接口新增去重逻辑，收到订单时先校验client_order_key字段，若系统内已有对应字段的订单，直接返回成功状态，避免重复生成订单
• 同步接口增加库存校验逻辑，离线场景无法实时扣减库存，同步时如果对应商品库存不足，直接返回错误信息给前端，提示用户调整订单

3. 兼容优化配置 #

• 拉长WordPress登录态有效期至7天以上，避免用户断网期间登录态过期，同步时出现401权限错误；若同步时检测到登录态过期，优先弹出登录提示，用户登录完成后自动重试同步
• 若使用的是WooCommerce POS Pro版本，可直接在插件设置页开启自带的Offline Mode功能，无需二次开发即可实现离线下单、自动同步能力

注意事项 #

• 离线场景下仅展示预缓存的商品数据，不支持商品搜索、会员折扣查询等需要实时请求后端的能力，可根据业务需求调整缓存内容范围
• 建议给离线订单加本地标识，同步成功后再打印小票，避免出现下单成功但同步失败的账实不符问题

内容的提问来源于stack exchange，提问作者3D PENNA