@pisell/pisellos 0.10.43 → 0.10.45

package/lib/modules/Order/index.js

@@ -9,7 +9,9 @@ var _types = require("./types");
 var _utils = require("./utils");
 var _utils2 = require("../Product/utils");
 var _dayjs = _interopRequireDefault(require("dayjs"));
+var _availability = require("../Discount/availability");
 var _osPrivatePayload = require("../../utils/os-private-payload");
+var _salesNotes = require("./salesNotes");
 var _paymentUtils = require("./payment-utils");
 var _paymentNumber = require("../../utils/payment-number");
 var _cartPromotion = require("../../solution/BaseSales/utils/cartPromotion");
@@ -126,6 +128,8 @@ class OrderModule extends _BaseModule.BaseModule {
   openCache = false;
   sessionStoragePersistEnabled = false;
   sessionStorageRestoreRecord = null;
+  /** 只允许当前订单最新的 prepare/config 请求回写客户资产态。 */
+  customerWalletPrepareConfigEpoch = 0;
   salesSummaryModuleName;
   rulesHooksOverride;
   moduleHooksOverride;
@@ -136,8 +140,10 @@ class OrderModule extends _BaseModule.BaseModule {
   promotionEvaluator = null;
   /** 赠品选择 resolver；由 SDK host bridge 注入 */
   giftSelectResolver = null;
-  /** applyPromotion 递归保护 flag（写路径同步调 applyPromotion，禁止重入） */
+  /** 促销评估递归保护 flag（写路径同步评估促销，禁止重入） */
   isApplyingPromotion = false;
+  /** 保持旧事件语义：同步事件监听器内触发的订单写入不得递归评估促销。 */
+  isEmittingPromotionApplied = false;
   /** 商品曾应用过客户券卡，客户变更剥离后需强制跑一次 calcDiscount 复位价格 */
   hasActiveCustomerBoundDiscount = false;
   /** 最近一次 applyPromotion 的未满足促销提示 */
@@ -491,13 +497,24 @@ class OrderModule extends _BaseModule.BaseModule {
     this.store.rules = rules;
   }
   createDefaultRulesHooks() {
-    return (0, _utils.createDefaultOrderRulesHooks)();
+    return (0, _utils.createDefaultOrderRulesHooks)(() => this.store.tempOrder?.bookings || []);
+  }
+
+  /**
+   * Stable across notifyTempOrderChanged's immutable copy, but changes when a
+   * different local/server order becomes current.
+   */
+  getDiscountConfigOrderIdentityKey(tempOrder) {
+    const identity = this.getOrderIdentity();
+    return JSON.stringify([identity?.orderId ?? tempOrder?.order_id ?? '', tempOrder?.request_unique_idempotency_token ?? '', identity?.externalSaleNumber ?? tempOrder?.external_sale_number ?? '', identity?.localId ?? tempOrder?._extend?.localId ?? this.cacheId ?? '']);
   }
 
   // ─── Discount: 公共 API ───
 
   async loadDiscountConfig(params) {
     const orderId = params.orderId || this.store.tempOrder?.order_id || undefined;
+    const requestEpoch = ++this.customerWalletPrepareConfigEpoch;
+    const requestOrderIdentityKey = this.getDiscountConfigOrderIdentityKey(this.store.tempOrder);
     const prepareConfigResult = await this.store.discount?.loadPrepareConfig({
       customer_id: params.customerId,
       action: params.action || (orderId ? 'edit' : 'create'),
@@ -508,18 +525,23 @@ class OrderModule extends _BaseModule.BaseModule {
       with_available_wallet_pass_flag: 1,
       with_virtual_currency: 1,
       with_entitlement_pass: 1,
+      filter_order_wallet_pass_usage: 0,
       request_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
       ...(orderId ? {
         order_id: orderId
       } : {})
     });
+    const isCurrentRequest = () => requestEpoch === this.customerWalletPrepareConfigEpoch && this.getDiscountConfigOrderIdentityKey(this.store.tempOrder) === requestOrderIdentityKey && String(this.store.tempOrder?.customer_id ?? '') === String(params.customerId);
+    if (!isCurrentRequest()) {
+      return this.getDiscountList();
+    }
     const discountList = prepareConfigResult?.discountList;
-    this.store.availableWalletIds = prepareConfigResult?.availableWalletIds || [];
-    this.store.virtualCurrencyList = prepareConfigResult?.virtualCurrencyList || [];
     if (prepareConfigResult) {
-      this.writePointCardSnapshotFromPrepareConfig({
+      this.writeCustomerWalletSnapshotsFromPrepareConfig({
         customerId: params.customerId,
-        availableWalletPassList: prepareConfigResult.availableWalletPassList || []
+        availableWalletIds: prepareConfigResult.availableWalletIds || [],
+        availableWalletPassList: prepareConfigResult.availableWalletPassList || [],
+        virtualCurrencyList: prepareConfigResult.virtualCurrencyList || []
       });
     }
     if (discountList) {
@@ -579,9 +601,12 @@ class OrderModule extends _BaseModule.BaseModule {
         return id === null || !refreshedScanDiscountIds.has(id);
       });
       const mergedDiscountList = [...retainedCommittedDiscounts, ...retainedScanDiscounts, ...runtimeDiscounts];
+      if (!isCurrentRequest()) return this.getDiscountList();
       await this.store.discount?.setOriginalDiscountList(mergedDiscountList);
+      if (!isCurrentRequest()) return this.getDiscountList();
       await this.store.discount?.setDiscountList(mergedDiscountList);
     }
+    if (!isCurrentRequest()) return this.getDiscountList();
     if (params.apply !== false && this.store.tempOrder?.products?.length) {
       this.applyDiscount();
     }
@@ -596,6 +621,9 @@ class OrderModule extends _BaseModule.BaseModule {
   getVirtualCurrencyList() {
     return (0, _lodashEs.cloneDeep)(this.store.virtualCurrencyList || []);
   }
+  getCustomerWalletPrepareConfigEpoch() {
+    return this.customerWalletPrepareConfigEpoch;
+  }
   async syncScannedDiscountsToOriginalDiscountList(discountList) {
     const scanDiscounts = (discountList || []).filter(discount => discount?.isScan);
     if (!scanDiscounts.length) return;
@@ -693,19 +721,31 @@ class OrderModule extends _BaseModule.BaseModule {
       isAvailable: false,
       discountList: this.getDiscountList()
     };
-    const shouldRetainForLater = !isAvailable && unavailableReason === _types2.UnavailableReason.ProductNotApplicable && withScanList.some(isCustomerPromotionDiscount);
+    const scannedIds = new Set(withScanList.map(discount => String(discount.id)));
+    const evaluatedScannedDiscounts = (evaluatedDiscountList || withScanList).filter(discount => scannedIds.has(String(discount.id)) && isCustomerPromotionDiscount(discount) && !(0, _availability.getDiscountLifecycleReason)(discount));
+    const shouldRetainForLater = !isAvailable && evaluatedScannedDiscounts.length > 0;
     const normalizedNewDiscountList = newDiscountList ? markScannedDiscounts(newDiscountList, withScanList) : undefined;
-    const retainedDiscountList = evaluatedDiscountList ? markScannedDiscounts(evaluatedDiscountList, withScanList) : normalizedNewDiscountList;
     let resolvedDiscountList = normalizedNewDiscountList || this.getDiscountList();
     if (isAvailable && normalizedNewDiscountList) {
       await this.store.discount?.setDiscountList(normalizedNewDiscountList);
       this.applyDiscount();
       await this.syncScannedDiscountsToOriginalDiscountList(this.getDiscountList());
       resolvedDiscountList = this.getDiscountList();
-    } else if (shouldRetainForLater && retainedDiscountList) {
-      // 卡券有效但当前购物车没有适用商品：先保留在 Promotion 中，
-      // 不执行 applyDiscount，避免修改商品价格或订单金额。
-      await this.store.discount?.setDiscountList(retainedDiscountList);
+    } else if (shouldRetainForLater) {
+      // 只合并本次识别的卡券；不把试算产生的其他选券状态写回订单。
+      const retainedDiscounts = new Map(this.getDiscountList().map(discount => [String(discount.id), discount]));
+      evaluatedScannedDiscounts.forEach(discount => {
+        retainedDiscounts.set(String(discount.id), {
+          ...discount,
+          isScan: true,
+          isAvailable: false,
+          isSelected: false,
+          reasonCode: discount.reasonCode || 'product_not_applicable',
+          appliedProductDetails: [],
+          savedAmount: 0
+        });
+      });
+      await this.store.discount?.setDiscountList([...retainedDiscounts.values()]);
       await this.syncScannedDiscountsToOriginalDiscountList(this.getDiscountList());
       resolvedDiscountList = this.getDiscountList();
     }
@@ -714,7 +754,7 @@ class OrderModule extends _BaseModule.BaseModule {
       isAvailable: isAvailable || false,
       isAccepted: Boolean(isAvailable || shouldRetainForLater),
       discountList: resolvedDiscountList,
-      scannedDiscountList: resultDiscountList,
+      scannedDiscountList: evaluatedScannedDiscounts,
       unavailableReason
     };
   }
@@ -808,7 +848,7 @@ class OrderModule extends _BaseModule.BaseModule {
   }
 
   /**
-   * 应用购物车促销：计算 → 差异化赠品 → 写回 tempOrder.products → emit onPromotionApplied。
+   * 只执行购物车促销评估与赠品写回，不发布稳定态事件。
    *
    * 调用时机：写路径（add/update/remove/clear/setCustomer）末尾自动触发；外部一般无需手动调。
    *
@@ -816,26 +856,27 @@ class OrderModule extends _BaseModule.BaseModule {
    * - 不调用任何公开 CRUD API（如 removeProductFromOrder），全部内部 mutate tempOrder.products，避免事件风暴；
    * - 用 `isApplyingPromotion` 防递归；
    * - 多选项赠品依赖 giftSelectResolver，未注入则跳过且 console.warn；
-   * - 不主动调用 applyDiscount / recalculateSummary，调用方负责跟进。
+   * - 不主动调用 applyDiscount / recalculateSummary，调用方负责跟进；
+   * - 返回的 payload 只能在 applyDiscount（商品写路径还需 summary/persist）完成后发布。
    */
-  async applyPromotion() {
-    if (this.isApplyingPromotion) {
-      return;
+  async evaluatePromotion() {
+    if (this.isApplyingPromotion || this.isEmittingPromotionApplied) {
+      return null;
     }
     if (!this.promotionEvaluator) {
-      return;
+      return null;
     }
     const tempOrder = this.store.tempOrder;
     if (!tempOrder) {
-      return;
+      return null;
     }
     if (this.isActiveVirtualSettlementOrder(tempOrder)) {
       tempOrder.products = (0, _virtualSettlement.normalizeVirtualSettlementProducts)(tempOrder.products);
-      return;
+      return null;
     }
     const strategyConfigs = this.promotionEvaluator.getStrategyConfigs?.();
     if (Array.isArray(strategyConfigs) && strategyConfigs.length === 0) {
-      return;
+      return null;
     }
     this.isApplyingPromotion = true;
     try {
@@ -927,14 +968,46 @@ class OrderModule extends _BaseModule.BaseModule {
         })),
         products: tempOrder.products
       };
-      this.effectsEmit('onPromotionApplied', payload);
+      return payload;
     } catch (error) {
       console.error('[OrderModule] applyPromotion failed', error);
+      return null;
     } finally {
       this.isApplyingPromotion = false;
     }
   }
 
+  /** 发布促销稳定态；products 必须读取折扣计算后的当前数组。 */
+  emitPromotionApplied(payload) {
+    if (!payload) return;
+    const products = this.store.tempOrder?.products || payload.products;
+    this.isEmittingPromotionApplied = true;
+    try {
+      void this.effectsEmit('onPromotionApplied', {
+        ...payload,
+        products
+      });
+    } finally {
+      // effectsEmit 同步调用监听器后返回 Promise；保持既有的非阻塞事件行为。
+      this.isEmittingPromotionApplied = false;
+    }
+  }
+
+  /** 公开入口：促销、折扣、summary 与持久化完成后发布稳定态事件。 */
+  async applyPromotion() {
+    const payload = await this.evaluatePromotion();
+    if (!payload) return;
+    const tempOrder = this.store.tempOrder;
+    if (!tempOrder) return;
+    this.applyDiscount();
+    this.sanitizeTempOrderProducts(tempOrder);
+    await this.recalculateSummary({
+      createIfMissing: true
+    });
+    this.persistTempOrder();
+    this.emitPromotionApplied(payload);
+  }
+
   /** 最近一次 applyPromotion 输出的未满足促销列表 */
   getUnfulfilledPromotions() {
     return this.lastUnfulfilledPromotions;
@@ -1038,6 +1111,7 @@ class OrderModule extends _BaseModule.BaseModule {
     this.store.tempOrder = {
       ...this.store.tempOrder,
       products: [...this.store.tempOrder.products],
+      notes: [...(this.store.tempOrder.notes || [])],
       bookings: this.store.tempOrder.bookings ? [...this.store.tempOrder.bookings] : []
     };
     this.persistTempOrder();
@@ -1050,27 +1124,41 @@ class OrderModule extends _BaseModule.BaseModule {
       now: (0, _utils.formatDateTime)(new Date())
     });
   }
-  clearTempOrderPointCardSnapshot(tempOrder) {
+  clearTempOrderCustomerWalletSnapshots(tempOrder) {
     const orderMetaList = (0, _utils.normalizeOrderMetaList)(tempOrder.order_meta_list);
     if (!orderMetaList) return;
     const nextOrderMetaList = {
       ...orderMetaList
     };
     delete nextOrderMetaList.point_cards_snapshot;
+    delete nextOrderMetaList.virtual_currency_snapshot;
     if (Object.keys(nextOrderMetaList).length === 0) {
       delete tempOrder.order_meta_list;
       return;
     }
     tempOrder.order_meta_list = nextOrderMetaList;
   }
-  writePointCardSnapshotFromPrepareConfig(params) {
+  clearCustomerWalletState(tempOrder) {
+    this.clearCustomerWalletRuntimeState();
+    this.clearTempOrderCustomerWalletSnapshots(tempOrder);
+  }
+  clearCustomerWalletRuntimeState() {
+    this.customerWalletPrepareConfigEpoch += 1;
+    this.store.availableWalletIds = [];
+    this.store.virtualCurrencyList = [];
+  }
+  writeCustomerWalletSnapshotsFromPrepareConfig(params) {
     const tempOrder = this.store.tempOrder;
     if (!tempOrder) return;
     if (String(tempOrder.customer_id ?? '') !== String(params.customerId)) return;
+    const virtualCurrencyList = Array.isArray(params.virtualCurrencyList) ? params.virtualCurrencyList : [];
     tempOrder.order_meta_list = {
       ...((0, _utils.normalizeOrderMetaList)(tempOrder.order_meta_list) || {}),
-      point_cards_snapshot: (0, _utils.buildPointCardSnapshotFromWalletPassList)(params.availableWalletPassList)
+      point_cards_snapshot: (0, _utils.buildPointCardSnapshotFromWalletPassList)(params.availableWalletPassList),
+      virtual_currency_snapshot: (0, _utils.buildVirtualCurrencySnapshotFromList)(virtualCurrencyList)
     };
+    this.store.availableWalletIds = [...params.availableWalletIds];
+    this.store.virtualCurrencyList = (0, _lodashEs.cloneDeep)(virtualCurrencyList);
     this.persistTempOrder();
     this.saveDraftInBackground();
   }
@@ -1855,6 +1943,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const freshTempOrder = this.createDefaultTempOrderInstance();
     this.ensureExternalSaleNumber(freshTempOrder);
     this.store.tempOrder = freshTempOrder;
+    this.clearCustomerWalletRuntimeState();
     this.store.summary = (0, _utils.createEmptySummary)();
     this.store.lastOrderInfo = undefined;
     this.store.syncState = undefined;
@@ -1875,6 +1964,7 @@ class OrderModule extends _BaseModule.BaseModule {
       ensureIdentity: false
     });
     this.store.tempOrder = nextTempOrder;
+    this.clearCustomerWalletRuntimeState();
     if (options?.recalculateSummary !== false) {
       await this.recalculateSummary({
         createIfMissing: false
@@ -2398,6 +2488,179 @@ class OrderModule extends _BaseModule.BaseModule {
   getTempOrderNote() {
     return this.store.tempOrder?.note || '';
   }
+  ensureSalesNotesRuntimeState(tempOrder) {
+    const hadNotesSnapshot = Array.isArray(tempOrder.notes);
+    if (!Array.isArray(tempOrder.notes)) tempOrder.notes = [];
+    if (!tempOrder._extend || typeof tempOrder._extend !== 'object') {
+      tempOrder._extend = {
+        productsByUid: {}
+      };
+    }
+    if (!tempOrder._extend.salesNotesState) {
+      tempOrder._extend.salesNotesState = {
+        loaded: hadNotesSnapshot,
+        dirty: false
+      };
+    }
+    return tempOrder._extend.salesNotesState;
+  }
+  ensureSalesNotesLoadedForMutation(tempOrder) {
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    if (state.loaded) return;
+    if (tempOrder.order_id === null || tempOrder.order_id === undefined) {
+      state.loaded = true;
+      tempOrder.notes = [];
+      return;
+    }
+    throw new Error('[Order Notes] 当前订单 Notes 尚未完整加载，禁止提交部分快照');
+  }
+  normalizeSalesNoteUuid(value, field) {
+    const uuid = String(value ?? '').trim();
+    if (!uuid) throw new Error(`[Order Notes] ${field} 不能为空`);
+    if (uuid.length > 255) {
+      throw new Error(`[Order Notes] ${field} 不能超过 255 个字符`);
+    }
+    return uuid;
+  }
+  getSalesNotePrimaryRelation(note) {
+    return note.note_relations.find(relation => relation.is_primary === 1) || null;
+  }
+  removeSalesNotesForMissingProductLines(tempOrder) {
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    if (!state.loaded || !Array.isArray(tempOrder.notes) || tempOrder.notes.length === 0) {
+      return;
+    }
+    const remainingProductUids = new Set((tempOrder.products || []).map(product => product.metadata?.unique_identification_number || product.unique_identification_number).filter(uid => typeof uid === 'string' && uid.length > 0));
+    const nextNotes = tempOrder.notes.filter(note => {
+      const primary = this.getSalesNotePrimaryRelation(note);
+      if (!primary || primary.target_type !== 'order_detail') return true;
+      return remainingProductUids.has(primary.target_uuid);
+    });
+    if (nextNotes.length === tempOrder.notes.length) return;
+    tempOrder.notes = nextNotes;
+    state.dirty = true;
+  }
+  setSalesNoteOnTempOrder(tempOrder, input) {
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    const note_type = String(input.note_type || '').trim();
+    const policy = (0, _salesNotes.getSalesNotePolicy)(note_type);
+    if (!policy) {
+      throw new Error(`[Order Notes] 当前未注册备注类型: ${note_type || '(empty)'}`);
+    }
+    if (input.target?.target_type !== 'order_detail') {
+      throw new Error('[Order Notes] 本期只支持 order_detail 作为主体');
+    }
+    const target_uuid = this.normalizeSalesNoteUuid(input.target.target_uuid, 'target_uuid');
+    const targetProductExists = (tempOrder.products || []).some(product => {
+      const productLineUid = product.metadata?.unique_identification_number || product.unique_identification_number;
+      return String(productLineUid ?? '') === target_uuid;
+    });
+    if (!targetProductExists) {
+      throw new Error('[Order Notes] 目标商品行不存在');
+    }
+    const text = (0, _salesNotes.buildSalesNoteText)(input.text);
+    const notes = tempOrder.notes || [];
+    // 当前 allergy policy 固定同一商品行只保留一条；业务调用方不参与去重规则。
+    const existingIndex = policy.uniquePerPrimaryTarget ? notes.findIndex(note => {
+      const primary = this.getSalesNotePrimaryRelation(note);
+      return note.note_type === note_type && primary?.target_type === 'order_detail' && primary.target_uuid === target_uuid;
+    }) : -1;
+    const existing = existingIndex >= 0 ? notes[existingIndex] : null;
+    const existingPrimary = existing?.note_relations.find(relation => relation.is_primary === 1 && relation.target_type === 'order_detail');
+    const existingOrderRelation = existing?.note_relations.find(relation => relation.is_primary === 0 && relation.target_type === 'order');
+    const note = {
+      uuid: existing?.uuid || (0, _utils.createUuidV4)(),
+      note_type: policy.note_type,
+      content: {
+        text
+      },
+      importance: policy.importance,
+      note_relations: [{
+        uuid: existingPrimary?.uuid || (0, _utils.createUuidV4)(),
+        relation_type: policy.primary_relation_type,
+        target_type: 'order_detail',
+        target_uuid,
+        is_primary: 1
+      }, {
+        uuid: existingOrderRelation?.uuid || (0, _utils.createUuidV4)(),
+        relation_type: policy.secondary_order_relation_type,
+        target_type: 'order',
+        target_uuid: String(tempOrder.shop_order_number ?? ''),
+        is_primary: 0
+      }]
+    };
+    const duplicateIndex = notes.findIndex((item, index) => item.uuid === note.uuid && index !== existingIndex);
+    if (duplicateIndex >= 0) {
+      throw new Error('[Order Notes] uuid 已被其他 Note 使用');
+    }
+    tempOrder.notes = existingIndex >= 0 ? notes.map((item, index) => index === existingIndex ? note : item) : [...notes, note];
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    state.loaded = true;
+    state.dirty = true;
+    return note;
+  }
+  getSalesNotes() {
+    const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesRuntimeState(tempOrder);
+    return (0, _lodashEs.cloneDeep)(tempOrder.notes || []);
+  }
+  createSalesNotesMutationSnapshot() {
+    const tempOrder = this.ensureTempOrder();
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    return {
+      orderIdentity: {
+        orderId: tempOrder.order_id ?? null,
+        externalSaleNumber: String(tempOrder.external_sale_number || '')
+      },
+      notes: (0, _lodashEs.cloneDeep)(tempOrder.notes || []),
+      state: (0, _lodashEs.cloneDeep)(state)
+    };
+  }
+  restoreSalesNotesMutationSnapshot(snapshot) {
+    if (!snapshot || !Array.isArray(snapshot.notes) || !snapshot.orderIdentity || typeof snapshot.orderIdentity.externalSaleNumber !== 'string' || typeof snapshot.state?.loaded !== 'boolean' || typeof snapshot.state?.dirty !== 'boolean') {
+      throw new Error('[Order Notes] 无效的 mutation snapshot');
+    }
+    const tempOrder = this.store.tempOrder;
+    if (!tempOrder) throw new Error('[Order Notes] 当前订单不存在');
+    const snapshotOrderId = snapshot.orderIdentity.orderId;
+    const currentOrderId = tempOrder.order_id;
+    const hasSnapshotOrderId = snapshotOrderId !== null && snapshotOrderId !== undefined && String(snapshotOrderId).trim().length > 0;
+    const hasCurrentOrderId = currentOrderId !== null && currentOrderId !== undefined && String(currentOrderId).trim().length > 0;
+    const isSameOrder = hasSnapshotOrderId && hasCurrentOrderId ? String(snapshotOrderId) === String(currentOrderId) : Boolean(snapshot.orderIdentity.externalSaleNumber) && snapshot.orderIdentity.externalSaleNumber === String(tempOrder.external_sale_number || '');
+    if (!isSameOrder) {
+      throw new Error('[Order Notes] 当前订单已切换，拒绝恢复旧订单快照');
+    }
+    this.ensureSalesNotesRuntimeState(tempOrder);
+    tempOrder.notes = (0, _lodashEs.cloneDeep)(snapshot.notes);
+    tempOrder._extend.salesNotesState = (0, _lodashEs.cloneDeep)(snapshot.state);
+    this.notifyTempOrderChanged();
+  }
+  async setSalesNote(input) {
+    const tempOrder = this.ensureTempOrder();
+    const note = this.setSalesNoteOnTempOrder(tempOrder, input);
+    this.notifyTempOrderChanged();
+    return (0, _lodashEs.cloneDeep)(note);
+  }
+  async removeSalesNote(uuid) {
+    const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    const normalizedUuid = this.normalizeSalesNoteUuid(uuid, 'uuid');
+    const notes = tempOrder.notes || [];
+    const nextNotes = notes.filter(note => note.uuid !== normalizedUuid);
+    if (nextNotes.length === notes.length) return;
+    tempOrder.notes = nextNotes;
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    state.dirty = true;
+    this.notifyTempOrderChanged();
+  }
+  async clearSalesNotes() {
+    const tempOrder = this.ensureTempOrder();
+    tempOrder.notes = [];
+    const state = this.ensureSalesNotesRuntimeState(tempOrder);
+    state.loaded = true;
+    state.dirty = true;
+    this.notifyTempOrderChanged();
+  }
   updateTempOrderShopDiscount(amount) {
     const tempOrder = this.ensureTempOrder();
     const discount = _decimal.default.max(new _decimal.default(Number(amount) || 0), 0).toDecimalPlaces(2).toFixed(2);
@@ -2437,6 +2700,31 @@ class OrderModule extends _BaseModule.BaseModule {
     this.persistTempOrder();
     return tempOrder.buzzer;
   }
+  updateTempOrderShopServiceData(patch) {
+    const tempOrder = this.ensureTempOrder();
+    const metadata = tempOrder.metadata && typeof tempOrder.metadata === 'object' && !Array.isArray(tempOrder.metadata) ? tempOrder.metadata : {};
+    const currentShopServiceData = metadata.shop_service_data && typeof metadata.shop_service_data === 'object' && !Array.isArray(metadata.shop_service_data) ? metadata.shop_service_data : {};
+    const shopServiceData = {
+      ...currentShopServiceData,
+      ...patch
+    };
+    tempOrder.metadata = {
+      ...metadata,
+      shop_service_data: shopServiceData
+    };
+    this.persistTempOrder();
+    return shopServiceData;
+  }
+  updateTempOrderPickupReferenceMode(mode) {
+    return this.updateTempOrderShopServiceData({
+      pickup_reference_mode: mode
+    });
+  }
+  updateTempOrderServiceType(serviceType) {
+    return this.updateTempOrderShopServiceData({
+      service_type: serviceType
+    });
+  }
   updateTempOrderContactsInfo(contactsInfo) {
     const tempOrder = this.ensureTempOrder();
     tempOrder.contacts_info = contactsInfo && typeof contactsInfo === 'object' && !Array.isArray(contactsInfo) ? contactsInfo : null;
@@ -2547,8 +2835,7 @@ class OrderModule extends _BaseModule.BaseModule {
     });
     const nextCustomerId = tempOrder.customer_id ?? null;
     if (String(previousCustomerId ?? '') !== String(nextCustomerId ?? '')) {
-      this.store.availableWalletIds = [];
-      this.clearTempOrderPointCardSnapshot(tempOrder);
+      this.clearCustomerWalletState(tempOrder);
     }
     this.persistTempOrder();
     return {
@@ -2584,9 +2871,7 @@ class OrderModule extends _BaseModule.BaseModule {
     }
     const nextCustomerId = tempOrder.customer_id ?? null;
     if (String(previousCustomerId ?? '') !== String(nextCustomerId ?? '')) {
-      this.store.availableWalletIds = [];
-      this.store.virtualCurrencyList = [];
-      this.clearTempOrderPointCardSnapshot(tempOrder);
+      this.clearCustomerWalletState(tempOrder);
       (0, _utils.clearTempOrderHolderAssignments)(tempOrder);
       this.clearCustomerBoundDiscounts(tempOrder);
       this.applyDiscount();
@@ -2624,9 +2909,7 @@ class OrderModule extends _BaseModule.BaseModule {
     tempOrder.email = '';
     tempOrder.customer = null;
     if (tempOrder._extend) delete tempOrder._extend.customerSnapshot;
-    this.store.availableWalletIds = [];
-    this.store.virtualCurrencyList = [];
-    this.clearTempOrderPointCardSnapshot(tempOrder);
+    this.clearCustomerWalletState(tempOrder);
     this.clearCustomerBoundDiscounts(tempOrder);
     this.applyDiscount();
     this.persistTempOrder();
@@ -3034,9 +3317,7 @@ class OrderModule extends _BaseModule.BaseModule {
     if (!options?.skipEditDiscountConfigRefresh && !isVirtualSettlement) {
       await this.ensureEditDiscountConfigForProductChange(tempOrder);
     }
-    if (!options?.skipDiscountRecalculation && !isVirtualSettlement) {
-      await this.applyPromotion();
-    }
+    const promotionPayload = !options?.skipDiscountRecalculation && !isVirtualSettlement ? await this.evaluatePromotion() : null;
     if (!options?.skipDiscountRecalculation && !isVirtualSettlement) {
       this.applyDiscount();
     }
@@ -3045,6 +3326,7 @@ class OrderModule extends _BaseModule.BaseModule {
       createIfMissing: true
     });
     this.persistTempOrder();
+    this.emitPromotionApplied(promotionPayload);
   }
 
   /**
@@ -3127,6 +3409,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const matchedProduct = matchedIndex === -1 ? null : tempOrder.products[matchedIndex];
     const existedFingerprint = matchedProduct ? (0, _utils3.buildProductLineFingerprint)((0, _utils.getProductSkuOptions)(matchedProduct), matchedProduct.product_bundle) : '';
     const commitProductLine = shouldMerge => {
+      let committedProduct;
       if (matchedIndex === -1 || !matchedProduct || !shouldMerge) {
         this.captureProductRuntime(tempOrder, productToAdd, normalizedIncoming);
         if (linked) {
@@ -3142,6 +3425,7 @@ class OrderModule extends _BaseModule.BaseModule {
         } else {
           tempOrder.products = [...tempOrder.products, normalizedIncoming];
         }
+        committedProduct = normalizedIncoming;
       } else {
         const targetProduct = matchedProduct;
         const targetUid = targetProduct.metadata?.unique_identification_number;
@@ -3177,6 +3461,7 @@ class OrderModule extends _BaseModule.BaseModule {
           num: nextNum
         };
         this.captureProductRuntime(tempOrder, productToAdd, tempOrder.products[matchedIndex], targetUid);
+        committedProduct = tempOrder.products[matchedIndex];
         if (matchedIndex !== tempOrder.products.length - 1) {
           const mergedProduct = tempOrder.products[matchedIndex];
           tempOrder.products = [...tempOrder.products.slice(0, matchedIndex), ...tempOrder.products.slice(matchedIndex + 1), mergedProduct];
@@ -3185,10 +3470,10 @@ class OrderModule extends _BaseModule.BaseModule {
       if (linked) {
         tempOrder.bookings = [...(tempOrder.bookings || []), linked.booking];
       }
+      return committedProduct;
     };
     if (!matchedProduct) {
-      commitProductLine(false);
-      return;
+      return commitProductLine(false);
     }
     const shouldMerge = this.shouldMergeProductToOrder({
       incomingProduct: productToAdd,
@@ -3203,7 +3488,7 @@ class OrderModule extends _BaseModule.BaseModule {
     if (shouldMerge && typeof shouldMerge === 'object' && typeof shouldMerge.then === 'function') {
       return Promise.resolve(shouldMerge).then(commitProductLine);
     }
-    commitProductLine(shouldMerge);
+    return commitProductLine(shouldMerge);
   }
 
   /**
@@ -3276,34 +3561,99 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async addProductToOrder(product, booking, options) {
     const tempOrder = this.ensureTempOrder();
+    const salesNoteDrafts = (options?.salesNotes || []).map(draft => ({
+      note_type: String(draft.note_type || '').trim(),
+      text: {
+        kind: 'resolved',
+        text: (0, _salesNotes.buildSalesNoteText)(draft.text)
+      }
+    }));
+    const mutationSnapshot = salesNoteDrafts.length > 0 ? {
+      products: (0, _lodashEs.cloneDeep)(tempOrder.products || []),
+      bookings: (0, _lodashEs.cloneDeep)(tempOrder.bookings || []),
+      notes: (0, _lodashEs.cloneDeep)(tempOrder.notes || []),
+      extend: (0, _lodashEs.cloneDeep)(tempOrder._extend || {})
+    } : null;
+    const attachSalesNoteDrafts = orderProduct => {
+      if (!salesNoteDrafts.length) return;
+      const productLineUid = orderProduct.metadata?.unique_identification_number || orderProduct.unique_identification_number;
+      if (!productLineUid) {
+        throw new Error('[Order Notes] 商品行缺少 unique_identification_number');
+      }
+      salesNoteDrafts.forEach(draft => {
+        this.setSalesNoteOnTempOrder(tempOrder, {
+          note_type: draft.note_type,
+          target: {
+            target_type: 'order_detail',
+            target_uuid: String(productLineUid)
+          },
+          text: draft.text
+        });
+      });
+    };
+    const rollbackProductAndNotesMutation = () => {
+      if (!mutationSnapshot) return;
+      tempOrder.products = mutationSnapshot.products;
+      tempOrder.bookings = mutationSnapshot.bookings;
+      tempOrder.notes = mutationSnapshot.notes;
+      tempOrder._extend = mutationSnapshot.extend;
+    };
     const insertAfterProductUid = options?.insertAfterProductUid;
     const anchorIndex = booking && insertAfterProductUid ? tempOrder.products.findIndex(line => {
       const uid = line.metadata?.unique_identification_number || line.unique_identification_number;
       return uid !== undefined && uid !== null && String(uid) === String(insertAfterProductUid);
     }) : -1;
     let insertAtIndex = anchorIndex >= 0 ? anchorIndex + 1 : undefined;
-    if (booking) {
-      const productRecord = product;
-      const splitCount = (0, _utils3.getSafeProductNum)(productRecord.num ?? productRecord.product_quantity ?? 1);
-      if (splitCount > 1) {
-        for (let i = 0; i < splitCount; i += 1) {
-          const splitLine = this.createSplitBookingLine(productRecord, booking, i, splitCount);
-          const appendResult = this.appendProductLineToTempOrder(tempOrder, splitLine.product, splitLine.booking, {
+    try {
+      if (booking) {
+        const productRecord = product;
+        const splitCount = (0, _utils3.getSafeProductNum)(productRecord.num ?? productRecord.product_quantity ?? 1);
+        if (splitCount > 1) {
+          for (let i = 0; i < splitCount; i += 1) {
+            const splitLine = this.createSplitBookingLine(productRecord, booking, i, splitCount);
+            if (i > 0) {
+              delete splitLine.product.unique_identification_number;
+              delete splitLine.product.identity_key;
+              if (splitLine.product.metadata) {
+                splitLine.product.metadata = {
+                  ...splitLine.product.metadata
+                };
+                delete splitLine.product.metadata.unique_identification_number;
+                delete splitLine.product.metadata.identity_key;
+              }
+              delete splitLine.booking.booking_uid;
+              if (splitLine.booking.metadata) {
+                splitLine.booking.metadata = {
+                  ...splitLine.booking.metadata
+                };
+                delete splitLine.booking.metadata.unique_identification_number;
+              }
+            }
+            const committedProduct = await this.appendProductLineToTempOrder(tempOrder, splitLine.product, splitLine.booking, {
+              insertAtIndex,
+              disableMerge: options?.disableMerge
+            });
+            attachSalesNoteDrafts(committedProduct);
+            if (insertAtIndex !== undefined) insertAtIndex += 1;
+          }
+        } else {
+          const committedProduct = await this.appendProductLineToTempOrder(tempOrder, product, (0, _lodashEs.cloneDeep)(booking), {
             insertAtIndex,
             disableMerge: options?.disableMerge
           });
-          if (appendResult) await appendResult;
-          if (insertAtIndex !== undefined) insertAtIndex += 1;
+          attachSalesNoteDrafts(committedProduct);
         }
-        await this.finalizeProductOrderMutation(tempOrder);
-        return tempOrder.products;
+      } else {
+        const committedProduct = await this.appendProductLineToTempOrder(tempOrder, product, undefined, {
+          insertAtIndex,
+          disableMerge: options?.disableMerge
+        });
+        attachSalesNoteDrafts(committedProduct);
       }
+    } catch (error) {
+      rollbackProductAndNotesMutation();
+      throw error;
     }
-    const appendResult = this.appendProductLineToTempOrder(tempOrder, product, booking, {
-      insertAtIndex,
-      disableMerge: options?.disableMerge
-    });
-    if (appendResult) await appendResult;
     await this.finalizeProductOrderMutation(tempOrder);
     this.logInfo('addProductToOrder success', {
       product_id: product.product_id,
@@ -3626,7 +3976,7 @@ class OrderModule extends _BaseModule.BaseModule {
   async updateOrderProduct(params) {
     const tempOrder = this.ensureTempOrder();
     const updatedProductUid = this.applyOrderProductUpdateToTempOrder(tempOrder, params);
-    await this.applyPromotion();
+    const promotionPayload = await this.evaluatePromotion();
     this.applyDiscount({
       reapplyBookingDiscountProductUids: params.allow_booking_discount_reapply && updatedProductUid ? [String(updatedProductUid)] : undefined
     });
@@ -3635,6 +3985,7 @@ class OrderModule extends _BaseModule.BaseModule {
       createIfMissing: true
     });
     this.persistTempOrder();
+    this.emitPromotionApplied(promotionPayload);
     this.logInfo('updateOrderProduct success', {
       params
     });
@@ -3729,8 +4080,9 @@ class OrderModule extends _BaseModule.BaseModule {
     }
     tempOrder.products[productIndex] = normalizedProduct;
     this.prepareVirtualSettlementTempOrder(tempOrder);
-    if (!this.isActiveVirtualSettlementOrder(tempOrder)) {
-      await this.applyPromotion();
+    const isVirtualSettlement = this.isActiveVirtualSettlementOrder(tempOrder);
+    const promotionPayload = !isVirtualSettlement ? await this.evaluatePromotion() : null;
+    if (!isVirtualSettlement) {
       this.applyDiscount();
     }
     this.sanitizeTempOrderProducts(tempOrder);
@@ -3738,6 +4090,7 @@ class OrderModule extends _BaseModule.BaseModule {
       createIfMissing: true
     });
     this.persistTempOrder();
+    this.emitPromotionApplied(promotionPayload);
     this.logInfo('updateOrderProductQuantity success', {
       params
     });
@@ -3782,7 +4135,7 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async finalizeAfterProductsMutation(tempOrder, options) {
     this.syncTempOrderHolderFromBookings(tempOrder);
-    await this.applyPromotion();
+    const promotionPayload = await this.evaluatePromotion();
     this.applyDiscount({
       reapplyBookingDiscountProductUids: options?.reapplyBookingDiscountProductUids
     });
@@ -3791,6 +4144,7 @@ class OrderModule extends _BaseModule.BaseModule {
       createIfMissing: true
     });
     this.persistTempOrder();
+    this.emitPromotionApplied(promotionPayload);
   }
 
   /**
@@ -3801,10 +4155,12 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async removeProductsFromOrder(identities, options) {
     const tempOrder = this.ensureTempOrder();
-    this.repairDuplicateProductLineIdentities(tempOrder);
     if (!identities.length) {
       return tempOrder.products;
     }
+    // 商品删除会同步删除以商品行为主关系的 Notes；快照不完整时禁止产生孤儿 Relation。
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    this.repairDuplicateProductLineIdentities(tempOrder);
     const productsBeforeRemove = tempOrder.products || [];
     const bookingsBeforeRemove = tempOrder.bookings || [];
     const preserveDisplayPosition = options?.preserveDisplayPosition;
@@ -3864,6 +4220,7 @@ class OrderModule extends _BaseModule.BaseModule {
         tempOrder.products = nextProductIndex >= 0 ? [...productsWithoutRemaining.slice(0, nextProductIndex), remainingProduct, ...productsWithoutRemaining.slice(nextProductIndex)] : [...productsWithoutRemaining, remainingProduct];
       }
     }
+    this.removeSalesNotesForMissingProductLines(tempOrder);
     await this.finalizeAfterProductsMutation(tempOrder);
     this.logInfo('removeProductsFromOrder success', {
       identities
@@ -3876,13 +4233,15 @@ class OrderModule extends _BaseModule.BaseModule {
 
   /**
    * 仅清空购物车行（products / bookings），不重置整单。
-   * 用于「仅清空商品」；客户、备注、支付等协议字段保持不变。
+   * 普通整单 note 保持不变；以商品行为主体的 Sales Notes 同步删除。
    */
   async clearOrderCartLines() {
     const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
     tempOrder.products = [];
     tempOrder.bookings = [];
     (0, _virtualSettlement.releaseTempOrderSettlementState)(tempOrder);
+    this.removeSalesNotesForMissingProductLines(tempOrder);
     this.syncTempOrderHolderFromBookings(tempOrder);
     if (tempOrder._extend && typeof tempOrder._extend === 'object') {
       tempOrder._extend = {
@@ -3890,13 +4249,14 @@ class OrderModule extends _BaseModule.BaseModule {
         productsByUid: {}
       };
     }
-    await this.applyPromotion();
+    const promotionPayload = await this.evaluatePromotion();
     this.applyDiscount();
     this.sanitizeTempOrderProducts(tempOrder);
     await this.recalculateSummary({
       createIfMissing: true
     });
     this.persistTempOrder();
+    this.emitPromotionApplied(promotionPayload);
     this.logInfo('clearOrderCartLines success', {});
     return tempOrder;
   }
@@ -3906,8 +4266,10 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async clearOrderForSettlementSwitch() {
     const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
     tempOrder.products = [];
     tempOrder.bookings = [];
+    this.removeSalesNotesForMissingProductLines(tempOrder);
     tempOrder.discount_list = [];
     tempOrder.payments = [];
     tempOrder.refunds = [];
@@ -4050,6 +4412,7 @@ class OrderModule extends _BaseModule.BaseModule {
     })) || this.store.summary || (0, _utils.createEmptySummary)();
     const effectiveCacheId = params?.cacheId ?? this.cacheId;
     const hasPaymentStatusOverride = params?.paymentStatus !== undefined;
+    const shouldOverridePaymentStatus = hasPaymentStatusOverride && !isOnlineStorePlatform && !shouldConfirmPendingVoucherPayments;
     const hasSmallTicketDataFlagOverride = params?.smallTicketDataFlag !== undefined;
     const enhancePayload = hasPaymentOverride || hasPaymentStatusOverride || hasSmallTicketDataFlagOverride || params?.enhancePayload ? (payload, ctx) => {
       const nextPayload = {
@@ -4057,7 +4420,7 @@ class OrderModule extends _BaseModule.BaseModule {
         ...(hasPaymentOverride ? {
           payments: preparedPaymentOverride || []
         } : {}),
-        ...(hasPaymentStatusOverride && !isOnlineStorePlatform && !shouldConfirmPendingVoucherPayments ? {
+        ...(shouldOverridePaymentStatus ? {
           payment_status: params?.paymentStatus
         } : {}),
         ...(hasSmallTicketDataFlagOverride ? {
@@ -4124,6 +4487,12 @@ class OrderModule extends _BaseModule.BaseModule {
       this.logSubmitBackendRejected(result, payload);
       return result;
     }
+    const isLocalPendingSubmit = this.isLocalPendingSubmitResult(result);
+    // need_sync=1 仅表示已进入本地同步队列，不能视为远端已确认 Notes。
+    if (Object.prototype.hasOwnProperty.call(payload, 'notes') && !isLocalPendingSubmit) {
+      const salesNotesState = this.ensureSalesNotesRuntimeState(tempOrder);
+      salesNotesState.dirty = false;
+    }
     const submittedOrderId = this.extractOrderIdFromSubmitResult(result);
     this.logInfo('runSubmitTempOrder: 提交成功', {
       submittedOrderId,
@@ -4137,9 +4506,10 @@ class OrderModule extends _BaseModule.BaseModule {
       tempOrder.order_id = submittedOrderId;
       const resultRecord = result;
       await this.markLocalOrderSynced(submittedOrderId, resultRecord?.data || resultRecord || {});
-    } else if (this.isLocalPendingSubmitResult(result)) {
+    }
+    if (isLocalPendingSubmit) {
       this.store.syncState = 'local';
-    } else {
+    } else if (submittedOrderId === null || submittedOrderId === undefined) {
       this.store.syncState = 'submitted';
     }
     return result;
@@ -4535,7 +4905,7 @@ class OrderModule extends _BaseModule.BaseModule {
       params.forceRemote = false;
     }
     const res = await this.request.get(`/order/sales/${encodeURIComponent(lookup)}`, {
-      with: ['products', 'bookings', 'payments', 'customer', 'summary', 'contacts_info', 'order_meta_list', 'refunds'],
+      with: ['products', 'bookings', 'payments', 'customer', 'summary', 'contacts_info', 'order_meta_list', 'refunds', 'notes'],
       ...(params.forceRemote ? {
         forceRemote: true
       } : {})
@@ -4588,9 +4958,11 @@ class OrderModule extends _BaseModule.BaseModule {
     const isMergedSalesDetailHydrate = options?.source === 'mergedSalesDetail';
     const nextTempOrder = this.normalizeTempOrderForRuntime(raw, {
       // merge 前已只给远端商品补标记；这里不能把本地未提交商品一并变成 saved item。
-      makeEditMark: !isSessionStorageHydrate && !isMergedSalesDetailHydrate
+      makeEditMark: !isSessionStorageHydrate && !isMergedSalesDetailHydrate,
+      allowUnresolvedSalesNotes: isSessionStorageHydrate
     });
     this.store.tempOrder = nextTempOrder;
+    this.clearCustomerWalletRuntimeState();
     if (isSessionStorageHydrate) {
       // 会话快照是未提交购物车，不应获得编辑订单的 saved/edit 标记与服务端基线。
       const restoredSessionDiscounts = Array.isArray(raw.discount_list) ? (0, _lodashEs.cloneDeep)(raw.discount_list) : [];
@@ -4810,6 +5182,17 @@ class OrderModule extends _BaseModule.BaseModule {
     nextTempOrder.payments = Array.isArray(raw.payments) ? raw.payments.map(p => ({
       ...(p || {})
     })) : [];
+    const rawHasSalesNotes = Object.prototype.hasOwnProperty.call(raw, 'notes');
+    const restoredSalesNotesState = raw._extend?.salesNotesState;
+    const allowUnresolvedSalesNotes = options?.allowUnresolvedSalesNotes === true || restoredSalesNotesState?.dirty === true || Number(raw.is_draft_order || 0) === 1;
+    const decodedSalesNotes = rawHasSalesNotes ? (0, _salesNotes.decodeSalesNotesSnapshot)(raw.notes, {
+      allowUnresolvedOrderTarget: allowUnresolvedSalesNotes
+    }) : {
+      notes: [],
+      complete: false
+    };
+    const hasUnresolvedSalesNoteOrderTarget = decodedSalesNotes.notes.some(note => note.note_relations.some(relation => relation.is_primary === 0 && relation.relation_type === 'related_to' && relation.target_type === 'order' && relation.target_uuid === ''));
+    nextTempOrder.notes = decodedSalesNotes.notes;
     nextTempOrder.surcharges = Array.isArray(raw.surcharges) ? raw.surcharges.map(s => ({
       ...(s || {})
     })) : [];
@@ -4830,6 +5213,10 @@ class OrderModule extends _BaseModule.BaseModule {
       productsByUid: {}
     };
     const tempOrderExtend = nextTempOrder._extend;
+    tempOrderExtend.salesNotesState = {
+      loaded: rawHasSalesNotes ? decodedSalesNotes.complete : restoredSalesNotesState?.loaded === true,
+      dirty: decodedSalesNotes.complete && (restoredSalesNotesState?.dirty === true || allowUnresolvedSalesNotes && hasUnresolvedSalesNoteOrderTarget)
+    };
     const productsByUid = tempOrderExtend.productsByUid || {};
     for (const [index, product] of nextTempOrder.products.entries()) {
       const uid = product.metadata?.unique_identification_number;
@@ -5021,7 +5408,7 @@ class OrderModule extends _BaseModule.BaseModule {
   }
   async getOrderInfo(order_id) {
     const res = await this.request.get(`/order/sales/${order_id}`, {
-      with: ['products', 'bookings']
+      with: ['products', 'bookings', 'notes']
     }, {
       osServer: true
     });