@pisell/pisellos 0.10.54 → 0.10.55

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

@@ -216,6 +216,8 @@ export interface UnifiedBookingSalesDiscountResult {
     summaryAfter?: unknown;
 }
 export interface UnifiedBookingSalesApi {
+    /** Uses cached business settings and evaluates the current store-local clock. */
+    getBusinessAvailability: () => Promise<import('../../modules/BusinessAvailability').BusinessAvailability>;
     loadOpenData: (params: UnifiedBookingSalesLoadOpenDataParams) => Promise<OpenDataConfig>;
     /** Returns the latest OpenData payload cached by this solution instance. */
     getOpenData: () => Promise<OpenDataConfig | null>;

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

@@ -1,46 +1 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "BUY_X_GET_Y_FREE_STRATEGY", {
-  enumerable: true,
-  get: function () {
-    return _examples.BUY_X_GET_Y_FREE_STRATEGY;
-  }
-});
-Object.defineProperty(exports, "ITEM_REWARD_STRATEGY", {
-  enumerable: true,
-  get: function () {
-    return _examples.ITEM_REWARD_STRATEGY;
-  }
-});
-Object.defineProperty(exports, "PromotionAdapter", {
-  enumerable: true,
-  get: function () {
-    return _adapter.PromotionAdapter;
-  }
-});
-Object.defineProperty(exports, "PromotionEvaluator", {
-  enumerable: true,
-  get: function () {
-    return _evaluator.PromotionEvaluator;
-  }
-});
-Object.defineProperty(exports, "X_ITEMS_FOR_Y_PRICE_STRATEGY", {
-  enumerable: true,
-  get: function () {
-    return _examples.X_ITEMS_FOR_Y_PRICE_STRATEGY;
-  }
-});
-Object.defineProperty(exports, "default", {
-  enumerable: true,
-  get: function () {
-    return _adapter.default;
-  }
-});
-var _evaluator = require("./evaluator");
-var _adapter = _interopRequireWildcard(require("./adapter"));
-var _examples = require("./examples");
-function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
-function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+"use strict";

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

@@ -0,0 +1,30 @@
+import type { MultiLangObject } from '../OpenData/types';
+import type { ScheduleItem } from '../Schedule/types';
+export type BusinessClosedBehavior = 'show_menu_disabled' | 'hide_all';
+export interface BusinessAvailability {
+    status: 'open' | 'paused' | 'closed' | 'error';
+    behavior: BusinessClosedBehavior | null;
+    message: string | MultiLangObject | null;
+    /** Epoch milliseconds. Re-evaluate the cached configuration at this time. */
+    nextChangeAt: number;
+    requirePaymentOnSubmit: boolean;
+    error?: string;
+}
+export interface BusinessAvailabilityConfig {
+    paused: boolean;
+    pauseBehavior: BusinessClosedBehavior;
+    closedBehavior: BusinessClosedBehavior;
+    pauseMessage: BusinessAvailability['message'];
+    closedMessage: BusinessAvailability['message'];
+    scheduleIds: number[];
+    invalidScheduleIds: boolean;
+    requirePaymentOnSubmit: boolean;
+}
+export declare function normalizeBusinessAvailabilityConfig(data: Record<string, unknown>): BusinessAvailabilityConfig;
+/** Business ordering is independent of reservation switches and Pickup slot availability. */
+export declare function computeBusinessAvailability(input: {
+    config: BusinessAvailabilityConfig;
+    schedules: ScheduleItem[];
+    timezone: string;
+    now: Date;
+}): BusinessAvailability;

package/lib/modules/BusinessAvailability/index.js

@@ -0,0 +1,146 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.computeBusinessAvailability = computeBusinessAvailability;
+exports.normalizeBusinessAvailabilityConfig = normalizeBusinessAvailabilityConfig;
+var _dayjs = _interopRequireDefault(require("dayjs"));
+var _isSameOrAfter = _interopRequireDefault(require("dayjs/plugin/isSameOrAfter"));
+var _isSameOrBefore = _interopRequireDefault(require("dayjs/plugin/isSameOrBefore"));
+var _getDateIsInSchedule = require("../Schedule/getDateIsInSchedule");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+_dayjs.default.extend(_isSameOrAfter.default);
+_dayjs.default.extend(_isSameOrBefore.default);
+const DAY = 86_400_000;
+const behavior = value => value === 'show_menu_disabled' ? value : 'hide_all';
+const message = value => typeof value === 'string' || value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
+function normalizeBusinessAvailabilityConfig(data) {
+  const rawIds = data['availability.operating_hours'];
+  const ids = Array.isArray(rawIds) ? rawIds.map(id => typeof id === 'number' || typeof id === 'string' ? Number(id) : NaN) : [];
+  const validIds = ids.filter(id => Number.isInteger(id) && id > 0);
+  const paused = data['availability.paused'];
+  return {
+    paused: paused === true || paused === 1 || paused === 'true' || paused === '1',
+    pauseBehavior: behavior(data['availability.pause_behavior']),
+    closedBehavior: behavior(data['availability.closed_behavior']),
+    pauseMessage: message(data['availability.pause_message']),
+    closedMessage: message(data['availability.closed_message']),
+    scheduleIds: [...new Set(validIds)],
+    invalidScheduleIds: rawIds != null && (!Array.isArray(rawIds) || validIds.length !== ids.length),
+    // Only an explicitly disabled setting changes the existing payment flow.
+    requirePaymentOnSubmit: data['sale.require_payment_on_submit'] !== false
+  };
+}
+function createClock(timezone) {
+  if (!timezone) throw new Error('Store timezone is unavailable.');
+  const formatter = new Intl.DateTimeFormat('en-GB', {
+    timeZone: timezone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hourCycle: 'h23'
+  });
+  const local = timestamp => {
+    const parts = {};
+    formatter.formatToParts(timestamp).forEach(part => {
+      parts[part.type] = part.value;
+    });
+    const date = `${parts.year}-${parts.month}-${parts.day}`;
+    return {
+      date,
+      scalar: Date.parse(`${date}T${parts.hour}:${parts.minute}:${parts.second}Z`)
+    };
+  };
+  const offsets = new Set();
+  const instants = scalar => {
+    offsets.clear();
+    for (let hours = -36; hours <= 36; hours += 6) {
+      const sample = scalar + hours * 3_600_000;
+      offsets.add(local(sample).scalar - sample);
+    }
+    return [...offsets].map(offset => scalar - offset).filter(instant => local(instant).scalar === scalar).sort((a, b) => a - b);
+  };
+  return {
+    local,
+    instants
+  };
+}
+
+/** Business ordering is independent of reservation switches and Pickup slot availability. */
+function computeBusinessAvailability(input) {
+  const {
+    config,
+    schedules,
+    timezone,
+    now
+  } = input;
+  const nowAt = now.getTime();
+  const base = {
+    requirePaymentOnSubmit: config.requirePaymentOnSubmit,
+    nextChangeAt: nowAt + DAY
+  };
+  if (config.paused) {
+    return {
+      ...base,
+      status: 'paused',
+      behavior: config.pauseBehavior,
+      message: config.pauseMessage
+    };
+  }
+  if (config.invalidScheduleIds) throw new Error('Business operating-hours configuration is invalid.');
+  if (!config.scheduleIds.length) return {
+    ...base,
+    status: 'open',
+    behavior: null,
+    message: null
+  };
+  const selected = schedules.filter(schedule => config.scheduleIds.includes(Number(schedule.id)));
+  if (config.scheduleIds.some(id => !selected.some(schedule => Number(schedule.id) === id))) {
+    throw new Error('A configured business operating-hours schedule is unavailable.');
+  }
+  const clock = createClock(timezone);
+  const current = clock.local(nowAt);
+  const today = Date.parse(`${current.date}T00:00:00Z`);
+  const nextMidnight = clock.instants(today + DAY).find(instant => instant > nowAt);
+  let nextChangeAt = nextMidnight ?? nowAt + 60_000;
+  let open = false;
+  // Yesterday contributes the tail of overnight windows; today supplies the next boundary.
+  for (const dateAt of [today - DAY, today]) {
+    const date = new Date(dateAt).toISOString().slice(0, 10);
+    // Schedule's resolver merges by time-of-day, so resolve each schedule independently.
+    for (const schedule of selected) {
+      for (const window of (0, _getDateIsInSchedule.getScheduleStartEndTimePoints)(date, [schedule])) {
+        const toMinutes = value => {
+          if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(value) && value !== '24:00') {
+            throw new Error('Business operating-hours schedule contains an invalid time.');
+          }
+          const [hours, minutes] = value.split(':').map(Number);
+          return hours * 60 + minutes;
+        };
+        const start = dateAt + toMinutes(window.start_time) * 60_000;
+        let end = dateAt + toMinutes(window.end_time) * 60_000;
+        if (end <= start) end += DAY;
+        if (current.scalar >= start && current.scalar < end) open = true;
+        for (const boundary of [start, end]) {
+          for (const instant of clock.instants(boundary)) {
+            if (instant > nowAt) nextChangeAt = Math.min(nextChangeAt, instant);
+          }
+        }
+      }
+    }
+  }
+  // A timezone offset change can repeat/skip a wall-clock boundary. A local-only safety
+  // check also covers throttled timers; it does not fetch either configuration source.
+  nextChangeAt = Math.min(nextChangeAt, nowAt + 60_000);
+  return {
+    ...base,
+    nextChangeAt,
+    status: open ? 'open' : 'closed',
+    behavior: open ? null : config.closedBehavior,
+    message: open ? null : config.closedMessage
+  };
+}

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

@@ -69,6 +69,8 @@ export interface OpenDataConfig {
     'reservation.time_slice'?: number | string;
     'sale.allow_item_notes'?: boolean;
     'sale.allow_order_notes'?: boolean;
+    /** False submits an order without starting or confirming payment. */
+    'sale.require_payment_on_submit'?: boolean | null;
     'sale.enable_item_rules'?: boolean;
     'sale.enable_short_number'?: boolean;
     'sale.short_number_daily_reset'?: boolean;

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, 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, 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';
@@ -67,6 +67,8 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * orderModule.updateOtherParams({ cacheId: 'cache-2', channel: 'pos' });
      */
     updateOtherParams(params: Record<string, any>): void;
+    /** Internal intent boundary shared with asynchronous scanner/detail flows. */
+    createCartIntentCommitGuard(action: OrderCartIntentCommitContext['action'], tempOrder?: OrderTempOrder | null): () => void;
     /** PC/H5 属于在线店铺；其它或缺失平台统一沿用 POS 行为。 */
     isOnlineStorePlatform(): boolean;
     /**
@@ -501,6 +503,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private hasSameEntitlementMergePriceConfig;
     private getBundleRuntimeIdentity;
     private preservePersistedBundlePriceFields;
+    private isRestrictedCartProductUpdate;
     private applyOrderProductUpdateToTempOrder;
     updateOrderProduct(params: UpdateOrderProductParams): Promise<OrderProduct[]>;
     updateOrderProducts(paramsList: UpdateOrderProductParams[]): Promise<OrderProduct[]>;
@@ -588,7 +591,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: "appointment_booking" | "virtual";
+        type: "virtual" | "appointment_booking";
         platform: string;
         sales_channel: string;
         order_sales_channel: string;

package/lib/modules/Order/index.js

@@ -440,6 +440,29 @@ class OrderModule extends _BaseModule.BaseModule {
     this.otherParams = otherParams;
   }
 
+  /** Internal intent boundary shared with asynchronous scanner/detail flows. */
+  createCartIntentCommitGuard(action, tempOrder = this.store.tempOrder) {
+    const hook = this.orderHooks?.beforeCartIntentCommit;
+    if (!hook) return () => {};
+    const getScope = this.orderHooks?.getCartIntentScope;
+    const scope = getScope?.();
+    const otherParams = this.otherParams;
+    let committed = false;
+    return () => {
+      if (this.store.tempOrder !== tempOrder || this.otherParams !== otherParams || this.orderHooks?.beforeCartIntentCommit !== hook || this.orderHooks?.getCartIntentScope !== getScope || getScope?.() !== scope) {
+        throw new Error('[Order] Cart intent belongs to a previous order or business');
+      }
+      // Derived gifts, discounts and persistence belong to the accepted intent,
+      // but an asynchronous continuation must never target a different cart.
+      if (committed) return;
+      hook({
+        action,
+        tempOrder
+      });
+      committed = true;
+    };
+  }
+
   /** PC/H5 属于在线店铺；其它或缺失平台统一沿用 POS 行为。 */
   isOnlineStorePlatform() {
     const platform = String(this.otherParams?.platform || '').trim().toLowerCase();
@@ -668,6 +691,7 @@ class OrderModule extends _BaseModule.BaseModule {
     });
   }
   async scanCode(code, customerId) {
+    const beforeCommit = this.createCartIntentCommitGuard('scan_promotion');
     if (this.isActiveVirtualSettlementOrder(this.store.tempOrder)) {
       return {
         type: 'clientCalc',
@@ -715,6 +739,7 @@ class OrderModule extends _BaseModule.BaseModule {
     }));
     const currentSelected = this.getDiscountList().filter(n => n.isSelected);
     if (currentSelected.length && currentSelected.some(n => withScanList.some(m => m.id === n.id))) {
+      beforeCommit();
       await this.syncScannedDiscountsToOriginalDiscountList(this.getDiscountList());
       return {
         type: 'clientCalc',
@@ -748,6 +773,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const normalizedNewDiscountList = newDiscountList ? markScannedDiscounts(newDiscountList, withScanList) : undefined;
     let resolvedDiscountList = normalizedNewDiscountList || this.getDiscountList();
     if (isAvailable && normalizedNewDiscountList) {
+      beforeCommit();
       await this.store.discount?.setDiscountList(normalizedNewDiscountList);
       // 实际写回商品时沿用扫码试算的优先级，避免旧商品行的选卡覆盖本次扫码。
       this.applyDiscount({
@@ -756,6 +782,7 @@ class OrderModule extends _BaseModule.BaseModule {
       await this.syncScannedDiscountsToOriginalDiscountList(this.getDiscountList());
       resolvedDiscountList = this.getDiscountList();
     } else if (shouldRetainForLater) {
+      beforeCommit();
       // 只合并本次识别的卡券；不把试算产生的其他选券状态写回订单。
       const retainedDiscounts = new Map(this.getDiscountList().map(discount => [String(discount.id), discount]));
       evaluatedScannedDiscounts.forEach(discount => {
@@ -3462,7 +3489,6 @@ class OrderModule extends _BaseModule.BaseModule {
     }) : null;
     const productToAdd = linked?.product || product;
     const disableMerge = options?.disableMerge === true;
-    this.assertAndLockProductSettlement(tempOrder, productToAdd);
     const incomingFingerprint = disableMerge ? '' : (0, _utils3.buildProductLineFingerprint)((0, _utils.getProductSkuOptions)(productToAdd), productToAdd.product_bundle);
     const normalizedIncoming = this.normalizeVirtualSettlementProductIfEnabled((0, _utils.mergeOrderProductDisplayFields)(productToAdd, (0, _utils3.normalizeOrderProduct)(productToAdd)));
     if (disableMerge) {
@@ -3523,6 +3549,8 @@ 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 => {
+      options?.beforeCommit?.();
+      this.assertAndLockProductSettlement(tempOrder, productToAdd);
       let committedProduct;
       if (matchedIndex === -1 || !matchedProduct || !shouldMerge) {
         this.captureProductRuntime(tempOrder, productToAdd, normalizedIncoming);
@@ -3675,6 +3703,7 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async addProductToOrder(product, booking, options) {
     const tempOrder = this.ensureTempOrder();
+    const beforeCommit = this.createCartIntentCommitGuard('add_product', tempOrder);
     const salesNoteDrafts = (options?.salesNotes || []).map(draft => ({
       note_type: String(draft.note_type || '').trim(),
       text: {
@@ -3745,7 +3774,8 @@ class OrderModule extends _BaseModule.BaseModule {
             }
             const committedProduct = await this.appendProductLineToTempOrder(tempOrder, splitLine.product, splitLine.booking, {
               insertAtIndex,
-              disableMerge: options?.disableMerge
+              disableMerge: options?.disableMerge,
+              beforeCommit
             });
             attachSalesNoteDrafts(committedProduct);
             if (insertAtIndex !== undefined) insertAtIndex += 1;
@@ -3753,14 +3783,16 @@ class OrderModule extends _BaseModule.BaseModule {
         } else {
           const committedProduct = await this.appendProductLineToTempOrder(tempOrder, product, (0, _lodashEs.cloneDeep)(booking), {
             insertAtIndex,
-            disableMerge: options?.disableMerge
+            disableMerge: options?.disableMerge,
+            beforeCommit
           });
           attachSalesNoteDrafts(committedProduct);
         }
       } else {
         const committedProduct = await this.appendProductLineToTempOrder(tempOrder, product, undefined, {
           insertAtIndex,
-          disableMerge: options?.disableMerge
+          disableMerge: options?.disableMerge,
+          beforeCommit
         });
         attachSalesNoteDrafts(committedProduct);
       }
@@ -3788,6 +3820,7 @@ class OrderModule extends _BaseModule.BaseModule {
   async addProductsToOrder(items, options) {
     const tempOrder = this.ensureTempOrder();
     if (!Array.isArray(items) || items.length === 0) return tempOrder.products;
+    const beforeCommit = this.createCartIntentCommitGuard('add_product', tempOrder);
     for (const item of items || []) {
       const {
         product,
@@ -3800,13 +3833,17 @@ class OrderModule extends _BaseModule.BaseModule {
         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);
+            const appendResult = this.appendProductLineToTempOrder(tempOrder, splitLine.product, splitLine.booking, {
+              beforeCommit
+            });
             if (appendResult) await appendResult;
           }
           continue;
         }
       }
-      const appendResult = this.appendProductLineToTempOrder(tempOrder, product, booking);
+      const appendResult = this.appendProductLineToTempOrder(tempOrder, product, booking, {
+        beforeCommit
+      });
       if (appendResult) await appendResult;
     }
     await this.finalizeProductOrderMutation(tempOrder, options);
@@ -3891,6 +3928,16 @@ class OrderModule extends _BaseModule.BaseModule {
       };
     });
   }
+  isRestrictedCartProductUpdate(tempOrder, params) {
+    if (!this.orderHooks?.beforeCartIntentCommit) return false;
+    if (params.booking || Object.keys(params.updates || {}).some(key => key !== 'num')) {
+      return true;
+    }
+    if (params.updates?.num === undefined) return false;
+    const uid = params.unique_identification_number;
+    const product = uid !== undefined ? tempOrder.products.find(item => String(item.metadata?.unique_identification_number || item.unique_identification_number || '') === String(uid)) : tempOrder.products[(0, _utils3.getProductIdentityIndex)(tempOrder.products, params)];
+    return !product || (0, _utils3.getSafeProductNum)(params.updates.num) > product.num;
+  }
   applyOrderProductUpdateToTempOrder(tempOrder, params) {
     const {
       product_id,
@@ -4089,6 +4136,9 @@ class OrderModule extends _BaseModule.BaseModule {
   }
   async updateOrderProduct(params) {
     const tempOrder = this.ensureTempOrder();
+    if (this.isRestrictedCartProductUpdate(tempOrder, params)) {
+      this.createCartIntentCommitGuard('update_product', tempOrder)();
+    }
     const updatedProductUid = this.applyOrderProductUpdateToTempOrder(tempOrder, params);
     const promotionPayload = await this.evaluatePromotion();
     this.applyDiscount({
@@ -4110,6 +4160,9 @@ class OrderModule extends _BaseModule.BaseModule {
     if (!paramsList.length) {
       return tempOrder.products;
     }
+    if (paramsList.some(params => this.isRestrictedCartProductUpdate(tempOrder, params))) {
+      this.createCartIntentCommitGuard('update_product', tempOrder)();
+    }
     const reapplyBookingDiscountProductUids = paramsList.reduce((acc, params) => {
       const updatedProductUid = this.applyOrderProductUpdateToTempOrder(tempOrder, params);
       // 批量改预约时间时，延迟到最后一次折扣计算里统一恢复已选预约折扣卡。
@@ -4192,6 +4245,9 @@ 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)();
+    }
     tempOrder.products[productIndex] = normalizedProduct;
     this.prepareVirtualSettlementTempOrder(tempOrder);
     const isVirtualSettlement = this.isActiveVirtualSettlementOrder(tempOrder);

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

@@ -517,7 +517,15 @@ export type OrderProductMergeDecisionResult = boolean | {
     reason?: string;
     [key: string]: any;
 };
+export interface OrderCartIntentCommitContext {
+    action: 'add_product' | 'update_product' | 'increase_quantity' | 'scan_promotion';
+    tempOrder: OrderTempOrder | null;
+}
 export interface OrderHooksConfig {
+    /** Optional customer-order guard; called synchronously before the first cart write. */
+    beforeCartIntentCommit?: (context: OrderCartIntentCommitContext) => void;
+    /** Captures tenant/business runtime identity for asynchronous cart intents. */
+    getCartIntentScope?: () => unknown;
     onBeforeMergeProductToOrder?: (context: OrderProductMergeDecisionContext) => OrderProductMergeDecisionResult | Promise<OrderProductMergeDecisionResult>;
 }
 /**

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

@@ -1,6 +1,6 @@
 import { Module, ModuleOptions, PisellCore } from '../../types';
 import { BaseModule } from '../../modules/BaseModule';
-import { BaseSalesOrderProduct, BaseSalesOrderProductIdentity, BaseSalesPaymentStatus, BaseSalesUpdateOrderProductQuantityParams, BaseSalesCalculateProductBookingPriceParams, BaseSalesPriceRecalculationContextChange, BaseSalesProductBookingPriceResult, BaseSalesQuotationCustomerScopeInfo, BaseSalesScanCodeResult, BaseSalesCashPaymentConfig, BaseSalesPayCashParams, BaseSalesPayCashResult, BaseSalesCommitPaymentMethodParams, BaseSalesCommitPaymentMethodResult, BaseSalesConfirmWalletPaymentResult } from './types';
+import { BaseSalesOrderProduct, BaseSalesOrderProductIdentity, BaseSalesPaymentStatus, BaseSalesSubmitSalesOrderParams, BaseSalesUpdateOrderProductQuantityParams, BaseSalesCalculateProductBookingPriceParams, BaseSalesPriceRecalculationContextChange, BaseSalesProductBookingPriceResult, BaseSalesQuotationCustomerScopeInfo, BaseSalesScanCodeResult, BaseSalesCashPaymentConfig, BaseSalesPayCashParams, BaseSalesPayCashResult, BaseSalesCommitPaymentMethodParams, BaseSalesCommitPaymentMethodResult, BaseSalesConfirmWalletPaymentResult } from './types';
 import { OrderModule } from '../../modules/Order';
 import { type PickupTimingBookingInput } from '../../modules/Order/pickupTiming';
 import type { PickupTimingAvailability, PickupTimingSelection, PickupTimingValidationResult } from '../../modules/FulfillmentTiming';
@@ -337,13 +337,8 @@ export declare class BaseSalesImpl extends BaseModule implements Module {
         productList?: Record<string, any>[];
         discountList?: Discount[];
     }): Promise<void>;
-    submitScanOrder<T = any>(params?: {
-        payments?: OrderPaymentSource[];
-        paymentStatus?: BaseSalesPaymentStatus;
-        smallTicketDataFlag?: number;
-        confirmPendingVoucherPayments?: boolean;
-        enhancePayload?: SubmitPayloadEnhancer;
-    }): Promise<T>;
+    submitScanOrder<T = any>(params?: BaseSalesSubmitSalesOrderParams): Promise<T>;
+    private buildVirtualSettlementOrderData;
     private buildVirtualSettlementSubmitData;
     /**
      * 提交当前 Sales 订单。
@@ -351,13 +346,7 @@ export declare class BaseSalesImpl extends BaseModule implements Module {
      * PaymentModal 场景通过 smallTicketDataFlag=1 请求 B 端小票数据；
      * payments 会交给 OrderModule 统一映射为 Sales 协议支付项。
      */
-    submitSalesOrder<T = any>(params?: {
-        payments?: OrderPaymentSource[];
-        paymentStatus?: BaseSalesPaymentStatus;
-        smallTicketDataFlag?: number;
-        confirmPendingVoucherPayments?: boolean;
-        enhancePayload?: SubmitPayloadEnhancer;
-    }): Promise<T>;
+    submitSalesOrder<T = any>(params?: BaseSalesSubmitSalesOrderParams): Promise<T>;
     saveSalesOrderDraft<T = any>(params?: {
         platform?: string;
         businessCode?: string;

package/lib/solution/BaseSales/index.js

@@ -2432,7 +2432,7 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
     // Deprecated compatibility alias. New BaseSales callers should use submitSalesOrder.
     return this.submitSalesOrder(params);
   }
-  async buildVirtualSettlementSubmitData() {
+  buildVirtualSettlementOrderData() {
     if (!this.store.order) return null;
     const tempOrder = this.store.order.getTempOrder();
     if (!this.isActiveVirtualSettlementOrder(tempOrder)) return null;
@@ -2441,6 +2441,21 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
     if (!snapshot || !Number.isFinite(currencyProductId) || currencyProductId <= 0) {
       throw new Error('Virtual currency settlement configuration is invalid.');
     }
+    return {
+      snapshot,
+      currencyProductId,
+      currencyCode: String(tempOrder?.currency_code || ''),
+      currencySymbol: String(tempOrder?.currency_symbol || ''),
+      currencyFormat: String(tempOrder?.currency_format || 'symbol_first')
+    };
+  }
+  async buildVirtualSettlementSubmitData() {
+    const settlement = this.buildVirtualSettlementOrderData();
+    if (!settlement || !this.store.order) return null;
+    const tempOrder = this.store.order.getTempOrder();
+    const {
+      currencyProductId
+    } = settlement;
     const summary = await this.store.order.recalculateSummary({
       createIfMissing: true
     });
@@ -2455,17 +2470,10 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
       });
     }
     const asset = this.store.order.getVirtualCurrencyList().find(item => Number(item?.product_id) === currencyProductId);
-    const currencyCode = String(tempOrder?.currency_code || '');
-    const currencySymbol = String(tempOrder?.currency_symbol || '');
-    const currencyFormat = String(tempOrder?.currency_format || 'symbol_first');
     if (amount.lte(0)) {
       return {
-        payments: [],
-        snapshot,
-        currencyProductId,
-        currencyCode,
-        currencySymbol,
-        currencyFormat
+        ...settlement,
+        payments: []
       };
     }
     if (!asset) {
@@ -2519,12 +2527,8 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
       };
     }
     return {
-      payments: [payment],
-      snapshot,
-      currencyProductId,
-      currencyCode,
-      currencySymbol,
-      currencyFormat
+      ...settlement,
+      payments: [payment]
     };
   }
 
@@ -2541,9 +2545,11 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
     if (this.isPickupTimingEnabled()) await this.preparePickupTimingForCheckout({
       freeze: true
     });
-    const virtualSettlement = await this.buildVirtualSettlementSubmitData();
+    const isDeferredPayment = params?.paymentExecution === 'deferred';
+    const virtualPaymentSettlement = isDeferredPayment ? null : await this.buildVirtualSettlementSubmitData();
+    const virtualSettlement = isDeferredPayment ? this.buildVirtualSettlementOrderData() : virtualPaymentSettlement;
     // this.store.order.persistTempOrder();
-    const inferredPaymentStatus = this.getSubmitPaymentStatus(params?.paymentStatus);
+    const inferredPaymentStatus = isDeferredPayment ? undefined : this.getSubmitPaymentStatus(params?.paymentStatus);
     const smallTicketDataFlag = params?.smallTicketDataFlag ?? this.getDefaultCheckoutSmallTicketDataFlag();
     const virtualSettlementEnhancePayload = virtualSettlement ? (payload, ctx) => {
       const callerPayload = params?.enhancePayload ? params.enhancePayload(payload, ctx) : payload;
@@ -2564,7 +2570,20 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
         currency_format: virtualSettlement.currencyFormat
       };
     } : params?.enhancePayload;
-    const enhancePayload = this.buildSubmitPayloadEnhancerWithOpenDataConfig(virtualSettlementEnhancePayload);
+    const configuredEnhancePayload = this.buildSubmitPayloadEnhancerWithOpenDataConfig(virtualSettlementEnhancePayload);
+    // Apply this last so neither a stale draft status nor a caller enhancer can
+    // turn deferred submission into payment. The live wallet selection is untouched.
+    const enhancePayload = isDeferredPayment ? (payload, ctx) => {
+      const enhancedPayload = configuredEnhancePayload ? configuredEnhancePayload(payload, ctx) : payload;
+      const {
+        payment_status: _paymentStatus,
+        ...orderPayload
+      } = enhancedPayload;
+      return {
+        ...orderPayload,
+        payments: []
+      };
+    } : configuredEnhancePayload;
     const submitParams = {
       cacheId: this.cacheId,
       platform: this.otherParams?.platform,
@@ -2572,8 +2591,10 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
       channel: this.getSubmitOrderSalesChannel(),
       type: this.otherParams?.type,
       request_unique_idempotency_token: this.store.order.generateIdempotencyToken(),
-      ...(virtualSettlement ? {
-        payments: virtualSettlement.payments
+      ...(isDeferredPayment ? {
+        payments: []
+      } : virtualPaymentSettlement ? {
+        payments: virtualPaymentSettlement.payments
       } : params?.payments !== undefined ? {
         payments: params.payments
       } : {}),
@@ -2583,7 +2604,7 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
       ...(smallTicketDataFlag !== undefined ? {
         smallTicketDataFlag
       } : {}),
-      ...(virtualSettlement ? {
+      ...(isDeferredPayment || virtualSettlement ? {
         confirmPendingVoucherPayments: false
       } : params?.confirmPendingVoucherPayments !== undefined ? {
         confirmPendingVoucherPayments: params.confirmPendingVoucherPayments
@@ -3921,7 +3942,7 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
   async addProductToOrder(product, booking, options) {
     try {
       if (!this.store.order) throw new Error('order 模块未初始化');
-      const products = await this.store.order.addProductToOrder(product, booking, options);
+      const products = options === undefined ? await this.store.order.addProductToOrder(product, booking) : await this.store.order.addProductToOrder(product, booking, options);
       // // 需要叠加
       // if (this.hooks.onAddProductOverlay) {
       //   const res = this.hooks.onAddProductOverlay(是否叠加, product)
@@ -4010,7 +4031,7 @@ class BaseSalesImpl extends _BaseModule.BaseModule {
   async removeProductsFromOrder(identities, options) {
     try {
       if (!this.store.order) throw new Error('order 模块未初始化');
-      return await this.store.order.removeProductsFromOrder(identities, options);
+      return options === undefined ? await this.store.order.removeProductsFromOrder(identities) : await this.store.order.removeProductsFromOrder(identities, options);
     } catch (error) {
       throw error;
     }