@pisell/pisellos 2.3.94 → 2.3.96

package/lib/modules/Order/utils.js

@@ -101,6 +101,7 @@ Object.defineProperty(exports, "resolveSafeProductNum", {
   }
 });
 exports.resolveSubmitCollectPax = resolveSubmitCollectPax;
+exports.resolveSubmitOrderType = resolveSubmitOrderType;
 Object.defineProperty(exports, "shouldBuildManualProductDiscount", {
   enumerable: true,
   get: function () {
@@ -125,6 +126,7 @@ var _decimal = _interopRequireDefault(require("decimal.js"));
 var _utils = require("../Holder/utils");
 var _utils2 = require("../../solution/ScanOrder/utils");
 var _orderCollectionIdentity = require("./utils/orderCollectionIdentity");
+var _salesNotes = require("./salesNotes");
 var _manualProductDiscount = require("./utils/manualProductDiscount");
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 /**
@@ -1127,6 +1129,7 @@ function createDefaultTempOrder(params) {
     request_unique_idempotency_token: '',
     vouchers: [],
     products: [],
+    notes: [],
     bookings: [],
     payments: [],
     surcharges: [],
@@ -1136,10 +1139,58 @@ function createDefaultTempOrder(params) {
     holder: null,
     metadata: {},
     _extend: {
-      productsByUid: {}
+      productsByUid: {},
+      salesNotesState: {
+        loaded: true,
+        dirty: false
+      }
     }
   };
 }
+function hasBoundBookingResource(bookings) {
+  if (!Array.isArray(bookings)) return false;
+  return bookings.some(booking => {
+    if (!booking || typeof booking !== 'object') return false;
+    if (Number(booking.parent_id) === 0) return false;
+    const resources = booking.resources;
+    if (!Array.isArray(resources)) return false;
+    return resources.some(resource => {
+      if (!resource || typeof resource !== 'object') return false;
+      const relationId = String(resource.relation_id ?? '').trim();
+      return relationId !== '' && relationId !== '0';
+    });
+  });
+}
+function isPersistedSubmitOrderId(orderId) {
+  if (orderId === undefined || orderId === null || orderId === '') return false;
+  const normalizedOrderId = Number(orderId);
+  return Number.isFinite(normalizedOrderId) && normalizedOrderId > 0;
+}
+
+/**
+ * 解析 checkout 的订单类型。
+ * dine_in 普通落库单在新增桌台资源后，即使原类型仍是 virtual，也必须按 table-order 提交。
+ */
+function resolveSubmitOrderType(params) {
+  const {
+    requestedType,
+    tempOrderType,
+    orderId,
+    businessCode,
+    tempOrderBusinessCode,
+    bookings
+  } = params;
+  const currentType = requestedType ?? tempOrderType;
+  const resolvedBusinessCode = businessCode ?? tempOrderBusinessCode;
+  if (isPersistedSubmitOrderId(orderId) && resolvedBusinessCode === 'dine_in' && currentType === 'virtual' && hasBoundBookingResource(bookings)) {
+    return 'table-order';
+  }
+  if (currentType) return currentType;
+  if (Array.isArray(bookings) && bookings.length > 0) {
+    return businessCode === 'dine_in' ? 'table-order' : 'appointment_booking';
+  }
+  return 'virtual';
+}
 function buildSubmitPayload(params) {
   const {
     tempOrder,
@@ -1173,22 +1224,18 @@ function buildSubmitPayload(params) {
     total_refund_amount: _totalRefundAmount,
     create_date: _createDate,
     holder_id: _holderId,
+    notes: _notes,
     ...tempOrderRest
   } = tempOrder;
-  let submitType = type ?? tempOrder.type;
-  if (!submitType) {
-    // 如果外部没有传递 types，根据订单里当前是否有 bookings 来决定是 appointment_booking 还是 virtual
-    if (tempOrder?.bookings?.length) {
-      // 260807 如果 biz 是堂食，type 使用table-order
-      if (businessCode === 'dine_in') {
-        submitType = 'table-order';
-      } else {
-        submitType = 'appointment_booking';
-      }
-    } else {
-      submitType = 'virtual';
-    }
-  }
+  const resolvedBusinessCode = businessCode ?? tempOrder.business_code;
+  const submitType = resolveSubmitOrderType({
+    requestedType: type,
+    tempOrderType: tempOrder.type,
+    orderId: tempOrder.order_id,
+    businessCode,
+    tempOrderBusinessCode: tempOrder.business_code,
+    bookings: tempOrder.bookings
+  });
   const payload = {
     ...tempOrderRest,
     customer_id: tempOrder.customer_id ?? 1,
@@ -1202,7 +1249,7 @@ function buildSubmitPayload(params) {
     platform: normalizeSubmitPlatform(platform),
     request_unique_idempotency_token: params?.request_unique_idempotency_token || tempOrder.request_unique_idempotency_token || `${tempOrder.external_sale_number}_${now.getTime()}`,
     type: submitType,
-    business_code: businessCode ?? tempOrder.business_code,
+    business_code: resolvedBusinessCode,
     sales_channel: tempOrder.sales_channel || 'my_pisel',
     order_sales_channel: channel ?? tempOrder.order_sales_channel ?? 'online_store',
     status: tempOrder.status || 'normal',
@@ -1235,6 +1282,11 @@ function buildSubmitPayload(params) {
         ...rest
       };
     })(),
+    ...(tempOrder._extend?.salesNotesState?.dirty ? {
+      notes: (0, _salesNotes.encodeSalesNotes)(tempOrder.notes || [], {
+        allowUnresolvedOrderTarget: true
+      })
+    } : {}),
     products: (tempOrder.products || []).map(product => normalizeSubmitProduct(product))
   };
   if (!enhance) return payload;

package/lib/modules/ProductList/index.d.ts

@@ -1,6 +1,6 @@
 import { Module, PisellCore } from '../../types';
 import { BaseModule } from '../BaseModule';
-import { ProductListLoadProductsParams } from './types';
+import { ProductListLoadProductsParams, ProductListStoreQueryParams } from './types';
 import { ProductData } from '../Product/types';
 export * from './types';
 export declare class ProductList extends BaseModule implements Module {
@@ -52,6 +52,7 @@ export declare class ProductList extends BaseModule implements Module {
     getRawProductPriceSources(ids: number[]): Map<number, ProductData>;
     getProducts(): Promise<ProductData[]>;
     getProduct(id: number): Promise<ProductData | undefined>;
+    queryProducts(params?: ProductListStoreQueryParams): Promise<ProductData[]>;
     getProductByIds(ids: number[]): Promise<ProductData[] | undefined>;
     addProduct(products: ProductData[]): Promise<void>;
     selectProducts(products: ProductData[]): Promise<void>;

package/lib/modules/ProductList/index.js

@@ -25,6 +25,15 @@ Object.keys(_types).forEach(function (key) {
   });
 });
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function normalizeQuerySet(values) {
+  if (!Array.isArray(values) || values.length === 0) return null;
+  const normalized = values.map(value => String(value ?? '').trim()).filter(Boolean);
+  return normalized.length ? new Set(normalized) : null;
+}
+function matchesAny(values, querySet) {
+  if (!querySet) return true;
+  return values.some(value => querySet.has(String(value ?? '').trim()));
+}
 class ProductList extends _BaseModule.BaseModule {
   defaultName = 'productList';
   defaultVersion = '1.0.0';
@@ -281,10 +290,46 @@ class ProductList extends _BaseModule.BaseModule {
     const product = this.store.list.find(product => product.id === id);
     return product ? (0, _lodashEs.cloneDeep)(product) : undefined;
   }
+  async queryProducts(params = {}) {
+    const includeIds = normalizeQuerySet(params.includeIds);
+    const excludeIds = normalizeQuerySet(params.excludeIds);
+    const categoryIds = normalizeQuerySet(params.categoryIds);
+    const collectionIds = normalizeQuerySet(params.collectionIds);
+    const extensionTypes = normalizeQuerySet(params.extensionTypes);
+    const statuses = normalizeQuerySet(params.statuses);
+    const channelApplications = normalizeQuerySet(params.channelApplications);
+    const codeOrBarcode = typeof params.codeOrBarcode === 'string' ? params.codeOrBarcode.trim() : '';
+    const products = (this.store.list || []).filter(product => {
+      const productId = String(product.id ?? '').trim();
+      if (includeIds && !includeIds.has(productId)) return false;
+      if (excludeIds && excludeIds.has(productId)) return false;
+      if (categoryIds) {
+        const productCategoryIds = (product.categories || []).flatMap(category => [category?.id, category?.pivot?.product_category_id]);
+        if (!matchesAny(productCategoryIds, categoryIds)) return false;
+      }
+      if (collectionIds) {
+        const productCollectionIds = (product.collection || []).map(collection => collection?.id);
+        if (!matchesAny(productCollectionIds, collectionIds)) return false;
+      }
+      if (extensionTypes && !extensionTypes.has(String(product.extension_type ?? '').trim())) return false;
+      if (statuses && !statuses.has(String(product.status ?? '').trim())) return false;
+      if (channelApplications) {
+        if (!matchesAny(product.channel_application || [], channelApplications)) return false;
+      }
+      if (codeOrBarcode) {
+        const code = typeof product.code === 'string' ? product.code.trim() : '';
+        const barcode = typeof product.barcode === 'string' ? product.barcode.trim() : '';
+        if (code !== codeOrBarcode && barcode !== codeOrBarcode) return false;
+      }
+      return true;
+    });
+    return (0, _lodashEs.cloneDeep)(products);
+  }
   async getProductByIds(ids) {
     await this.core.effects.emit(`${this.name}:onGetProductByIds`, this.store.list);
-    const products = this.store.list.filter(product => ids.includes(product.id));
-    return products;
+    return this.queryProducts({
+      includeIds: ids
+    });
   }
   async addProduct(products) {
     // list 需要根据 id 去重

package/lib/modules/ProductList/types.d.ts

@@ -15,6 +15,16 @@ export interface ProductListLoadProductsParams {
     /** 智能定价条件上下文，仅影响策略命中，不参与商品集合筛选 */
     strategy_context?: Record<string, any>;
 }
+export interface ProductListStoreQueryParams {
+    includeIds?: Array<number | string>;
+    excludeIds?: Array<number | string>;
+    categoryIds?: Array<number | string>;
+    collectionIds?: Array<number | string>;
+    extensionTypes?: string[];
+    statuses?: ProductData['status'][];
+    channelApplications?: string[];
+    codeOrBarcode?: string;
+}
 export interface ProductListData {
     list: ProductData[];
     selectProducts: ProductData[];

package/lib/modules/SalesSummary/index.js

@@ -133,7 +133,9 @@ class SalesSummaryModule extends _BaseModule.BaseModule {
       await this.getSurchargeList(summaryChannel);
     }
     const taxConfig = this.getTaxConfig();
-    const summarySchedule = this.core.getModule(`${this.name.split('_')[0]}_schedule`);
+    const fatherModuleName = this.otherParams?.fatherModule || this.name.replace(/_salesSummary$/, '');
+    const scheduleModuleName = `${fatherModuleName}_schedule`;
+    const summarySchedule = this.core.getModule(scheduleModuleName);
     const needScheduleIds = (this.store.surchargeList?.map(item => item.available_schedule_ids)?.flat() || []).filter(id => id !== undefined && id !== null && id !== '');
     const scheduleList = needScheduleIds.length > 0 ? summarySchedule?.getScheduleListByIds(needScheduleIds) : [];
     const scheduleById = {};

package/lib/server/index.d.ts

@@ -520,6 +520,12 @@ declare class Server {
     private stringifyCheckoutResourceIdentifier;
     private normalizeCheckoutSubmitData;
     private ensureCheckoutOrderNumbers;
+    /**
+     * Notes 允许在本地草稿阶段暂存空订单目标；checkout 的统一出口负责用最终
+     * shop_order_number 完成绑定并校验，保证后端请求、pending、设备任务和打印
+     * 都使用同一份完整快照。
+     */
+    private finalizeCheckoutSalesNotes;
     private dispatchCheckoutSyncTask;
     private dispatchPrintOtherReceiptTask;
     private buildPrintOtherReceiptIdempotencyKey;

package/lib/server/index.js

@@ -27,6 +27,7 @@ var _filterBookings = require("./modules/order/utils/filterBookings");
 var _smallTicket = require("./utils/small-ticket");
 var _BaseSales = require("../solution/BaseSales");
 var _paymentUtils = require("../modules/Order/payment-utils");
+var _salesNotes = require("../modules/Order/salesNotes");
 var _modules = require("./modules");
 Object.keys(_modules).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
@@ -3463,26 +3464,28 @@ class Server {
     if (!Array.isArray(bookings)) return '';
     const values = [];
     const seen = new Set();
-    const visitResource = resource => {
-      const identifier = this.getCheckoutResourceIdentifier(resource);
+    const visitResource = (resource, fallbackName) => {
+      const identifier = this.getCheckoutResourceIdentifier(resource, fallbackName);
       if (identifier && !seen.has(identifier)) {
         seen.add(identifier);
         values.push(identifier);
       }
       if (Array.isArray(resource?.children)) {
-        resource.children.forEach(visitResource);
+        resource.children.forEach(child => visitResource(child));
       }
     };
     bookings.forEach(booking => {
       if (Array.isArray(booking?.resources)) {
-        booking.resources.forEach(visitResource);
+        booking.resources.forEach((resource, index) => {
+          visitResource(resource, index === 0 ? booking?.relation_form_name : undefined);
+        });
       }
     });
     return values.join(',');
   }
-  getCheckoutResourceIdentifier(resource) {
+  getCheckoutResourceIdentifier(resource, fallbackName) {
     if (!resource || typeof resource !== 'object') return '';
-    const candidates = [resource.main_field, resource.name, resource.title, resource.metadata?.resource_name, resource.metadata?.name, resource.relation_id, resource.id];
+    const candidates = [resource.main_field, resource.name, resource.title, resource.metadata?.resource_name, resource.metadata?.name, fallbackName, resource.relation_id, resource.id];
     for (const candidate of candidates) {
       const value = this.stringifyCheckoutResourceIdentifier(candidate);
       if (value) return value;
@@ -3585,14 +3588,16 @@ class Server {
     };
     const needsShopOrderNumber = next.shop_order_number === undefined || next.shop_order_number === null || next.shop_order_number === '';
     const needsShopFullOrderNumber = next.shop_full_order_number === undefined || next.shop_full_order_number === null || next.shop_full_order_number === '';
-    if (!needsShopOrderNumber && !needsShopFullOrderNumber) return next;
+    if (!needsShopOrderNumber && !needsShopFullOrderNumber) {
+      return this.finalizeCheckoutSalesNotes(next, title);
+    }
     const idGenerator = this.getIdGeneratorPlugin();
     if (!idGenerator) {
       this.logWarning(`${title}: idGenerator 插件不可用，无法生成订单号`, {
         needsShopOrderNumber,
         needsShopFullOrderNumber
       });
-      return next;
+      return this.finalizeCheckoutSalesNotes(next, title);
     }
     try {
       if (needsShopOrderNumber && idGenerator.generateShopOrderNumber) {
@@ -3614,7 +3619,38 @@ class Server {
         error: error instanceof Error ? error.message : String(error)
       });
     }
-    return next;
+    return this.finalizeCheckoutSalesNotes(next, title);
+  }
+
+  /**
+   * Notes 允许在本地草稿阶段暂存空订单目标；checkout 的统一出口负责用最终
+   * shop_order_number 完成绑定并校验，保证后端请求、pending、设备任务和打印
+   * 都使用同一份完整快照。
+   */
+  finalizeCheckoutSalesNotes(data, title) {
+    if (!data || typeof data !== 'object') return data;
+    if (!Object.prototype.hasOwnProperty.call(data, 'notes')) return data;
+    if (data.notes === undefined || data.notes === null) return data;
+    if (!Array.isArray(data.notes)) {
+      throw new Error('[Order Notes] checkout notes 必须为数组');
+    }
+    if (data.notes.length === 0) return data;
+    const productTargetUuids = (Array.isArray(data.products) ? data.products : []).map(product => product?.metadata?.unique_identification_number ?? product?.unique_identification_number).filter(targetUuid => targetUuid !== undefined && targetUuid !== null && String(targetUuid).trim().length > 0).map(targetUuid => String(targetUuid));
+    const shopOrderNumber = String(data.shop_order_number ?? '').trim();
+    const notes = (0, _salesNotes.finalizeSalesNotesForCheckout)({
+      notes: data.notes,
+      shopOrderNumber,
+      productTargetUuids
+    });
+    this.logInfo(`${title}: checkout Notes 已绑定订单号`, {
+      shop_order_number: shopOrderNumber,
+      note_count: notes.length
+    });
+    return {
+      ...data,
+      shop_order_number: shopOrderNumber,
+      notes
+    };
   }
   async dispatchCheckoutSyncTask(params) {
     this.registerDeviceTaskActions();
@@ -5706,6 +5742,8 @@ class Server {
       schedule_datetime: context.schedule_datetime,
       customer_id: context.customer_id,
       strategy_context: context.strategy_context,
+      // 固定本次商品查询使用的语言，确保格式化与缓存使用同一份 locale 快照。
+      locale: this.core.context?.locale,
       menuList: this.menu?.getMenuList?.() || [],
       scheduleList: scheduleModule?.getScheduleList?.() || [],
       dataVariantEvaluator: this.core.context?.dataVariantEvaluator

package/lib/server/modules/products/index.d.ts

@@ -89,8 +89,8 @@ export declare class ProductsModule extends BaseModule implements Module {
     private buildBundleGroupPriceData;
     /**
      * 获取应用了价格的商品列表（带缓存）
-     * 使用日期作为缓存 key，同一天的商品价格会被缓存
-     * 缓存的是已经应用了价格的完整商品列表，避免重复转换
+     * 使用时间、客户、策略、商品范围和语言作为缓存 key
+     * 缓存的是已经应用了价格与多语言的完整商品列表，避免重复转换
      * @param schedule_date 日期
      * @param extraContext 额外的上下文数据（可选，由 Server 层传入）
      * @param options 可选参数

package/lib/server/modules/products/index.js

@@ -30,7 +30,7 @@ class ProductsModule extends _BaseModule.BaseModule {
   logger; // LoggerManager 实例
   otherParams = {};
 
-  // 商品价格缓存：Map<日期, 应用了价格的商品列表>
+  // 商品格式化缓存：Map<查询上下文 key, 已应用价格与多语言的商品列表>
   productsPriceCache = new Map();
 
   // 缓存配置
@@ -394,8 +394,8 @@ class ProductsModule extends _BaseModule.BaseModule {
 
   /**
    * 获取应用了价格的商品列表（带缓存）
-   * 使用日期作为缓存 key，同一天的商品价格会被缓存
-   * 缓存的是已经应用了价格的完整商品列表，避免重复转换
+   * 使用时间、客户、策略、商品范围和语言作为缓存 key
+   * 缓存的是已经应用了价格与多语言的完整商品列表，避免重复转换
    * @param schedule_date 日期
    * @param extraContext 额外的上下文数据（可选，由 Server 层传入）
    * @param options 可选参数
@@ -600,9 +600,10 @@ class ProductsModule extends _BaseModule.BaseModule {
   }
   getProductsPriceCacheKey(schedule_date, extraContext, productIds) {
     const datetime = extraContext?.schedule_datetime || schedule_date;
+    const locale = extraContext?.locale ?? this.core?.context?.locale ?? '';
     const productScope = productIds ? `:products:${productIds.join(',')}` : '';
     const strategyScope = this.stringifyStable(extraContext?.strategy_context || {});
-    return `${datetime}:customer:${extraContext?.customer_id ?? ''}:strategy:${strategyScope}${productScope}`;
+    return `${datetime}:locale:${locale}:customer:${extraContext?.customer_id ?? ''}` + `:strategy:${strategyScope}${productScope}`;
   }
 
   /**

package/lib/server/utils/product.d.ts

@@ -11,7 +11,7 @@ export declare function perfMark(label: string, durationMs: number, meta?: Recor
 export declare function applyPriceDataToProducts(products: ProductData[], priceData: LoadProductsPriceData[]): ProductData[];
 export declare const getIsSessionProduct: (product: ProductData) => boolean;
 /**
- * 根据 locale 将商品的 i18n 字段覆盖到对应原始字段
+ * 根据 locale 格式化商品、分类、规格及套餐文案，缺少对应语言时回退 original。
  */
 export declare function applyI18nToProducts(products: ProductData[], locale?: string): ProductData[];
 /**

package/lib/server/utils/product.js

@@ -194,9 +194,139 @@ const I18N_FIELD_MAP = {
   description_i18n: 'description',
   cover_i18n: 'cover'
 };
+/**
+ * 按当前语言读取 i18n 文案；当前语言为空时回退到商家原始文案。
+ */
+function resolveI18nValue(i18nDict, locale) {
+  if (!i18nDict) return undefined;
+  return i18nDict[locale] || i18nDict.original || undefined;
+}
+
+/**
+ * 递归格式化商品分类名称，同时保留未变化节点的引用。
+ */
+function applyI18nToCategory(category, locale) {
+  if (!category || typeof category !== 'object') return category;
+  const localizedName = resolveI18nValue(category.name_i18n, locale);
+  const localizedParent = applyI18nToCategory(category.parent_category, locale);
+  const nameChanged = localizedName !== undefined && localizedName !== category.name;
+  const parentChanged = localizedParent !== category.parent_category;
+  if (!nameChanged && !parentChanged) return category;
+  return {
+    ...category,
+    ...(nameChanged ? {
+      name: localizedName
+    } : {}),
+    ...(parentChanged ? {
+      parent_category: localizedParent
+    } : {})
+  };
+}
+function applyI18nToCategories(categories, locale) {
+  if (!Array.isArray(categories)) return categories;
+  let changed = false;
+  const localizedCategories = categories.map(category => {
+    const localizedCategory = applyI18nToCategory(category, locale);
+    if (localizedCategory !== category) changed = true;
+    return localizedCategory;
+  });
+  return changed ? localizedCategories : categories;
+}
+function applyI18nToNamedItems(items, locale) {
+  if (!Array.isArray(items)) return items;
+  let changed = false;
+  const localizedItems = items.map(item => {
+    if (!item || typeof item !== 'object') return item;
+    const localizedName = resolveI18nValue(item.name_i18n, locale);
+    if (localizedName === undefined || localizedName === item.name) return item;
+    changed = true;
+    return {
+      ...item,
+      name: localizedName
+    };
+  });
+  return changed ? localizedItems : items;
+}
+
+/**
+ * 格式化选项组、规格组及其子项名称，同时保留未变化节点的引用。
+ */
+function applyI18nToNamedGroups(groups, itemKey, locale) {
+  if (!Array.isArray(groups)) return groups;
+  let changed = false;
+  const localizedGroups = groups.map(group => {
+    if (!group || typeof group !== 'object') return group;
+    const localizedName = resolveI18nValue(group.name_i18n, locale);
+    const localizedItems = applyI18nToNamedItems(group[itemKey], locale);
+    const nameChanged = localizedName !== undefined && localizedName !== group.name;
+    const itemsChanged = localizedItems !== group[itemKey];
+    if (!nameChanged && !itemsChanged) return group;
+    changed = true;
+    return {
+      ...group,
+      ...(nameChanged ? {
+        name: localizedName
+      } : {}),
+      ...(itemsChanged ? {
+        [itemKey]: localizedItems
+      } : {})
+    };
+  });
+  return changed ? localizedGroups : groups;
+}
+function applyI18nToBundleItems(items, locale) {
+  if (!Array.isArray(items)) return items;
+  let changed = false;
+  const localizedItems = items.map(item => {
+    if (!item || typeof item !== 'object') return item;
+    const localizedTitle = resolveI18nValue(item.trans_title, locale);
+    const localizedOptionGroups = applyI18nToNamedGroups(item.option_group, 'option_item', locale);
+    const titleChanged = localizedTitle !== undefined && localizedTitle !== item.title;
+    const optionGroupsChanged = localizedOptionGroups !== item.option_group;
+    if (!titleChanged && !optionGroupsChanged) return item;
+    changed = true;
+    return {
+      ...item,
+      ...(titleChanged ? {
+        title: localizedTitle
+      } : {}),
+      ...(optionGroupsChanged ? {
+        option_group: localizedOptionGroups
+      } : {})
+    };
+  });
+  return changed ? localizedItems : items;
+}
 
 /**
- * 根据 locale 将商品的 i18n 字段覆盖到对应原始字段
+ * 格式化套餐组名称、套餐子商品标题及子商品选项，同时保留未变化节点的引用。
+ */
+function applyI18nToBundleGroups(groups, locale) {
+  if (!Array.isArray(groups)) return groups;
+  let changed = false;
+  const localizedGroups = groups.map(group => {
+    if (!group || typeof group !== 'object') return group;
+    const localizedName = resolveI18nValue(group.name_i18n, locale);
+    const localizedItems = applyI18nToBundleItems(group.bundle_item, locale);
+    const nameChanged = localizedName !== undefined && localizedName !== group.name;
+    const itemsChanged = localizedItems !== group.bundle_item;
+    if (!nameChanged && !itemsChanged) return group;
+    changed = true;
+    return {
+      ...group,
+      ...(nameChanged ? {
+        name: localizedName
+      } : {}),
+      ...(itemsChanged ? {
+        bundle_item: localizedItems
+      } : {})
+    };
+  });
+  return changed ? localizedGroups : groups;
+}
+
+/**
+ * 根据 locale 格式化商品、分类、规格及套餐文案，缺少对应语言时回退 original。
  */
 function applyI18nToProducts(products, locale) {
   if (!locale) return products;
@@ -205,14 +335,44 @@ function applyI18nToProducts(products, locale) {
     for (const [i18nKey, originalKey] of Object.entries(I18N_FIELD_MAP)) {
       const i18nDict = product[i18nKey];
       if (!i18nDict) continue;
-      const localizedValue = i18nDict[locale];
-      if (localizedValue) {
+      const localizedValue = resolveI18nValue(i18nDict, locale);
+      if (localizedValue !== undefined && localizedValue !== product[originalKey]) {
         if (!patched) patched = {
           ...product
         };
         patched[originalKey] = localizedValue;
       }
     }
+    for (const categoryKey of ['category', 'categories']) {
+      const categories = product[categoryKey];
+      const localizedCategories = applyI18nToCategories(categories, locale);
+      if (localizedCategories !== categories) {
+        if (!patched) patched = {
+          ...product
+        };
+        patched[categoryKey] = localizedCategories;
+      }
+    }
+    for (const [groupKey, itemKey] of [['option_group', 'option_item'], ['variant_group', 'variant_item']]) {
+      const groups = product[groupKey];
+      const localizedGroups = applyI18nToNamedGroups(groups, itemKey, locale);
+      if (localizedGroups !== groups) {
+        if (!patched) patched = {
+          ...product
+        };
+        patched[groupKey] = localizedGroups;
+      }
+    }
+    for (const bundleGroupKey of ['bundle_group', 'bundle_groups']) {
+      const groups = product[bundleGroupKey];
+      const localizedGroups = applyI18nToBundleGroups(groups, locale);
+      if (localizedGroups !== groups) {
+        if (!patched) patched = {
+          ...product
+        };
+        patched[bundleGroupKey] = localizedGroups;
+      }
+    }
     return patched ?? product;
   });
 }