inventory-tracking

库存跟踪

概述

实时库存跟踪可在客户将商品加入购物车时预留库存，并在订单履行时扣减库存，从而避免超卖。所有主要电商平台都内置了此功能。平台原生的库存跟踪几乎总是最佳起点——只有当你有平台无法满足的需求（复杂的多仓库路由、自定义预留时限或外部 WMS 集成）时，才需要构建自定义库存逻辑。

何时使用此技能

• 发生超卖，客户正在下单购买缺货商品时
• 实施按地点分别管理库存水平的多仓库库存时
• 为缺货商品构建延期交货或预售功能时
• 限时抢购或产品发布会导致客户高并发尝试结账购买库存有限的商品时

核心说明

第 1 步：确定平台并启用库存跟踪

平台	内置库存功能	推荐扩展
Shopify	原生支持按变体跟踪库存，并支持地点管理	Stocky（Shopify 提供的免费工具），用于采购订单和需求预测
WooCommerce	原生库存管理，并支持延期交货	ATUM Inventory Management，用于高级多仓库管理和供应商采购订单
BigCommerce	原生支持按 SKU 跟踪库存，并提供低库存提醒	Multi-Location Inventory 应用，用于仓库路由
自定义 / 无头平台	使用乐观锁构建原子预留	对没有原生库存管理的自定义平台而言，这是必需的

---

第 2 步：针对平台进行设置

---

Shopify

Shopify 原生支持按变体、按地点跟踪库存。

启用库存跟踪：

1. 前往 Admin → Products → [Product] → [Variant]
2. 在 Inventory 下，勾选 Track quantity
3. 输入各地点的库存数量
4. 对于“缺货时继续销售”，只有在允许该商品延期交货时才勾选

设置地点：

1. 前往 Settings → Locations
2. 将每个仓库、商店或履约中心添加为一个地点
3. 编辑产品变体时，分别设置各地点的库存数量

延期交货：

• 按变体启用：勾选该变体上的 Continue selling when out of stock
• 或使用 Pre-Order Now 或 Back In Stock 等延期交货应用，以获得更多控制（有货时通知客户、收集预售订单等）

高流量期间防止超卖：

Shopify 的结账系统会在结账过程中锁定库存，避免两位客户同时购买最后一件商品。对于限时抢购，可使用 Shopify Scripts（Plus）或 Inventory Planner 应用设置购买限额。

与实体地点同步库存：

• 安装 Stocky（Shopify 提供的免费工具），用于采购订单和收货
• 收到采购订单后，Stocky 会自动更新 Shopify 库存
• 使用 Shopify POS 应用，在网店和实体零售地点之间同步库存

---

WooCommerce

WooCommerce 内置库存管理功能。

启用库存跟踪：

1. 前往 WooCommerce → Settings → Products → Inventory
2. 勾选 Enable stock management
3. 设置 Hold stock (minutes) — 这是结账期间的库存预留时长（默认：60 分钟）

单个产品的设置：

1. 前往 WooCommerce → Products → [Product] → Inventory tab
2. 启用 Manage stock?
3. 输入 Stock quantity
4. 设置 Backorders：「Do not allow」/「Allow, but notify customer」/「Allow」
5. 为此产品设置 Low stock threshold

使用 ATUM 进行高级库存管理：

1. 安装 ATUM Inventory Management for WooCommerce（核心功能免费，高级功能付费）
2. ATUM 提供中央库存仪表板，显示所有产品的库存水平
3. 通过 ATUM → Purchase Orders → Add PO 添加采购订单
4. 在 ATUM 中接收采购订单会自动增加 WooCommerce 库存
5. 对于多仓库：ATUM 的 Multi-Inventory 插件（$）可按地点分配库存并安排履约路线

---

BigCommerce

BigCommerce 原生支持按 SKU 跟踪库存。

启用库存跟踪：

1. 前往 Products → [Product] → Inventory tab
2. 将 Inventory tracking 设置为「By product」或「By option」（适用于变体）
3. 输入当前库存水平
4. 设置 Low stock level 以接收提醒

多地点库存：

• 从 BigCommerce App Marketplace 安装 Multi-Location Inventory 应用
• 按地点分配库存数量
• 设置履约路线规则（从最近地点发货、从成本最低地点发货等）

延期交货：

• BigCommerce 原生支持此功能 — 对于缺货时仍要继续销售的产品，设置 Allow backorders
• 产品缺货延期交货时，产品页面会显示「Ships in X days」

---

自定义 / 无头架构

对于自定义平台，请使用乐观并发控制实现原子库存预留，以防止高负载下超卖：

// lib/inventory.ts
const MAX_RETRIES = 3;

// Reserve inventory atomically — handles concurrent requests safely
export async function reserveInventory({
  variantId, locationId, quantity, referenceId
}: { variantId: string; locationId: string; quantity: number; referenceId: string }) {
  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    const level = await db.inventoryLevels.findUnique({
      where: { variantId_locationId: { variantId, locationId } },
    });

    if (!level) throw new Error(`Inventory not found: ${variantId}`);

    const available = level.onHand - level.reserved;
    if (available < quantity && !level.backorderAllowed) {
      throw new Error(`Insufficient stock: ${available} available, ${quantity} requested`);
    }

    // Optimistic update — only succeeds if version hasn't changed (no concurrent modifications)
    const updated = await db.inventoryLevels.updateMany({
      where: { variantId_locationId: { variantId, locationId }, version: level.version },
      data: { reserved: level.reserved + quantity, version: level.version + 1 },
    });

    if (updated.count === 0) {
      // Another process modified inventory concurrently; retry
      await new Promise(r => setTimeout(r, 50 * (attempt + 1)));
      continue;
    }

    // Log the transaction for audit trail
    await db.inventoryTransactions.create({
      data: { variantId, locationId, type: 'reserve', quantity: -quantity, referenceId },
    });

    return { success: true, remaining: available - quantity };
  }
  throw new Error(`Failed to reserve inventory after ${MAX_RETRIES} retries`);
}

// Release reservation when cart expires or order is cancelled
export async function releaseReservation({
  variantId, locationId, quantity, referenceId
}: { variantId: string; locationId: string; quantity: number; referenceId: string }) {
  // Idempotency check — don't release twice
  const existing = await db.inventoryTransactions.findFirst({
    where: { type: 'release', referenceId, variantId },
  });
  if (existing) return;

  await db.$transaction([
    db.inventoryLevels.update({
      where: { variantId_locationId: { variantId, locationId } },
      data: { reserved: { decrement: quantity } },
    }),
    db.inventoryTransactions.create({
      data: { variantId, locationId, type: 'release', quantity: +quantity, referenceId },
    }),
  ]);
}

// Expire stale cart reservations — run every 5-10 minutes via cron
export async function expireStaleCartReservations() {
  const TTL_MINUTES = 30;
  const cutoff = new Date(Date.now() - TTL_MINUTES * 60 * 1000);

  const staleCarts = await db.carts.findMany({
    where: { status: 'active', updatedAt: { lt: cutoff }, reservedAt: { not: null } },
    include: { items: true },
  });

  for (const cart of staleCarts) {
    for (const item of cart.items) {
      await releaseReservation({ variantId: item.variantId, locationId: item.locationId, quantity: item.quantity, referenceId: cart.id });
    }
  }
}

---

第 3 步：配置延期交货行为

延期交货允许客户在库存为零时仍然购买，同时明确告知交付会延迟。

适合允许延期交货的情况：

• 供应商交货周期可靠的产品（7–14 天）
• 按需定制产品
• 为即将推出的产品开展的预售活动

适合禁止延期交货的情况：

• 供应不可靠的产品
• 由第三方履约且你无法控制补货的商品

沟通最佳实践：

• 当库存为 0 且启用了延期交货时，在产品页面显示「7–10 天内发货」
• 在订单确认邮件中注明预计发货日期
• 如果预计日期发生变化，主动通知客户

---

第 4 步：设置库存提醒

将库存跟踪与低库存提醒配合使用 — 完整设置请参阅 @low-stock-alerts 技能。简要说明：

• Shopify：前往 Admin → Products — Shopify 会显示低库存指示器；使用 Stocky 接收邮件提醒
• WooCommerce：前往 WooCommerce → Settings → Products → Inventory → Low stock threshold — 库存低于此阈值时，WooCommerce 会向店铺管理员发送邮件
• BigCommerce：前往 Products → [Product] → Inventory → Low stock level — BigCommerce 会自动发送邮件通知

最佳实践

• 为每个 SKU 启用库存跟踪 — 未启用跟踪的商品可能会在不知情的情况下超卖；仅对数字商品或供应量不限的商品关闭跟踪
• 为进行中的结账设置预留时限 — WooCommerce 的“保留库存”设置（默认 60 min）可防止库存被已放弃的购物车无限期占用
• 测试超卖保护 — 设置限时促销期间，通过模拟两个同时进行的结账，手动确认最后一件商品无法被购买两次
• 记录每次库存变更 — 各平台都原生支持记录；对于自定义构建，使用不可变的 inventory_transactions 表对于排查差异至关重要
• 购买第三方应用前，先使用平台内置的多地点库存功能 — Shopify、WooCommerce 和 BigCommerce 都原生支持多个地点

常见问题

问题	解决方案
Shopify 在限时促销期间发生超卖	Shopify 的结账流程会暂扣库存；对于并发量极高的发售活动，可使用 Shopify Scripts（Plus）设置购买限额，或使用候补名单应用
WooCommerce 下单后未扣减库存	检查是否已在商品和 WooCommerce 全局设置中启用库存管理；两处都必须启用
订单在履约前取消后，库存立即释放	对实体商品而言，这是正确行为 — 释放的库存可供其他客户购买；仅对缺货待补商品延迟释放
手动调整后库存为负数	在 WooCommerce（ATUM）中添加验证，或在自定义构建中设置数据库检查约束；reserved >= 0 和 on_hand >= 0
Shopify 地点未收到 POS 的库存更新	确认 POS 已在“设置 → 地点 → POS 渠道”中连接到正确的 Shopify 地点

相关技能

• @multi-warehouse
• @low-stock-alerts
• @variant-matrix