@pisell/pisellos 0.10.54 → 0.10.56

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[]>;

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/plugins/request.d.ts

@@ -56,6 +56,10 @@ export interface CacheProps {
  * 请求配置
  */
 export interface RequestOptions {
+    /** Customer-only, credential-free GET /open/document/{id} on picoding. */
+    publicInvoiceDocument?: boolean;
+    /** Route through the host's configured picoding environment. */
+    pisell2?: boolean;
     /** Let the caller handle read-only preview failures without host navigation/toasts. */
     manualErrorHandling?: boolean;
     skipErrorHandler?: boolean;

package/lib/shared/receipt/loadCustomerInvoiceLayout.d.ts

@@ -0,0 +1,22 @@
+import type { RequestPlugin } from '../../plugins/request';
+import { type InvoiceLayoutConfig } from '../../modules/OpenData';
+export interface PublicInvoiceDocumentResponse {
+    status: boolean;
+    code: number;
+    message?: string;
+    data: {
+        id: number;
+        data?: {
+            template_settings?: unknown;
+        } | null;
+    } | null;
+}
+interface TemplateScope {
+    tenantId: string | number;
+    shopId: string | number;
+    identity: string;
+    businessCode: string;
+    channel: string;
+}
+export declare function loadCustomerInvoiceLayout(request: RequestPlugin, scope: TemplateScope): Promise<InvoiceLayoutConfig>;
+export {};

package/lib/shared/receipt/loadCustomerInvoiceLayout.js

@@ -0,0 +1,86 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.loadCustomerInvoiceLayout = loadCustomerInvoiceLayout;
+var _OpenData = require("../../modules/OpenData");
+// Page-runtime caches: also retain DEFAULT on failure, without automatic retries.
+const caches = new WeakMap();
+const isRecord = value => !!value && typeof value === 'object' && !Array.isArray(value);
+function documentId(value) {
+  if (typeof value !== 'string' && typeof value !== 'number') return null;
+  const text = String(value).trim();
+  if (!/^\d+$/.test(text)) return null;
+  const id = Number(text);
+  return Number.isSafeInteger(id) && id > 0 ? String(id) : null;
+}
+function loadCustomerInvoiceLayout(request, scope) {
+  let cache = caches.get(request);
+  if (!cache) {
+    cache = {
+      scopes: new Map(),
+      documents: new Map()
+    };
+    caches.set(request, cache);
+  }
+  const target = `${scope.businessCode}+${scope.channel}`;
+  const key = JSON.stringify([scope.tenantId, scope.shopId, scope.identity, scope.businessCode, scope.channel]);
+  const cached = cache.scopes.get(key);
+  if (cached) return cached;
+  let id = null;
+  const task = (async () => {
+    const response = await request.post(`/open/my-pisell/${encodeURIComponent(String(scope.shopId))}/setting`, {
+      scope: 'board',
+      target,
+      section_code: ['documents']
+    }, {
+      pisell2: true,
+      prefix: false,
+      headers: scope.tenantId ? {
+        'Tenant-Id': String(scope.tenantId)
+      } : {},
+      manualErrorHandling: true,
+      skipErrorHandler: true,
+      timeout: 15000
+    });
+    if (response?.status !== true || response.code !== 200 || !isRecord(response.data)) throw new Error(response?.message || 'Invoice OpenData is unavailable');
+    const config = response.data;
+    const raw = config['documents.invoice_template'];
+    id = documentId(raw);
+    if (!id) {
+      // Preserve the existing non-numeric legacy template / invoice_edit contract.
+      const numericLike = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i;
+      return typeof raw === 'string' && raw.trim() && !numericLike.test(raw.trim()) ? (0, _OpenData.normalizeInvoiceLayoutFromTemplateSettings)((0, _OpenData.normalizeInvoiceTemplateSettings)(config)) : (0, _OpenData.getDefaultInvoiceLayoutConfig)();
+    }
+    const docKey = JSON.stringify([key, id]);
+    let pending = cache.documents.get(docKey);
+    if (!pending) {
+      const expectedId = id;
+      pending = (async () => {
+        const result = await request.get(`/open/document/${expectedId}`, {}, {
+          publicInvoiceDocument: true
+        });
+        if (result?.status !== true || result.code !== 200) throw new Error(result?.message || 'Invoice Document request failed');
+        const doc = result.data;
+        if (!doc || documentId(doc.id) !== expectedId) throw new Error('Invoice Document is unavailable or its ID does not match');
+        if (!isRecord(doc.data) || !isRecord(doc.data.template_settings)) throw new Error('Invoice Document has no template_settings');
+        const settings = (0, _OpenData.normalizeRawInvoiceTemplateSettings)(doc.data.template_settings);
+        if (settings.modules.length === 0) throw new Error('Invoice Document has no usable template modules');
+        return (0, _OpenData.normalizeInvoiceLayoutFromTemplateSettings)(settings);
+      })().catch(error => fallback(error, target, expectedId));
+      cache.documents.set(docKey, pending);
+    }
+    return pending;
+  })().catch(error => fallback(error, target, id));
+  cache.scopes.set(key, task);
+  return task;
+}
+function fallback(error, target, id) {
+  console.warn('[OrderInvoicePreview] Template unavailable; using DEFAULT', {
+    target,
+    documentId: id,
+    message: error instanceof Error ? error.message : 'Template request failed'
+  });
+  return (0, _OpenData.getDefaultInvoiceLayoutConfig)();
+}

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;