wix-stores-versioning

Wix Stores 目录版本控制

Wix Stores 有两个目录版本，二者不向后兼容：

版本	状态
V1_CATALOG	旧版（例如，products、inventory）
V3_CATALOG	当前版本（例如，productsV3、inventoryItemsV3）

V3 模块通常带有 V3 后缀。使用 Wix MCP 搜索所需的特定模块。

核心模式

执行任何 Stores 操作前，务必检查目录版本：

import { catalogVersioning, products, productsV3 } from '@wix/stores';

async function getProducts() {
  const { catalogVersion } = await catalogVersioning.getCatalogVersion();

  if (catalogVersion === 'STORES_NOT_INSTALLED') {
    return [];
  }

  if (catalogVersion === 'V3_CATALOG') {
    // Use V3 module
    const result = await productsV3.queryProducts().limit(10).find();
    return result.items;
  }

  // Use V1 module
  const result = await products.queryProducts().limit(10).find();
  return result.items;
}

所需权限

务必查询所用的每个 API 方法所需的权限：

1. 使用 SearchWixSDKDocumentation 搜索该方法
2. 使用 ReadFullDocsArticle 阅读完整文档，获取所需权限
3. 向用户返回所需权限

关键规则

• 在每个流程开始时调用 getCatalogVersion()
• 目录版本对每个站点都是永久的（不会从 V3 降级到 V1）
• V1 和 V3 的载荷结构不同——字段名称、嵌套结构和类型均有差异
• 同时订阅 V1 和 V3 Webhook，以处理所有站点

查找 SDK 详情

使用 MCP 工具搜索特定版本的文档：

• SearchWixSDKDocumentation - 搜索方法和权限
• ReadFullDocsArticle - 在需要时阅读完整文档

搜索查询（结果会同时显示 V1 和 V3 命名空间）：

• "getCatalogVersion" → 权限和用法
• "createProduct" → productsV3（V3）和 products（V1）
• "queryProducts" → productsV3（V3）和 products（V1）
• "getInventoryItem" → inventoryItemsV3（V3）和 inventory（V1）

重要： 找到方法后，使用 ReadFullDocsArticle 获取包含所需权限的完整文档。请将权限返回给用户。

API 差异参考

V1 和 V3 的字段结构不同。如需了解字段映射，请参阅： 目录 V1 到 V3 迁移指南