@pisell/pisellos 0.0.509 → 0.0.511

package/dist/solution/ScanOrder/types.d.ts

@@ -31,6 +31,9 @@ export interface ScanOrderOrderProductIdentity {
     product_id: number | null;
     product_variant_id: number;
     identity_key?: string;
+    /** 参与合并/匹配；与 remove 通配语义见 isSkuOnlyDeleteIdentity */
+    product_option_item?: any[];
+    product_bundle?: any[];
 }
 export interface ScanOrderOrderProduct extends ScanOrderOrderProductIdentity {
     order_detail_id: number | null;
@@ -45,8 +48,22 @@ export interface ScanOrderOrderProduct extends ScanOrderOrderProductIdentity {
     discount_list: any[];
     product_bundle: any[];
     metadata: Record<string, any>;
+    /** 商品行备注（如顾客对单品的特殊要求） */
+    note?: string;
     _origin?: Record<string, any>;
 }
+/**
+ * 出站 payload 版本的商品行。
+ *
+ * 与 tempOrder 内部 `ScanOrderOrderProduct` 的字段差异：
+ * - `product_option_item[*]`：内部为 `{ product_option_item_id, option_group_id, num, price, ... }`，
+ *   出站由 `normalizeSubmitProduct` 重命名为 `{ option_group_item_id, option_group_id, num }`
+ *   （后端 checkout 协议；丢弃 `price` 等运行时辅助字段）。
+ * - `product_bundle[*].option[*]`：同上重命名规则。
+ *
+ * 运行时（UI 显示、加购合并、指纹、持久化）全部消费内部字段名 `product_option_item_id`，
+ * 仅在 SDK 提交边界做一次出站映射，不影响 opaque identity 契约。
+ */
 export interface ScanOrderSubmitProduct extends Omit<ScanOrderOrderProduct, '_origin' | 'identity_key'> {
     /**
      * 出站兼容字段：SDK 内部不再消费 payment_price，

package/dist/solution/ScanOrder/types.js

@@ -10,6 +10,19 @@ export var ScanOrderHooks = /*#__PURE__*/function (ScanOrderHooks) {
   return ScanOrderHooks;
 }({});
 
+/**
+ * 出站 payload 版本的商品行。
+ *
+ * 与 tempOrder 内部 `ScanOrderOrderProduct` 的字段差异：
+ * - `product_option_item[*]`：内部为 `{ product_option_item_id, option_group_id, num, price, ... }`，
+ *   出站由 `normalizeSubmitProduct` 重命名为 `{ option_group_item_id, option_group_id, num }`
+ *   （后端 checkout 协议；丢弃 `price` 等运行时辅助字段）。
+ * - `product_bundle[*].option[*]`：同上重命名规则。
+ *
+ * 运行时（UI 显示、加购合并、指纹、持久化）全部消费内部字段名 `product_option_item_id`，
+ * 仅在 SDK 提交边界做一次出站映射，不影响 opaque identity 契约。
+ */
+
 /**
  * ScanOrder 临时订单（runtime-clean 版本）
  * 只保留运行时字段，不包含任何 __comment 字段

package/dist/solution/ScanOrder/utils.d.ts

@@ -82,9 +82,24 @@ export declare function buildItemRuleBusinessData(params: {
 }): ItemRuleBusinessData;
 export declare function attachItemRuleLimitsToTopLevelProducts<T>(productList: T, limits: QuantityLimitResult[]): T;
 /**
- * 判断两个商品 identity 是否匹配。
- * 当双方都没有 identity_key 时回退到 product_id + product_variant_id 比较（向后兼容）；
- * 一旦有一方携带 identity_key，则必须严格相等。
+ * 将选项行 / 套餐行归一成稳定 JSON，用于「同 SKU 是否合并」判断。
+ * 数组元素先按主键排序再序列化，避免顺序差异导致误判为不同行。
+ */
+export declare function buildProductLineFingerprint(productOptionItem?: unknown, productBundle?: unknown): string;
+/**
+ * removeProductFromOrder 仅传 SKU 时的通配 identity（对象上未声明选项键）。
+ * 与显式 `product_option_item: []` 区分：后者只匹配「无选项」行。
+ */
+export declare function isSkuOnlyDeleteIdentity(x: ScanOrderOrderProductIdentity): boolean;
+/**
+ * 判断两个商品 identity 是否匹配（不透明 identity 契约）。
+ *
+ * 调用约定：始终 `isIdentityMatch(line, callerIdentity)`。
+ * - 若 SKU（product_id + product_variant_id）不一致 → 不匹配。
+ * - **双方都带** `identity_key` → 严格字符串相等比较（不再猜测合成 key / metadata 桥接）。
+ *   这是 opaque identity 契约的标准路径：UI 删改时透传 SDK 回灌的 identity_key。
+ * - 否则（即至少一侧未声明 identity_key）→ 进入「SKU 通配 / 显式空选项 / 指纹」回退路径，
+ *   忽略线侧 identity_key，按内容语义匹配。这给「行已 opaque、调用方却想按 SKU 通配 / 选项指纹删除」留兼容入口。
  */
 export declare function isIdentityMatch(a: ScanOrderOrderProductIdentity, b: ScanOrderOrderProductIdentity): boolean;
 /**

package/dist/solution/ScanOrder/utils.js

@@ -12,6 +12,8 @@ function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol
 function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
 function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
 import dayjs from 'dayjs';
+import { createUuidV4 } from "../../modules/Order/utils";
+
 /**
  * 构建金额全为 0 的空 summary。
  * 作为尚未计算金额时的兜底默认值，避免下游因 undefined 报错。
@@ -367,14 +369,75 @@ export function attachItemRuleLimitsToTopLevelProducts(productList, limits) {
 }
 
 /**
- * 判断两个商品 identity 是否匹配。
- * 当双方都没有 identity_key 时回退到 product_id + product_variant_id 比较（向后兼容）；
- * 一旦有一方携带 identity_key，则必须严格相等。
+ * 将选项行 / 套餐行归一成稳定 JSON，用于「同 SKU 是否合并」判断。
+ * 数组元素先按主键排序再序列化，避免顺序差异导致误判为不同行。
+ */
+export function buildProductLineFingerprint(productOptionItem, productBundle) {
+  var optArr = Array.isArray(productOptionItem) ? productOptionItem : [];
+  var normalizedOpts = optArr.map(function (item) {
+    var _item$price;
+    return {
+      product_option_item_id: Number(item === null || item === void 0 ? void 0 : item.product_option_item_id) || 0,
+      option_group_id: Number(item === null || item === void 0 ? void 0 : item.option_group_id) || 0,
+      num: typeof (item === null || item === void 0 ? void 0 : item.num) === 'number' && !Number.isNaN(item.num) ? Math.max(1, Math.floor(item.num)) : 1,
+      price: String((_item$price = item === null || item === void 0 ? void 0 : item.price) !== null && _item$price !== void 0 ? _item$price : '')
+    };
+  }).sort(function (p, q) {
+    if (p.product_option_item_id !== q.product_option_item_id) {
+      return p.product_option_item_id - q.product_option_item_id;
+    }
+    if (p.option_group_id !== q.option_group_id) return p.option_group_id - q.option_group_id;
+    if (p.num !== q.num) return p.num - q.num;
+    return p.price.localeCompare(q.price);
+  });
+  var bundleArr = Array.isArray(productBundle) ? productBundle : [];
+  var normalizedBundles = bundleArr.map(function (item) {
+    var _ref, _item$bundle_id;
+    return {
+      bundle_id: Number((_ref = (_item$bundle_id = item === null || item === void 0 ? void 0 : item.bundle_id) !== null && _item$bundle_id !== void 0 ? _item$bundle_id : item === null || item === void 0 ? void 0 : item.id) !== null && _ref !== void 0 ? _ref : 0) || 0,
+      product_id: Number(item === null || item === void 0 ? void 0 : item.product_id) || 0,
+      num: typeof (item === null || item === void 0 ? void 0 : item.num) === 'number' && !Number.isNaN(item.num) ? Math.max(1, Math.floor(item.num)) : 1
+    };
+  }).sort(function (p, q) {
+    if (p.bundle_id !== q.bundle_id) return p.bundle_id - q.bundle_id;
+    if (p.product_id !== q.product_id) return p.product_id - q.product_id;
+    return p.num - q.num;
+  });
+  return JSON.stringify([normalizedOpts, normalizedBundles]);
+}
+
+/**
+ * removeProductFromOrder 仅传 SKU 时的通配 identity（对象上未声明选项键）。
+ * 与显式 `product_option_item: []` 区分：后者只匹配「无选项」行。
+ */
+export function isSkuOnlyDeleteIdentity(x) {
+  if (x.identity_key) return false;
+  return !('product_option_item' in x) && !('product_bundle' in x);
+}
+function fingerprintForIdentityWithOptionKeys(x) {
+  var row = x;
+  var opts = 'product_option_item' in row ? Array.isArray(row.product_option_item) ? row.product_option_item : [] : [];
+  var buds = 'product_bundle' in row ? Array.isArray(row.product_bundle) ? row.product_bundle : [] : [];
+  return buildProductLineFingerprint(opts, buds);
+}
+
+/**
+ * 判断两个商品 identity 是否匹配（不透明 identity 契约）。
+ *
+ * 调用约定：始终 `isIdentityMatch(line, callerIdentity)`。
+ * - 若 SKU（product_id + product_variant_id）不一致 → 不匹配。
+ * - **双方都带** `identity_key` → 严格字符串相等比较（不再猜测合成 key / metadata 桥接）。
+ *   这是 opaque identity 契约的标准路径：UI 删改时透传 SDK 回灌的 identity_key。
+ * - 否则（即至少一侧未声明 identity_key）→ 进入「SKU 通配 / 显式空选项 / 指纹」回退路径，
+ *   忽略线侧 identity_key，按内容语义匹配。这给「行已 opaque、调用方却想按 SKU 通配 / 选项指纹删除」留兼容入口。
  */
 export function isIdentityMatch(a, b) {
   if (a.product_id !== b.product_id || a.product_variant_id !== b.product_variant_id) return false;
-  if (!a.identity_key && !b.identity_key) return true;
-  return a.identity_key === b.identity_key;
+  var aHasKey = typeof a.identity_key === 'string' && a.identity_key.length > 0;
+  var bHasKey = typeof b.identity_key === 'string' && b.identity_key.length > 0;
+  if (aHasKey && bHasKey) return a.identity_key === b.identity_key;
+  if (isSkuOnlyDeleteIdentity(a) || isSkuOnlyDeleteIdentity(b)) return true;
+  return fingerprintForIdentityWithOptionKeys(a) === fingerprintForIdentityWithOptionKeys(b);
 }
 
 /**
@@ -396,8 +459,11 @@ export function getProductIdentityIndex(products, identity) {
 export function normalizeOrderProduct(product) {
   var _product$is_charge_ta;
   var metadata = _objectSpread({}, product.metadata || {});
-  if (product.identity_key && !metadata.unique_identification_number) {
-    metadata.unique_identification_number = product.identity_key;
+  // 不透明 identity 契约：每条订单行必须带 identity_key。
+  // 调用方未传时由 SDK 自动生成 UUID，后续 update/remove 只做严格比对，避免猜测合成 key。
+  var resolvedIdentityKey = product.identity_key && String(product.identity_key).length > 0 ? String(product.identity_key) : createUuidV4();
+  if (!metadata.unique_identification_number) {
+    metadata.unique_identification_number = resolvedIdentityKey;
   }
 
   // selling_price：券后成交单价；original_price：券前店铺售价。
@@ -414,14 +480,14 @@ export function normalizeOrderProduct(product) {
     metadata.main_product_selling_price = resolvedSellingPrice;
   }
   if (metadata.source_product_price === undefined) {
-    var _ref, _product$_origin$pric, _product$_origin, _product$_origin2;
-    metadata.source_product_price = (_ref = (_product$_origin$pric = (_product$_origin = product._origin) === null || _product$_origin === void 0 ? void 0 : _product$_origin.price) !== null && _product$_origin$pric !== void 0 ? _product$_origin$pric : (_product$_origin2 = product._origin) === null || _product$_origin2 === void 0 ? void 0 : _product$_origin2.base_price) !== null && _ref !== void 0 ? _ref : resolvedSellingPrice;
+    var _ref2, _product$_origin$pric, _product$_origin, _product$_origin2;
+    metadata.source_product_price = (_ref2 = (_product$_origin$pric = (_product$_origin = product._origin) === null || _product$_origin === void 0 ? void 0 : _product$_origin.price) !== null && _product$_origin$pric !== void 0 ? _product$_origin$pric : (_product$_origin2 = product._origin) === null || _product$_origin2 === void 0 ? void 0 : _product$_origin2.base_price) !== null && _ref2 !== void 0 ? _ref2 : resolvedSellingPrice;
   }
   var normalizedBundle = (product.product_bundle || []).map(function (item) {
-    var _ref2, _item$bundle_selling_, _ref3, _ref4, _item$custom_price;
+    var _ref3, _item$bundle_selling_, _ref4, _ref5, _item$custom_price;
     return _objectSpread(_objectSpread({}, item), {}, {
-      bundle_selling_price: (_ref2 = (_item$bundle_selling_ = item.bundle_selling_price) !== null && _item$bundle_selling_ !== void 0 ? _item$bundle_selling_ : item.price) !== null && _ref2 !== void 0 ? _ref2 : '0.00',
-      custom_price: (_ref3 = (_ref4 = (_item$custom_price = item.custom_price) !== null && _item$custom_price !== void 0 ? _item$custom_price : item.bundle_selling_price) !== null && _ref4 !== void 0 ? _ref4 : item.price) !== null && _ref3 !== void 0 ? _ref3 : '0.00'
+      bundle_selling_price: (_ref3 = (_item$bundle_selling_ = item.bundle_selling_price) !== null && _item$bundle_selling_ !== void 0 ? _item$bundle_selling_ : item.price) !== null && _ref3 !== void 0 ? _ref3 : '0.00',
+      custom_price: (_ref4 = (_ref5 = (_item$custom_price = item.custom_price) !== null && _item$custom_price !== void 0 ? _item$custom_price : item.bundle_selling_price) !== null && _ref5 !== void 0 ? _ref5 : item.price) !== null && _ref4 !== void 0 ? _ref4 : '0.00'
     });
   });
   return {
@@ -429,7 +495,7 @@ export function normalizeOrderProduct(product) {
     product_id: product.product_id,
     num: getSafeProductNum(product.num),
     product_variant_id: product.product_variant_id,
-    identity_key: product.identity_key,
+    identity_key: resolvedIdentityKey,
     product_option_item: product.product_option_item || [],
     selling_price: resolvedSellingPrice,
     original_price: resolvedOriginalPrice,
@@ -438,6 +504,7 @@ export function normalizeOrderProduct(product) {
     discount_list: product.discount_list || [],
     product_bundle: normalizedBundle,
     metadata: metadata,
+    note: product.note != null ? String(product.note) : '',
     _origin: product._origin
   };
 }

package/dist/solution/VenueBooking/index.d.ts

@@ -2,6 +2,7 @@ import { Module, ModuleOptions, PisellCore } from '../../types';
 import { BaseModule } from '../../modules/BaseModule';
 import { VenueBookingAddLogParams, VenueBookingSlotConfig, VenueDateSummaryItem, VenueSlotSelection, VenueTimeSlotGrid } from './types';
 import type { ScanOrderOrderProduct, ScanOrderOrderProductIdentity } from '../ScanOrder/types';
+import type { UpdateProductInOrderParams } from '../../modules/Order/types';
 import type { OpenDataAvailabilityResult } from '../../modules/OpenData';
 import type { ProductData } from '../../modules/Product/types';
 import { type CartItemSummary, type PaxInfo, type QuantityCheckResult, type QuantityLimitResult } from '../../model/strategy/adapter/itemRule';
@@ -165,11 +166,7 @@ export declare class VenueBookingImpl extends BaseModule implements Module {
     getSummary(): Promise<import("./types").ScanOrderSummary>;
     submitOrder<T = any>(): Promise<T>;
     addProductToOrder(product: Partial<ScanOrderOrderProduct> & ScanOrderOrderProductIdentity): Promise<ScanOrderOrderProduct[]>;
-    updateProductInOrder(params: {
-        product_id: number | null;
-        product_variant_id: number;
-        updates: Partial<ScanOrderOrderProduct>;
-    }): Promise<ScanOrderOrderProduct[]>;
+    updateProductInOrder(params: UpdateProductInOrderParams): Promise<ScanOrderOrderProduct[]>;
     removeProductFromOrder(identity: ScanOrderOrderProductIdentity): Promise<ScanOrderOrderProduct[]>;
     getProductList(): Promise<ProductData[]>;
     private loadOpenDataConfig;

package/lib/model/strategy/adapter/promotion/index.js

@@ -0,0 +1,49 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/model/strategy/adapter/promotion/index.ts
+var promotion_exports = {};
+__export(promotion_exports, {
+  BUY_X_GET_Y_FREE_STRATEGY: () => import_examples.BUY_X_GET_Y_FREE_STRATEGY,
+  PromotionAdapter: () => import_adapter.PromotionAdapter,
+  PromotionEvaluator: () => import_evaluator.PromotionEvaluator,
+  X_ITEMS_FOR_Y_PRICE_STRATEGY: () => import_examples.X_ITEMS_FOR_Y_PRICE_STRATEGY,
+  default: () => import_adapter2.default
+});
+module.exports = __toCommonJS(promotion_exports);
+var import_evaluator = require("./evaluator");
+var import_adapter = require("./adapter");
+var import_adapter2 = __toESM(require("./adapter"));
+var import_examples = require("./examples");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BUY_X_GET_Y_FREE_STRATEGY,
+  PromotionAdapter,
+  PromotionEvaluator,
+  X_ITEMS_FOR_Y_PRICE_STRATEGY
+});

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

@@ -1,6 +1,6 @@
 import { Module, PisellCore, ModuleOptions } from '../../types';
 import { BaseModule } from '../BaseModule';
-import { OrderModuleAPI, CommitOrderParams, SubmitScanOrderParams, ScanOrderMoreParams, CheckoutOrderParams } from './types';
+import { OrderModuleAPI, CommitOrderParams, SubmitScanOrderParams, ScanOrderMoreParams, CheckoutOrderParams, UpdateProductInOrderParams } from './types';
 import { CartItem } from '../Cart/types';
 import { type SubmitPayloadEnhancer } from './utils';
 import type { ScanOrderOrderProduct, ScanOrderOrderProductIdentity, ScanOrderSummary, ScanOrderTempOrder } from '../../solution/ScanOrder/types';
@@ -71,11 +71,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     updateTempOrderBuzzer(buzzer: string): string;
     updateTempOrderContactsInfo(contactsInfo: any[]): any[];
     addProductToOrder(product: Partial<ScanOrderOrderProduct> & ScanOrderOrderProductIdentity): Promise<ScanOrderOrderProduct[]>;
-    updateProductInOrder(params: {
-        product_id: number | null;
-        product_variant_id: number;
-        updates: Partial<ScanOrderOrderProduct>;
-    }): Promise<ScanOrderOrderProduct[]>;
+    updateProductInOrder(params: UpdateProductInOrderParams): Promise<ScanOrderOrderProduct[]>;
     removeProductFromOrder(identity: ScanOrderOrderProductIdentity): Promise<ScanOrderOrderProduct[]>;
     submitTempOrder<T = any>(params?: {
         cacheId?: string;
@@ -119,3 +115,4 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     getOrderInfoByRemote(order_id: number): Promise<any>;
     getLastOrderInfo(): Record<string, any> | undefined;
 }
+export type { UpdateProductInOrderParams } from './types';

package/lib/modules/Order/index.js

@@ -288,6 +288,29 @@ var OrderModule = class extends import_BaseModule.BaseModule {
         this.window.localStorage.removeItem(key);
         return;
       }
+      if (Array.isArray(parsedData.products)) {
+        for (const p of parsedData.products) {
+          if (!p || typeof p !== "object")
+            continue;
+          if (!Array.isArray(p.product_option_item)) {
+            p.product_option_item = [];
+          }
+          if (!Array.isArray(p.product_bundle)) {
+            p.product_bundle = [];
+          }
+          const row = p;
+          if (typeof row.identity_key !== "string" || row.identity_key.length === 0) {
+            const newKey = (0, import_utils.createUuidV4)();
+            row.identity_key = newKey;
+            if (!row.metadata || typeof row.metadata !== "object") {
+              row.metadata = {};
+            }
+            if (!row.metadata.unique_identification_number) {
+              row.metadata.unique_identification_number = newKey;
+            }
+          }
+        }
+      }
       this.store.tempOrder = parsedData;
     } catch {
       (_b = (_a = this.window) == null ? void 0 : _a.localStorage) == null ? void 0 : _b.removeItem(key);
@@ -397,21 +420,57 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   // ─── TempOrder: 商品 CRUD ───
   async addProductToOrder(product) {
     const tempOrder = this.ensureTempOrder();
-    const normalizedProduct = (0, import_utils3.normalizeOrderProduct)(product);
-    const productIndex = (0, import_utils3.getProductIdentityIndex)(
-      tempOrder.products,
-      normalizedProduct
-    );
-    if (productIndex === -1) {
-      tempOrder.products.push(normalizedProduct);
+    const hasExplicitIdentityKey = typeof product.identity_key === "string" && product.identity_key.length > 0;
+    if (hasExplicitIdentityKey) {
+      const normalizedProduct = (0, import_utils3.normalizeOrderProduct)(product);
+      const productIndex = (0, import_utils3.getProductIdentityIndex)(
+        tempOrder.products,
+        normalizedProduct
+      );
+      if (productIndex === -1) {
+        tempOrder.products.push(normalizedProduct);
+      } else {
+        const targetProduct = tempOrder.products[productIndex];
+        tempOrder.products[productIndex] = {
+          ...targetProduct,
+          ...normalizedProduct,
+          num: (0, import_utils3.getSafeProductNum)(targetProduct.num + normalizedProduct.num),
+          _origin: normalizedProduct._origin || targetProduct._origin
+        };
+      }
     } else {
-      const targetProduct = tempOrder.products[productIndex];
-      tempOrder.products[productIndex] = {
-        ...targetProduct,
-        ...normalizedProduct,
-        num: (0, import_utils3.getSafeProductNum)(targetProduct.num + normalizedProduct.num),
-        _origin: normalizedProduct._origin || targetProduct._origin
-      };
+      const incomingFingerprint = (0, import_utils3.buildProductLineFingerprint)(
+        product.product_option_item,
+        product.product_bundle
+      );
+      const matchedIndex = tempOrder.products.findIndex((item) => {
+        if (item.product_id !== product.product_id)
+          return false;
+        if (item.product_variant_id !== product.product_variant_id)
+          return false;
+        const existedFingerprint = (0, import_utils3.buildProductLineFingerprint)(
+          item.product_option_item,
+          item.product_bundle
+        );
+        return existedFingerprint === incomingFingerprint;
+      });
+      if (matchedIndex === -1) {
+        const normalizedProduct = (0, import_utils3.normalizeOrderProduct)(product);
+        tempOrder.products.push(normalizedProduct);
+      } else {
+        const targetProduct = tempOrder.products[matchedIndex];
+        const normalizedProduct = (0, import_utils3.normalizeOrderProduct)({
+          ...product,
+          identity_key: targetProduct.identity_key
+        });
+        tempOrder.products[matchedIndex] = {
+          ...targetProduct,
+          ...normalizedProduct,
+          identity_key: targetProduct.identity_key,
+          num: (0, import_utils3.getSafeProductNum)(targetProduct.num + normalizedProduct.num),
+          _origin: normalizedProduct._origin || targetProduct._origin
+        };
+      }
     }
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
@@ -419,12 +478,26 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     return tempOrder.products;
   }
   async updateProductInOrder(params) {
-    const { product_id, product_variant_id, updates } = params;
+    const {
+      product_id,
+      product_variant_id,
+      updates,
+      identity_key,
+      product_option_item,
+      product_bundle
+    } = params;
     const tempOrder = this.ensureTempOrder();
-    const productIndex = (0, import_utils3.getProductIdentityIndex)(tempOrder.products, {
+    const identityLookup = {
       product_id,
       product_variant_id
-    });
+    };
+    if (identity_key !== void 0)
+      identityLookup.identity_key = identity_key;
+    if (product_option_item !== void 0)
+      identityLookup.product_option_item = product_option_item;
+    if (product_bundle !== void 0)
+      identityLookup.product_bundle = product_bundle;
+    const productIndex = (0, import_utils3.getProductIdentityIndex)(tempOrder.products, identityLookup);
     if (productIndex === -1) {
       throw new Error("[Order] 目标商品不存在，无法更新");
     }
@@ -444,18 +517,9 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   }
   async removeProductFromOrder(identity) {
     const tempOrder = this.ensureTempOrder();
-    const beforeProducts = tempOrder.products;
     tempOrder.products = tempOrder.products.filter(
       (item) => !(0, import_utils3.isIdentityMatch)(item, identity)
     );
-    const removedByStrictIdentity = beforeProducts.length - tempOrder.products.length;
-    if (removedByStrictIdentity === 0 && identity.identity_key) {
-      tempOrder.products = tempOrder.products.filter((item) => {
-        const isSameProduct = String(item.product_id) === String(identity.product_id) && String(item.product_variant_id) === String(identity.product_variant_id);
-        const hasNoIdentityKey = !item.identity_key;
-        return !(isSameProduct && hasNoIdentityKey);
-      });
-    }
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
     this.persistTempOrder();

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

@@ -16,6 +16,15 @@ export interface OrderState {
     discount: DiscountModule | null;
     rules: RulesModule | null;
 }
+/** 更新购物车行：仅传 SKU 时命中同 SKU 第一行；多行同 SKU 须传 identity_key / 选项指纹等 */
+export interface UpdateProductInOrderParams {
+    product_id: number | null;
+    product_variant_id: number;
+    updates: Partial<ScanOrderOrderProduct>;
+    identity_key?: string;
+    product_option_item?: any[];
+    product_bundle?: any[];
+}
 /**
  * 订单信息
  */
@@ -43,6 +52,8 @@ export interface SubmitScanOrderProduct {
     discount_list: any[];
     product_bundle: any[];
     metadata: Record<string, any>;
+    /** 商品行备注 */
+    note?: string;
 }
 export interface SubmitScanOrderSummary {
     product_quantity: number;
@@ -210,11 +221,7 @@ export interface OrderModuleAPI {
     updateTempOrderBuzzer: (buzzer: string) => string;
     updateTempOrderContactsInfo: (contactsInfo: any[]) => any[];
     addProductToOrder: (product: Partial<ScanOrderOrderProduct> & ScanOrderOrderProductIdentity) => Promise<ScanOrderOrderProduct[]>;
-    updateProductInOrder: (params: {
-        product_id: number | null;
-        product_variant_id: number;
-        updates: Partial<ScanOrderOrderProduct>;
-    }) => Promise<ScanOrderOrderProduct[]>;
+    updateProductInOrder: (params: UpdateProductInOrderParams) => Promise<ScanOrderOrderProduct[]>;
     removeProductFromOrder: (identity: ScanOrderOrderProductIdentity) => Promise<ScanOrderOrderProduct[]>;
     persistTempOrder: () => void;
     submitTempOrder: <T = any>(params?: {

package/lib/modules/Order/utils.d.ts

@@ -81,6 +81,7 @@ export declare function formatV1Product(products: ScanOrderSubmitProduct[]): {
     product_id: number | null;
     product_variant_id: number;
     num: number;
+    note: string;
     rowKey: number | null;
     session: null;
     unique: string;

package/lib/modules/Order/utils.js

@@ -60,7 +60,14 @@ function createDefaultOrderRulesHooks() {
       var _a, _b, _c, _d;
       return {
         id: product.product_id,
-        _id: product.identity_key ? `${product.product_id}_${product.product_variant_id}_${product.identity_key}` : `${product.product_id}_${product.product_variant_id}`,
+        // Rules 引擎用 _id 作为 processedProductsMap 键；必须与购物车行级 identity 一致，
+        // 否则同 SKU 不同小料会在 calcDiscount 重组时互相覆盖。
+        // 不透明 identity 契约下，normalizeOrderProduct / restoreTempOrderFromStorage 已保证 identity_key 必存在；
+        // 留 fingerprint 分支仅作 Rules 单测里直接传裸 product 时的兜底。
+        _id: product.identity_key ? `${product.product_id}_${product.product_variant_id}_${product.identity_key}` : `${product.product_id}_${product.product_variant_id}_${(0, import_utils.buildProductLineFingerprint)(
+          product.product_option_item,
+          product.product_bundle
+        )}`,
         price: product.selling_price,
         total: new import_decimal.default(product.selling_price || 0).times(product.num || 1).toNumber(),
         origin_total: new import_decimal.default(product.original_price || product.selling_price || 0).times(product.num || 1).toNumber(),
@@ -152,6 +159,23 @@ function formatDateTime(date) {
 function normalizeSubmitPlatform(platform) {
   return (platform == null ? void 0 : platform.toLowerCase()) === "pc" ? "PC" : "H5";
 }
+function formatSubmitOptionItems(options) {
+  if (!Array.isArray(options))
+    return [];
+  return options.map((d) => ({
+    num: d == null ? void 0 : d.num,
+    option_group_item_id: (d == null ? void 0 : d.option_group_item_id) ?? (d == null ? void 0 : d.product_option_item_id),
+    option_group_id: d == null ? void 0 : d.option_group_id
+  }));
+}
+function formatSubmitBundleItems(bundle) {
+  if (!Array.isArray(bundle))
+    return [];
+  return bundle.map((b) => ({
+    ...b,
+    option: formatSubmitOptionItems(b == null ? void 0 : b.option)
+  }));
+}
 function normalizeSubmitProduct(product) {
   const { _origin, identity_key, ...submitProduct } = product;
   const rawMetadata = submitProduct.metadata || {};
@@ -179,9 +203,9 @@ function normalizeSubmitProduct(product) {
   return {
     ...submitProduct,
     ...bookingUid ? { booking_uid: bookingUid } : {},
-    product_option_item: submitProduct.product_option_item || [],
+    product_option_item: formatSubmitOptionItems(submitProduct.product_option_item),
     discount_list: submitProduct.discount_list || [],
-    product_bundle: submitProduct.product_bundle || [],
+    product_bundle: formatSubmitBundleItems(submitProduct.product_bundle),
     metadata: cleanMetadata,
     // 出站兼容：后端仍消费 payment_price 字段，从 selling_price（券后单价）派生。
     payment_price: submitProduct.selling_price
@@ -382,6 +406,7 @@ function formatV1Product(products) {
       product_id: product.product_id,
       product_variant_id: product.product_variant_id,
       num: product.num,
+      note: String(product.note ?? ""),
       rowKey: product.product_id,
       session: null,
       unique: createUuidV4()

package/lib/solution/ScanOrder/index.d.ts

@@ -1,6 +1,7 @@
 import { Module, ModuleOptions, PisellCore } from '../../types';
 import { BaseModule } from '../../modules/BaseModule';
 import { ScanOrderAddLogParams, ScanOrderAvailabilityInfo, ScanOrderOrderProduct, ScanOrderOrderProductIdentity, ScanOrderScanCodeResult } from './types';
+import type { UpdateProductInOrderParams } from '../../modules/Order/types';
 import type { Discount } from '../../modules/Discount/types';
 import { type CartItemSummary, type PaxInfo, type QuantityCheckResult, type QuantityLimitResult } from '../../model/strategy/adapter/itemRule';
 import type { StrategyConfig } from '../../model/strategy/type';
@@ -85,11 +86,12 @@ export declare class ScanOrderImpl extends BaseModule implements Module {
     private buildSubmitPayloadEnhancer;
     submitScanOrder<T = any>(): Promise<T>;
     addProductToOrder(product: Partial<ScanOrderOrderProduct> & ScanOrderOrderProductIdentity): Promise<ScanOrderOrderProduct[]>;
-    updateProductInOrder(params: {
-        product_id: number | null;
-        product_variant_id: number;
-        updates: Partial<ScanOrderOrderProduct>;
-    }): Promise<ScanOrderOrderProduct[]>;
+    updateProductInOrder(params: UpdateProductInOrderParams): Promise<ScanOrderOrderProduct[]>;
+    /**
+     * 设置单行商品备注（与整单 `updateTempOrderNote` 区分）。
+     * 多行同 SKU 时必须传入与删除/更新一致的 identity（如 `identity_key`）。
+     */
+    setOrderProductLineNote(identity: ScanOrderOrderProductIdentity, note: string): Promise<ScanOrderOrderProduct[]>;
     removeProductFromOrder(identity: ScanOrderOrderProductIdentity): Promise<ScanOrderOrderProduct[]>;
     private loadRuntimeConfigs;
     private syncItemRuleConfigsFromDineInConfig;

package/lib/solution/ScanOrder/index.js

@@ -892,6 +892,36 @@ var _ScanOrderImpl = class extends import_BaseModule.BaseModule {
       throw error;
     }
   }
+  /**
+   * 设置单行商品备注（与整单 `updateTempOrderNote` 区分）。
+   * 多行同 SKU 时必须传入与删除/更新一致的 identity（如 `identity_key`）。
+   */
+  async setOrderProductLineNote(identity, note) {
+    this.logMethodStart("setOrderProductLineNote", {
+      product_id: identity.product_id,
+      product_variant_id: identity.product_variant_id
+    });
+    try {
+      const params = {
+        product_id: identity.product_id,
+        product_variant_id: identity.product_variant_id,
+        updates: { note: String(note || "") }
+      };
+      if (identity.identity_key !== void 0)
+        params.identity_key = identity.identity_key;
+      if (identity.product_option_item !== void 0) {
+        params.product_option_item = identity.product_option_item;
+      }
+      if (identity.product_bundle !== void 0)
+        params.product_bundle = identity.product_bundle;
+      const products = await this.updateProductInOrder(params);
+      this.logMethodSuccess("setOrderProductLineNote", { productCount: products.length });
+      return products;
+    } catch (error) {
+      this.logMethodError("setOrderProductLineNote", error);
+      throw error;
+    }
+  }
   async removeProductFromOrder(identity) {
     this.logMethodStart("removeProductFromOrder", {
       product_id: identity.product_id,