@pisell/pisellos 0.10.57 → 0.10.59

package/lib/inventory/index.js

@@ -0,0 +1,280 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.salesGuardError = exports.InventoryController = void 0;
+/** Optional, instance-scoped sales inventory. Never stored in ProductData or order payloads. */
+
+const salesGuardError = message => Object.assign(new Error(message), {
+  code: 'SALES_GUARD_REJECTED'
+});
+exports.salesGuardError = salesGuardError;
+const cancelled = () => Object.assign(new Error('Inventory request cancelled'), {
+  name: 'AbortError'
+});
+const variantIdentity = (productId, variantId) => JSON.stringify([String(productId), String(variantId ?? 0)]);
+class InventoryController {
+  identity = Symbol('sales-inventory-instance');
+  scopeKey;
+  entries = new Map();
+  lastQuantities = new Map();
+  products = new Map();
+  keys = new Map();
+  catalogProducts = new Map();
+  listeners = new Set();
+  revision = 0;
+  state = 'stale';
+  pending;
+  disposed = false;
+  constructor(source) {
+    this.source = source;
+    this.scopeKey = source.scopeKey;
+  }
+  getRevision = () => this.revision;
+  subscribe = listener => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+  publish() {
+    this.revision += 1;
+    this.listeners.forEach(listener => {
+      try {
+        listener();
+      } catch {/* A view cannot interrupt a stock update. */}
+    });
+  }
+  assertCurrent(signal) {
+    if (this.disposed || signal?.aborted) throw cancelled();
+    this.source.assertCurrent();
+  }
+  activate() {
+    this.disposed = false;
+  }
+  dispose() {
+    this.disposed = true;
+    this.invalidate();
+  }
+  invalidate() {
+    this.pending?.controller.abort();
+    this.pending = undefined;
+    this.state = 'stale';
+    this.publish();
+  }
+
+  /** Catalog replaces identities; partial detail only merges its variants, never its prices. */
+  registerProducts(products, complete = false) {
+    this.assertCurrent();
+    let changed = false;
+    for (const product of products) {
+      const id = String(product.id ?? product.product_id);
+      if (complete && this.catalogProducts.get(id) === product) continue;
+      if (complete) this.catalogProducts.set(id, product);
+      const previous = this.products.get(id);
+      if (complete) for (const variantId of previous?.keys() || []) this.keys.delete(variantIdentity(id, variantId));
+      const variants = complete ? new Map() : new Map(previous);
+      const list = product.variant?.length ? product.variant : [{
+        id: 0,
+        code: product.code
+      }];
+      for (const variant of list) {
+        const variantId = String(variant.id ?? variant.product_variant_id ?? 0);
+        const key = this.source.keyOf(product, variant) ?? previous?.get(variantId);
+        variants.set(variantId, key);
+        this.keys.set(variantIdentity(id, variantId), key);
+      }
+      if (!previous || previous.size !== variants.size || [...variants].some(([id, key]) => previous.get(id) !== key)) changed = true;
+      this.products.set(id, variants);
+    }
+    if (changed) this.publish();
+  }
+
+  /** Consumers share I/O; cancelling one detail does not cancel another consumer. */
+  async refresh(context) {
+    this.assertCurrent(context.signal);
+    if (context.force) this.invalidate();
+    let read = this.pending;
+    if (!read) {
+      read = {
+        controller: new AbortController(),
+        consumers: 0,
+        promise: Promise.resolve()
+      };
+      const current = read;
+      this.pending = current;
+      this.state = 'loading';
+      this.publish();
+      current.promise = (async () => {
+        try {
+          const entries = await this.source.read({
+            reason: context.reason,
+            signal: current.controller.signal
+          });
+          this.assertCurrent(current.controller.signal);
+          if (this.pending !== current) throw cancelled();
+          this.entries = entries;
+          for (const [key, stock] of entries) if (stock.quantity !== null && Number.isSafeInteger(stock.quantity) && stock.quantity >= 0) this.lastQuantities.set(key, stock.quantity);
+          this.state = 'ready';
+        } catch (error) {
+          if (this.pending !== current || current.controller.signal.aborted) throw cancelled();
+          this.state = 'error';
+          throw error;
+        } finally {
+          if (this.pending === current) {
+            this.pending = undefined;
+            this.publish();
+          }
+        }
+      })();
+    }
+    read.consumers += 1;
+    try {
+      if (!context.signal) await read.promise;else await new Promise((resolve, reject) => {
+        const signal = context.signal;
+        const abort = () => reject(cancelled());
+        signal.addEventListener('abort', abort, {
+          once: true
+        });
+        read.promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+        if (signal.aborted) abort();
+      });
+      this.assertCurrent(context.signal);
+    } finally {
+      read.consumers -= 1;
+      if (this.pending === read && read.consumers === 0) this.invalidate();
+    }
+  }
+  availabilityForKey(key) {
+    const stock = key ? this.entries.get(key) : undefined;
+    const quantity = key ? this.lastQuantities.get(key) : undefined;
+    if (this.state !== 'ready') return {
+      status: this.state,
+      quantity,
+      message: this.source.message('unavailable')
+    };
+    if (!stock) return {
+      status: 'unmapped',
+      quantity,
+      message: this.source.message('unmapped')
+    };
+    if (stock.quantity === null || !Number.isSafeInteger(stock.quantity) || stock.quantity < 0) return {
+      status: 'error',
+      quantity,
+      message: stock.message || this.source.message('unavailable')
+    };
+    return {
+      status: 'ready',
+      quantity: stock.quantity
+    };
+  }
+  availability(product, variantId) {
+    const id = product.id ?? product.product_id;
+    if (variantId !== undefined && variantId !== null) return this.availabilityForKey(this.keys.get(variantIdentity(id, variantId)));
+    const keys = [...new Set(this.products.get(String(id))?.values() || [])];
+    const states = keys.map(key => this.availabilityForKey(key));
+    if (!states.length) return this.availabilityForKey();
+    const quantity = states.every(entry => entry.quantity !== undefined) ? states.reduce((sum, entry) => sum + entry.quantity, 0) : undefined;
+    const failed = states.find(entry => entry.status !== 'ready');
+    if (quantity !== undefined && !Number.isSafeInteger(quantity)) return {
+      status: 'error',
+      message: this.source.message('unavailable')
+    };
+    return {
+      status: failed?.status || 'ready',
+      quantity,
+      message: failed?.message
+    };
+  }
+  keyForLine(item) {
+    return this.keys.get(variantIdentity(item.product_id, item.product_variant_id ?? item.product_sku?.product_variant_id));
+  }
+  /** Advisory UI limit only. The serialized cart guard remains authoritative. */
+  selectionAvailability(product, variantId, items, editingItem) {
+    const identity = variantIdentity(product.id ?? product.product_id, variantId);
+    const key = this.keys.get(identity);
+    let availability = this.availabilityForKey(key);
+    let reserved = 0;
+    let retainedQuantity = 0;
+    for (const item of items) {
+      const matches = key ? this.keyForLine(item) === key : variantIdentity(item.product_id, item.product_variant_id ?? item.product_sku?.product_variant_id) === identity;
+      if (!matches) continue;
+      const count = Number(item.num ?? item.quantity);
+      if (!Number.isSafeInteger(count) || count < 0) {
+        availability = {
+          ...availability,
+          status: 'error',
+          message: this.source.message('unavailable')
+        };
+        continue;
+      }
+      if (item === editingItem) retainedQuantity = count;else reserved += count;
+    }
+    if (!Number.isSafeInteger(reserved)) {
+      availability = {
+        ...availability,
+        status: 'error',
+        message: this.source.message('unavailable')
+      };
+    }
+    const availableQuantity = availability.status === 'ready' ? Math.max(0, availability.quantity - reserved) : 0;
+    return {
+      availability,
+      availableQuantity,
+      retainedQuantity,
+      maxQuantity: Math.max(availableQuantity, retainedQuantity)
+    };
+  }
+  totals(items) {
+    const totals = new Map();
+    for (const item of items) {
+      const key = this.keyForLine(item);
+      const identity = key ? JSON.stringify(['inventory', key]) : variantIdentity(item.product_id, item.product_variant_id);
+      const quantity = Number(item.num ?? item.quantity);
+      if (!Number.isSafeInteger(quantity) || quantity < 0) throw salesGuardError(this.source.message('unavailable'));
+      if (!quantity) continue;
+      const total = (totals.get(identity)?.quantity || 0) + quantity;
+      if (!Number.isSafeInteger(total)) throw salesGuardError(this.source.message('unavailable'));
+      totals.set(identity, {
+        key,
+        quantity: total
+      });
+    }
+    return totals;
+  }
+  validate(proposed, current = [], allowReductions = true) {
+    this.assertCurrent();
+    const previous = this.totals(current);
+    for (const [identity, {
+      key,
+      quantity
+    }] of this.totals(proposed)) {
+      if (allowReductions && quantity <= (previous.get(identity)?.quantity || 0)) continue;
+      const stock = this.availabilityForKey(key);
+      if (stock.status !== 'ready') throw salesGuardError(stock.message || this.source.message('unavailable'));
+      if (quantity > stock.quantity) throw salesGuardError(this.source.message('insufficient', {
+        key: key,
+        quantity: stock.quantity
+      }));
+    }
+  }
+  freezeCheckout(items) {
+    if (!items.length || items.some(item => Number(item.num ?? item.quantity) <= 0)) {
+      throw salesGuardError(this.source.message('unavailable'));
+    }
+    this.validate(items, [], false);
+    return Object.freeze({
+      scopeKey: this.scopeKey,
+      revision: this.revision,
+      lines: Object.freeze(items.map((item, index) => Object.freeze({
+        lineId: String(item.metadata?.unique_identification_number ?? item.unique_identification_number ?? item.order_detail_id ?? index),
+        productId: item.product_id,
+        variantId: item.product_variant_id ?? item.product_sku?.product_variant_id ?? 0,
+        quantity: Number(item.num ?? item.quantity),
+        inventoryKey: this.keyForLine(item)
+      })))
+    });
+  }
+}
+exports.InventoryController = InventoryController;

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

@@ -4,7 +4,7 @@ import { OrderModuleAPI, CommitOrderParams, UpdateOrderBookingParams, UpdateOrde
 import { CartItem } from '../Cart/types';
 import { type SubmitPayloadEnhancer } from './utils';
 import { type PickupTimingBooking, type PickupTimingBookingInput } from './pickupTiming';
-import type { OrderAmountSnapshot, AddProductBookingInput, AddProductToOrderOptions, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, OrderCartIntentCommitContext, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions, RemoveProductsFromOrderOptions, SalesNote, SalesNotesMutationSnapshot, SetSalesNoteInput, PickupReferenceMode, PointCardSnapshotMergeContext, PointCardSnapshotItem, ShopServiceData, ShopServiceType } from './types';
+import type { OrderAmountSnapshot, AddProductBookingInput, AddProductToOrderOptions, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, OrderHooksConfig, OrderCartIntentCommitContext, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions, RemoveProductsFromOrderOptions, SalesNote, SalesNotesMutationSnapshot, SetSalesNoteInput, PickupReferenceMode, PointCardSnapshotMergeContext, PointCardSnapshotItem, ShopServiceData, ShopServiceType } from './types';
 import type { ICustomer } from '../AccountList/types';
 import type { Discount } from '../Discount/types';
 import { UnavailableReason } from '../Rules/types';
@@ -29,6 +29,12 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private rulesHooksOverride?;
     private moduleHooksOverride?;
     private orderHooks?;
+    private cartCommandQueue;
+    private queueCartCommand;
+    /** Use the exact Order normalizers/merge rules on a private draft, not a second projection. */
+    private beginCartMutation;
+    /** Serializes checkout preparation with local cart commands; hydration remains outside this guard. */
+    prepareCheckout<T>(prepare: (items: OrderProduct[]) => Promise<T>): Promise<T>;
     private otherParams?;
     /** 评估器引用；由 SalesSdkProvider 注入，未注入时 applyPromotion 静默跳过 */
     private promotionEvaluator;
@@ -66,7 +72,11 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * @example
      * orderModule.updateOtherParams({ cacheId: 'cache-2', channel: 'pos' });
      */
-    updateOtherParams(params: Record<string, any>): void;
+    updateOtherParams(params: Record<string, any>, options?: {
+        hooks?: OrderHooksConfig;
+        changedParams?: Record<string, any>;
+        cover?: boolean;
+    }): void;
     /** Internal intent boundary shared with asynchronous scanner/detail flows. */
     createCartIntentCommitGuard(action: OrderCartIntentCommitContext['action'], tempOrder?: OrderTempOrder | null): () => void;
     /** PC/H5 属于在线店铺；其它或缺失平台统一沿用 POS 行为。 */
@@ -481,6 +491,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * // → tempOrder.products 新增 3 行，每行 num=1，bookings 3 条
      */
     addProductToOrder(product: Partial<OrderProduct> & OrderProductIdentity, booking?: AddProductBookingInput, options?: AddProductToOrderOptions): Promise<OrderProduct[]>;
+    private addProductToOrderDraft;
     /**
      * 批量添加商品行，所有行追加完成后只触发一次促销、折扣、summary 重算与持久化。
      *
@@ -496,6 +507,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     }>, options?: {
         skipEditDiscountConfigRefresh?: boolean;
     }): Promise<OrderProduct[]>;
+    private addProductsToOrderDraft;
     private getFullCoveragePassDiscounts;
     private hasEntitlementPassDiscount;
     private hasGoodPassDiscount;
@@ -507,8 +519,11 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private isRestrictedCartProductUpdate;
     private applyOrderProductUpdateToTempOrder;
     updateOrderProduct(params: UpdateOrderProductParams): Promise<OrderProduct[]>;
+    private updateOrderProductDraft;
     updateOrderProducts(paramsList: UpdateOrderProductParams[]): Promise<OrderProduct[]>;
+    private updateOrderProductsDraft;
     updateOrderProductQuantity(params: UpdateOrderProductQuantityParams): Promise<OrderProduct[]>;
+    private updateOrderProductQuantityDraft;
     updateOrderBooking(params: UpdateOrderBookingParams): any[];
     /**
      * 商品行写路径收尾：促销 → 折扣 → 清洗 → summary → 持久化。
@@ -525,12 +540,14 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * await order.removeProductsFromOrder([identityA, identityB]);
      */
     removeProductsFromOrder(identities: OrderProductIdentity[], options?: RemoveProductsFromOrderOptions): Promise<OrderProduct[]>;
+    private removeProductsFromOrderDraft;
     removeProductFromOrder(identity: OrderProductIdentity, options?: RemoveProductsFromOrderOptions): Promise<OrderProduct[]>;
     /**
      * 仅清空购物车行（products / bookings），不重置整单。
      * 普通整单 note 保持不变；以商品行为主体的 Sales Notes 同步删除。
      */
     clearOrderCartLines(): Promise<OrderTempOrder>;
+    private clearOrderCartLinesDraft;
     /**
      * 切换购物车结算单位时清理所有会影响新币种的订单状态，但保留当前客户。
      */
@@ -592,7 +609,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     generateIdempotencyToken(): string;
     syncPaymentsToOrder<T = any>(params: SyncPaymentsToOrderParams): Promise<SyncPaymentsToOrderResult<T>>;
     createOrder(params: CommitOrderParams['query']): {
-        type: "virtual" | "appointment_booking";
+        type: "appointment_booking" | "virtual";
         platform: string;
         sales_channel: string;
         order_sales_channel: string;

package/lib/modules/Order/index.js

@@ -145,6 +145,63 @@ class OrderModule extends _BaseModule.BaseModule {
   rulesHooksOverride;
   moduleHooksOverride;
   orderHooks;
+  cartCommandQueue = Promise.resolve();
+  queueCartCommand(run) {
+    if (!this.orderHooks?.onBeforeCartCommit) return run();
+    const pending = this.cartCommandQueue.then(run, run);
+    this.cartCommandQueue = pending.catch(() => undefined);
+    return pending;
+  }
+
+  /** Use the exact Order normalizers/merge rules on a private draft, not a second projection. */
+  beginCartMutation() {
+    const current = this.ensureTempOrder();
+    const guard = this.orderHooks?.onBeforeCartCommit;
+    if (!guard) return {
+      current,
+      draft: current,
+      commit: undefined
+    };
+    const before = (0, _lodashEs.cloneDeep)(current);
+    const draft = (0, _lodashEs.cloneDeep)(current);
+    return {
+      current,
+      draft,
+      commit: async beforeCommit => {
+        await guard({
+          currentItems: (0, _lodashEs.cloneDeep)(before.products),
+          proposedItems: (0, _lodashEs.cloneDeep)(draft.products)
+        });
+        if (this.store.tempOrder !== current || guard !== this.orderHooks?.onBeforeCartCommit || !(0, _lodashEs.isEqual)(current, before)) {
+          throw Object.assign(new Error('The cart changed. Please try again.'), {
+            code: 'SALES_GUARD_REJECTED'
+          });
+        }
+        // Recheck the accepted intent's scope after asynchronous inventory validation.
+        beforeCommit?.();
+        Object.assign(current, draft);
+        return current;
+      }
+    };
+  }
+
+  /** Serializes checkout preparation with local cart commands; hydration remains outside this guard. */
+  async prepareCheckout(prepare) {
+    const run = async () => {
+      const order = this.ensureTempOrder();
+      const items = (0, _lodashEs.cloneDeep)(order.products);
+      const result = await prepare(items);
+      if (this.store.tempOrder !== order || !(0, _lodashEs.isEqual)(order.products, items)) {
+        throw Object.assign(new Error('The cart changed. Please try again.'), {
+          code: 'SALES_GUARD_REJECTED'
+        });
+      }
+      return result;
+    };
+    const pending = this.cartCommandQueue.then(run, run);
+    this.cartCommandQueue = pending.catch(() => undefined);
+    return pending;
+  }
   otherParams;
   // ─── 促销/赠品 ────────────────────────────────────
   /** 评估器引用；由 SalesSdkProvider 注入，未注入时 applyPromotion 静默跳过 */
@@ -432,8 +489,11 @@ class OrderModule extends _BaseModule.BaseModule {
    * @example
    * orderModule.updateOtherParams({ cacheId: 'cache-2', channel: 'pos' });
    */
-  updateOtherParams(params) {
+  updateOtherParams(params, options) {
     const otherParams = params || {};
+    if (options && Object.prototype.hasOwnProperty.call(options, 'hooks')) {
+      this.moduleHooksOverride = options.hooks;
+    }
     this.syncSessionStorageOptions(otherParams);
     this.salesSummaryModuleName = otherParams.salesSummaryModuleName;
     this.rulesHooksOverride = otherParams.rules?.hooks;
@@ -3704,8 +3764,12 @@ class OrderModule extends _BaseModule.BaseModule {
    * // → tempOrder.products 新增 3 行，每行 num=1，bookings 3 条
    */
   async addProductToOrder(product, booking, options) {
-    const tempOrder = this.ensureTempOrder();
-    const beforeCommit = this.createCartIntentCommitGuard('add_product', tempOrder);
+    return this.queueCartCommand(() => this.addProductToOrderDraft(product, booking, options));
+  }
+  async addProductToOrderDraft(product, booking, options) {
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
+    const beforeCommit = this.createCartIntentCommitGuard('add_product', mutation.current);
     const salesNoteDrafts = (options?.salesNotes || []).map(draft => ({
       note_type: String(draft.note_type || '').trim(),
       text: {
@@ -3802,6 +3866,7 @@ class OrderModule extends _BaseModule.BaseModule {
       rollbackProductAndNotesMutation();
       throw error;
     }
+    if (mutation.commit) tempOrder = await mutation.commit(beforeCommit);
     await this.finalizeProductOrderMutation(tempOrder);
     this.logInfo('addProductToOrder success', {
       product_id: product.product_id,
@@ -3820,9 +3885,13 @@ class OrderModule extends _BaseModule.BaseModule {
    * ]);
    */
   async addProductsToOrder(items, options) {
-    const tempOrder = this.ensureTempOrder();
+    return this.queueCartCommand(() => this.addProductsToOrderDraft(items, options));
+  }
+  async addProductsToOrderDraft(items, options) {
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
     if (!Array.isArray(items) || items.length === 0) return tempOrder.products;
-    const beforeCommit = this.createCartIntentCommitGuard('add_product', tempOrder);
+    const beforeCommit = this.createCartIntentCommitGuard('add_product', mutation.current);
     for (const item of items || []) {
       const {
         product,
@@ -3848,6 +3917,7 @@ class OrderModule extends _BaseModule.BaseModule {
       });
       if (appendResult) await appendResult;
     }
+    if (mutation.commit) tempOrder = await mutation.commit(beforeCommit);
     await this.finalizeProductOrderMutation(tempOrder, options);
     this.logInfo('addProductsToOrder success', {
       itemsCount: items.length
@@ -4190,12 +4260,16 @@ class OrderModule extends _BaseModule.BaseModule {
     return tempOrder.products[productIndex].metadata?.unique_identification_number;
   }
   async updateOrderProduct(params) {
-    const tempOrder = this.ensureTempOrder();
-    if (this.isRestrictedCartProductUpdate(tempOrder, params)) {
-      this.createCartIntentCommitGuard('update_product', tempOrder)();
-    }
+    return this.queueCartCommand(() => this.updateOrderProductDraft(params));
+  }
+  async updateOrderProductDraft(params) {
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
+    const beforeCommit = this.isRestrictedCartProductUpdate(tempOrder, params) ? this.createCartIntentCommitGuard('update_product', mutation.current) : undefined;
+    beforeCommit?.();
     const reapplyWeighedDiscountProductUids = [];
     const updatedProductUid = this.applyOrderProductUpdateToTempOrder(tempOrder, params, reapplyWeighedDiscountProductUids);
+    if (mutation.commit) tempOrder = await mutation.commit(beforeCommit);
     const promotionPayload = await this.evaluatePromotion();
     this.applyDiscount({
       reapplyWeighedDiscountProductUids,
@@ -4213,13 +4287,16 @@ class OrderModule extends _BaseModule.BaseModule {
     return tempOrder.products;
   }
   async updateOrderProducts(paramsList) {
-    const tempOrder = this.ensureTempOrder();
+    return this.queueCartCommand(() => this.updateOrderProductsDraft(paramsList));
+  }
+  async updateOrderProductsDraft(paramsList) {
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
     if (!paramsList.length) {
       return tempOrder.products;
     }
-    if (paramsList.some(params => this.isRestrictedCartProductUpdate(tempOrder, params))) {
-      this.createCartIntentCommitGuard('update_product', tempOrder)();
-    }
+    const beforeCommit = paramsList.some(params => this.isRestrictedCartProductUpdate(tempOrder, params)) ? this.createCartIntentCommitGuard('update_product', mutation.current) : undefined;
+    beforeCommit?.();
     const reapplyWeighedDiscountProductUids = [];
     const reapplyBookingDiscountProductUids = paramsList.reduce((acc, params) => {
       const updatedProductUid = this.applyOrderProductUpdateToTempOrder(tempOrder, params, reapplyWeighedDiscountProductUids);
@@ -4229,6 +4306,7 @@ class OrderModule extends _BaseModule.BaseModule {
       }
       return acc;
     }, []);
+    if (mutation.commit) tempOrder = await mutation.commit(beforeCommit);
     await this.finalizeAfterProductsMutation(tempOrder, {
       reapplyWeighedDiscountProductUids,
       reapplyBookingDiscountProductUids: reapplyBookingDiscountProductUids.length ? reapplyBookingDiscountProductUids : undefined
@@ -4239,6 +4317,9 @@ class OrderModule extends _BaseModule.BaseModule {
     return tempOrder.products;
   }
   async updateOrderProductQuantity(params) {
+    return this.queueCartCommand(() => this.updateOrderProductQuantityDraft(params));
+  }
+  async updateOrderProductQuantityDraft(params) {
     const {
       product_id,
       product_variant_id,
@@ -4248,7 +4329,8 @@ class OrderModule extends _BaseModule.BaseModule {
       product_sku,
       product_bundle
     } = params;
-    const tempOrder = this.ensureTempOrder();
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
     this.repairDuplicateProductLineIdentities(tempOrder);
     const identityLookup = {
       product_id,
@@ -4304,10 +4386,10 @@ class OrderModule extends _BaseModule.BaseModule {
         throw new _virtualSettlement.VirtualCurrencyBalanceError(balance.toFixed(2), requiredAmount.toFixed(2));
       }
     }
-    if (normalizedProduct.num > targetProduct.num) {
-      this.createCartIntentCommitGuard('increase_quantity', tempOrder)();
-    }
+    const beforeCommit = normalizedProduct.num > targetProduct.num ? this.createCartIntentCommitGuard('increase_quantity', mutation.current) : undefined;
+    beforeCommit?.();
     tempOrder.products[productIndex] = normalizedProduct;
+    if (mutation.commit) tempOrder = await mutation.commit(beforeCommit);
     this.prepareVirtualSettlementTempOrder(tempOrder);
     const isVirtualSettlement = this.isActiveVirtualSettlementOrder(tempOrder);
     const promotionPayload = !isVirtualSettlement ? await this.evaluatePromotion() : null;
@@ -4384,7 +4466,11 @@ class OrderModule extends _BaseModule.BaseModule {
    * await order.removeProductsFromOrder([identityA, identityB]);
    */
   async removeProductsFromOrder(identities, options) {
-    const tempOrder = this.ensureTempOrder();
+    return this.queueCartCommand(() => this.removeProductsFromOrderDraft(identities, options));
+  }
+  async removeProductsFromOrderDraft(identities, options) {
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
     if (!identities.length) {
       return tempOrder.products;
     }
@@ -4451,6 +4537,7 @@ class OrderModule extends _BaseModule.BaseModule {
       }
     }
     this.removeSalesNotesForMissingProductLines(tempOrder);
+    if (mutation.commit) tempOrder = await mutation.commit();
     await this.finalizeAfterProductsMutation(tempOrder);
     this.logInfo('removeProductsFromOrder success', {
       identities
@@ -4466,7 +4553,11 @@ class OrderModule extends _BaseModule.BaseModule {
    * 普通整单 note 保持不变；以商品行为主体的 Sales Notes 同步删除。
    */
   async clearOrderCartLines() {
-    const tempOrder = this.ensureTempOrder();
+    return this.queueCartCommand(() => this.clearOrderCartLinesDraft());
+  }
+  async clearOrderCartLinesDraft() {
+    const mutation = this.beginCartMutation();
+    let tempOrder = mutation.draft;
     this.ensureSalesNotesLoadedForMutation(tempOrder);
     tempOrder.products = [];
     tempOrder.bookings = [];
@@ -4479,6 +4570,7 @@ class OrderModule extends _BaseModule.BaseModule {
         productsByUid: {}
       };
     }
+    if (mutation.commit) tempOrder = await mutation.commit();
     const promotionPayload = await this.evaluatePromotion();
     this.applyDiscount();
     this.sanitizeTempOrderProducts(tempOrder);

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

@@ -526,6 +526,11 @@ export interface OrderHooksConfig {
     beforeCartIntentCommit?: (context: OrderCartIntentCommitContext) => void;
     /** Captures tenant/business runtime identity for asynchronous cart intents. */
     getCartIntentScope?: () => unknown;
+    /** Awaited before a local cart draft is published. Reject to leave the live order unchanged. */
+    onBeforeCartCommit?: (context: {
+        currentItems: readonly OrderProduct[];
+        proposedItems: readonly OrderProduct[];
+    }) => void | Promise<void>;
     onBeforeMergeProductToOrder?: (context: OrderProductMergeDecisionContext) => OrderProductMergeDecisionResult | Promise<OrderProductMergeDecisionResult>;
 }
 /**

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

@@ -121,8 +121,9 @@ export declare function getBundleSellingMagnitude(bundle: Record<string, any> |
  *   = `metadata.main_product_original_price` + Σ(bundle 原价 × num)。
  * - `metadata.source_product_price`：主商品/variant 基础价（已应用报价单），不含 option、
  *   不含折扣。**权威源**。
- * - `metadata.main_product_original_price` = source + Σ(option.price × option.num)（含 option、不含折扣）。
- * - `metadata.main_product_selling_price` = main_original − 主商品券 per-unit amount（含 option、含折扣）。
+ * - `product_sku.option[].add_price` 保留单规格折前单价；Rules 的 option.price 只用于本次计算。
+ * - `metadata.main_product_original_price` = source + Σ(option.add_price × option.num)（含 option、不含折扣）。
+ * - `metadata.main_product_selling_price` = main_original − 行内 per-unit amount（含主商品及 option 优惠）。
  * - `payment_price`：出站 payload 中为行 composite 已减整单折扣均摊价（无折扣时与 `selling_price` 同义）。
  *
  * Rules 钩子契约（hook_adapt 方案，Rules 内部保持不变）：
@@ -131,8 +132,9 @@ export declare function getBundleSellingMagnitude(bundle: Record<string, any> |
  *   `getProductOriginTotalPrice` 会自行叠加 option + bundle，喂 source 可避免 option 双加。
  * - `getProduct.total` = `selling_price × num`（行 composite × num），与 Rules 内部产出的
  *   total（source + option + bundle）对齐。
+ * - `getProduct.options` 用单规格原价参与重算；主商品折后价从 main_selling 减去 option 折后合计反推。
  * - `setProduct` 反向流程：把 Rules 返回的 source-level `main_product_selling_price` / `price`
- *   加回 Σoptions，重新合成含 option 的 main_product_* 并派生 composite。
+ *   加回单规格原价合计，再减去 optionDiscountAmount；保留订单单规格原价供取消折扣及后续重算。
  *   优先级：
  *     1. `values.main_product_selling_price`（券应用分支，per-unit 券后 source-level 主价）
  *     2. `values.price`（还原分支 `restoredPrice`、good_pass 归零）