@pisell/pisellos 0.10.2 → 0.10.4

package/lib/model/strategy/adapter/promotion/examples.d.ts

@@ -136,3 +136,89 @@ export declare const BUY_X_GET_Y_FREE_STRATEGY: {
         };
     }[];
 };
+/**
+ * ITEM_REWARD 策略配置示例：儿童票触发婴儿票免费
+ *
+ * 业务规则：
+ * - 条件商品：儿童票（conditions.rules.productIdAndVariantId）
+ * - 奖励商品：购物车/订单内已经存在的婴儿票（actions[0].config.rewardTargets）
+ * - 本 action 不自动新增婴儿票；每次购物车变更后由统一促销链路重算
+ *
+ * 字段说明：
+ * - type: "ITEM_REWARD" 表示商品奖励 action
+ * - target: "product" 表示本期只奖励商品行
+ * - config.rewardTargets: 奖励对象数组，支持 { product_id, product_variant_id }
+ * - config.targetSelection: "consumer_best" 表示目标商品超额时选择节省金额最高的商品
+ * - value.rewardMethod:
+ *   - "free": 目标商品最终价为 0
+ *   - "percent_off": 百分比折扣，rewardValue 为 0-100
+ *   - "amount_off": 每个目标商品固定减免 rewardValue
+ *   - "fixed_price": 目标商品最终单价为 rewardValue
+ * - value.quantityRule:
+ *   - "per_condition_quantity": 每满足 triggerQuantity 个条件商品，奖励 rewardQuantity 个目标商品
+ *   - "all_targets": 满足条件后奖励全部目标商品
+ *   - "max_per_order": 满足条件后每单最多奖励 maxRewardQuantity 个目标商品
+ */
+export declare const ITEM_REWARD_STRATEGY: {
+    metadata: {
+        id: string;
+        name: {
+            en: string;
+            'zh-CN': string;
+            'zh-HK': string;
+        };
+        type: string;
+        custom: {
+            display: {
+                product_card: {
+                    text: {
+                        en: string;
+                        'zh-CN': string;
+                        'zh-HK': string;
+                    };
+                    type: string;
+                };
+            };
+        };
+    };
+    conditions: {
+        operator: string;
+        rules: ({
+            type: string;
+            field: string;
+            value: string;
+            operator: string;
+        } | {
+            type: string;
+            field: string;
+            value: {
+                product_id: number;
+                product_variant_id: number;
+            }[];
+            operator: string;
+        })[];
+        actionIds: string[];
+    };
+    actions: {
+        id: string;
+        type: string;
+        value: {
+            rewardMethod: string;
+            rewardValue: number;
+            quantityRule: string;
+            triggerQuantity: number;
+            rewardQuantity: number;
+            maxRewardQuantity: number;
+        };
+        valueType: string;
+        target: string;
+        priority: number;
+        config: {
+            rewardTargets: {
+                product_id: number;
+                product_variant_id: number;
+            }[];
+            targetSelection: string;
+        };
+    }[];
+};

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

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var examples_exports = {};
 __export(examples_exports, {
   BUY_X_GET_Y_FREE_STRATEGY: () => BUY_X_GET_Y_FREE_STRATEGY,
+  ITEM_REWARD_STRATEGY: () => ITEM_REWARD_STRATEGY,
   X_ITEMS_FOR_Y_PRICE_STRATEGY: () => X_ITEMS_FOR_Y_PRICE_STRATEGY
 });
 module.exports = __toCommonJS(examples_exports);
@@ -185,8 +186,98 @@ var BUY_X_GET_Y_FREE_STRATEGY = {
     }
   ]
 };
+var ITEM_REWARD_STRATEGY = {
+  metadata: {
+    id: "STRATEGY_003",
+    name: {
+      en: "Infant ticket free with child ticket",
+      "zh-CN": "儿童票触发婴儿票免费",
+      "zh-HK": "兒童票觸發嬰兒票免費"
+    },
+    type: "promotion",
+    custom: {
+      display: {
+        product_card: {
+          text: {
+            en: "Infant ticket free",
+            "zh-CN": "婴儿票免费",
+            "zh-HK": "嬰兒票免費"
+          },
+          type: "tag"
+        }
+      }
+    }
+  },
+  conditions: {
+    operator: "and",
+    rules: [
+      {
+        type: "operator",
+        field: "currentDateTime",
+        value: "2023-01-01 00:00:00",
+        operator: ">="
+      },
+      {
+        type: "operator",
+        field: "currentDateTime",
+        value: "2030-01-01 00:00:00",
+        operator: "<="
+      },
+      {
+        type: "operator",
+        field: "productIdAndVariantId",
+        value: [
+          {
+            product_id: 1001,
+            // 条件商品：儿童票
+            product_variant_id: 0
+            // 0 = 匹配任意变体
+          }
+        ],
+        operator: "product_match"
+      }
+    ],
+    actionIds: ["1"]
+  },
+  actions: [
+    {
+      id: "1",
+      type: "ITEM_REWARD",
+      value: {
+        rewardMethod: "free",
+        // free | percent_off | amount_off | fixed_price
+        rewardValue: 0,
+        // free 可省略；其他 rewardMethod 使用
+        quantityRule: "per_condition_quantity",
+        // per_condition_quantity | all_targets | max_per_order
+        triggerQuantity: 1,
+        // N：每满足 N 个条件商品
+        rewardQuantity: 1,
+        // Y：奖励 Y 个目标商品
+        maxRewardQuantity: 1
+        // max_per_order 使用；本例保留为配置示意
+      },
+      valueType: "object",
+      target: "product",
+      priority: 1,
+      config: {
+        rewardTargets: [
+          {
+            product_id: 2001,
+            // 奖励对象：婴儿票
+            product_variant_id: 0
+            // 0 = 匹配任意变体
+          }
+        ],
+        targetSelection: "consumer_best"
+        // consumer_best = 按可节省金额从高到低选择
+      }
+    }
+  ]
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUY_X_GET_Y_FREE_STRATEGY,
+  ITEM_REWARD_STRATEGY,
   X_ITEMS_FOR_Y_PRICE_STRATEGY
 });

package/lib/model/strategy/adapter/promotion/index.d.ts

@@ -1,4 +1,4 @@
 export { PromotionEvaluator } from './evaluator';
 export { PromotionAdapter } from './adapter';
 export { default } from './adapter';
-export { X_ITEMS_FOR_Y_PRICE_STRATEGY, BUY_X_GET_Y_FREE_STRATEGY, } from './examples';
+export { X_ITEMS_FOR_Y_PRICE_STRATEGY, BUY_X_GET_Y_FREE_STRATEGY, ITEM_REWARD_STRATEGY, } from './examples';

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

@@ -30,6 +30,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var promotion_exports = {};
 __export(promotion_exports, {
   BUY_X_GET_Y_FREE_STRATEGY: () => import_examples.BUY_X_GET_Y_FREE_STRATEGY,
+  ITEM_REWARD_STRATEGY: () => import_examples.ITEM_REWARD_STRATEGY,
   PromotionAdapter: () => import_adapter.PromotionAdapter,
   PromotionEvaluator: () => import_evaluator.PromotionEvaluator,
   X_ITEMS_FOR_Y_PRICE_STRATEGY: () => import_examples.X_ITEMS_FOR_Y_PRICE_STRATEGY,
@@ -43,6 +44,7 @@ var import_examples = require("./examples");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BUY_X_GET_Y_FREE_STRATEGY,
+  ITEM_REWARD_STRATEGY,
   PromotionAdapter,
   PromotionEvaluator,
   X_ITEMS_FOR_Y_PRICE_STRATEGY

package/lib/model/strategy/adapter/promotion/type.d.ts

@@ -12,6 +12,8 @@ export declare const PROMOTION_ACTION_TYPES: {
     readonly X_ITEMS_FOR_Y_PRICE: "X_ITEMS_FOR_Y_PRICE";
     /** 买X送Y（买X件送Y件，可累计） */
     readonly BUY_X_GET_Y_FREE: "BUY_X_GET_Y_FREE";
+    /** 商品奖励（满足条件后，订单内指定目标商品享优惠） */
+    readonly ITEM_REWARD: "ITEM_REWARD";
     /** 固定折扣 */
     readonly DISCOUNT_RATE: "DISCOUNT_RATE";
     /** 固定减价 */
@@ -66,6 +68,59 @@ export interface BuyXGetYFreeConfig {
     /** 可选的赠品列表 */
     giftProducts?: ProductIdentifier[];
 }
+/**
+ * 商品奖励优惠方式
+ *
+ * - free: 目标商品最终价为 0
+ * - percent_off: 目标商品按百分比折扣，rewardValue 为 0-100
+ * - amount_off: 每个目标商品固定减免 rewardValue
+ * - fixed_price: 目标商品改为固定价 rewardValue
+ */
+export type ItemRewardMethod = 'free' | 'percent_off' | 'amount_off' | 'fixed_price';
+/**
+ * 商品奖励数量规则
+ *
+ * - per_condition_quantity: 每满足 N 个条件商品，奖励 Y 个目标商品
+ * - all_targets: 满足条件后奖励全部目标商品
+ * - max_per_order: 满足条件后每单最多奖励固定数量目标商品
+ */
+export type ItemRewardQuantityRule = 'per_condition_quantity' | 'all_targets' | 'max_per_order';
+/** 商品奖励目标选择规则 */
+export type ItemRewardTargetSelection = 'consumer_best';
+/**
+ * 商品奖励 - Action Value
+ *
+ * @example
+ * value: {
+ *   rewardMethod: 'free',
+ *   quantityRule: 'per_condition_quantity',
+ *   triggerQuantity: 1,
+ *   rewardQuantity: 1,
+ * }
+ */
+export interface ItemRewardValue {
+    /** 奖励方式 */
+    rewardMethod: ItemRewardMethod;
+    /** 奖励值：percent_off/amount_off/fixed_price 使用，free 可省略 */
+    rewardValue?: number;
+    /** 奖励数量规则 */
+    quantityRule: ItemRewardQuantityRule;
+    /** 每满足 N 个条件商品；默认 1 */
+    triggerQuantity?: number;
+    /** 奖励 Y 个目标商品；默认 1 */
+    rewardQuantity?: number;
+    /** 每单最多奖励 Y 个目标商品；max_per_order 使用 */
+    maxRewardQuantity?: number;
+}
+/**
+ * 商品奖励 - Action Config
+ */
+export interface ItemRewardConfig {
+    /** 奖励对象，本期支持指定商品/变体；product_variant_id=0 表示任意变体 */
+    rewardTargets?: ProductIdentifier[];
+    /** 目标商品超额时的选择规则；本期支持 consumer_best */
+    targetSelection?: ItemRewardTargetSelection;
+}
 /**
  * 商品标识
  *
@@ -102,10 +157,19 @@ export interface BuyXGetYFreeAction extends Omit<ActionEffect, 'type' | 'value'
     valueType: 'object';
     config?: BuyXGetYFreeConfig;
 }
+/**
+ * 商品奖励 Action
+ */
+export interface ItemRewardAction extends Omit<ActionEffect, 'type' | 'value' | 'config'> {
+    type: typeof PROMOTION_ACTION_TYPES.ITEM_REWARD;
+    value: ItemRewardValue;
+    valueType: 'object';
+    config?: ItemRewardConfig;
+}
 /**
  * 促销活动 Action 联合类型
  */
-export type PromotionAction = XItemsForYPriceAction | BuyXGetYFreeAction;
+export type PromotionAction = XItemsForYPriceAction | BuyXGetYFreeAction | ItemRewardAction;
 /**
  * 促销相关运算符
  */
@@ -170,6 +234,8 @@ export interface PromotionProduct {
     quantity: number;
     /** 原价 */
     original_price?: number;
+    /** 内部字段：编辑态订单行只允许参与 ITEM_REWARD，避免旧促销误算历史行 */
+    _promotionOnlyForItemReward?: boolean;
 }
 /**
  * 促销活动适配器转换结果
@@ -195,7 +261,7 @@ export interface PromotionTransformResult {
 /**
  * Action 详情联合类型
  */
-export type PromotionActionDetail = XItemsForYPriceActionDetail | BuyXGetYFreeActionDetail;
+export type PromotionActionDetail = XItemsForYPriceActionDetail | BuyXGetYFreeActionDetail | ItemRewardActionDetail;
 /**
  * X件Y元 Action 详情
  */
@@ -226,6 +292,28 @@ export interface BuyXGetYFreeActionDetail {
     /** 可选的赠品列表 */
     giftProducts: ProductIdentifier[];
 }
+/**
+ * 商品奖励 Action 详情
+ */
+export interface ItemRewardActionDetail {
+    type: typeof PROMOTION_ACTION_TYPES.ITEM_REWARD;
+    /** 奖励方式 */
+    rewardMethod: ItemRewardMethod;
+    /** 奖励值：percent_off/amount_off/fixed_price 使用，free 为 0 */
+    rewardValue: number;
+    /** 奖励数量规则 */
+    quantityRule: ItemRewardQuantityRule;
+    /** 每满足 N 个条件商品；默认 1 */
+    triggerQuantity: number;
+    /** 奖励 Y 个目标商品；默认 1 */
+    rewardQuantity: number;
+    /** 每单最多奖励 Y 个目标商品；max_per_order 使用 */
+    maxRewardQuantity?: number;
+    /** 奖励对象，本期支持指定商品/变体 */
+    rewardTargets: ProductIdentifier[];
+    /** 目标商品超额时的选择规则 */
+    targetSelection: ItemRewardTargetSelection;
+}
 /**
  * X件Y元 - 业务层计算结果
  *

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

@@ -28,6 +28,8 @@ var PROMOTION_ACTION_TYPES = {
   X_ITEMS_FOR_Y_PRICE: "X_ITEMS_FOR_Y_PRICE",
   /** 买X送Y（买X件送Y件，可累计） */
   BUY_X_GET_Y_FREE: "BUY_X_GET_Y_FREE",
+  /** 商品奖励（满足条件后，订单内指定目标商品享优惠） */
+  ITEM_REWARD: "ITEM_REWARD",
   /** 固定折扣 */
   DISCOUNT_RATE: "DISCOUNT_RATE",
   /** 固定减价 */

package/lib/modules/BaseModule.d.ts

@@ -8,6 +8,7 @@ export declare class BaseModule {
     protected core: PisellCore;
     constructor(name?: string, version?: string);
     destroy(): void;
+    private isRecord;
     checkSaveCache({ cacheId, fatherModule, store, cacheKey, }: {
         cacheId: string | undefined;
         fatherModule: string | undefined;

package/lib/modules/BaseModule.js

@@ -34,6 +34,9 @@ var BaseModule = class {
     this.core.effects.offByModuleDestroy(this.name);
     this.core.unregisterModule(this);
   }
+  isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+  }
   // 提供统一的缓存 module 里的数据的方法
   checkSaveCache({
     cacheId,
@@ -41,45 +44,29 @@ var BaseModule = class {
     store,
     cacheKey
   }) {
-    const window = this.core.getPlugin("window");
-    if (cacheId) {
+    if (!cacheId)
+      return;
+    try {
+      const window = this.core.getPlugin("window");
+      const sessionStorage = window == null ? void 0 : window.sessionStorage;
+      if (!sessionStorage)
+        return;
+      const storageKey = fatherModule || cacheId;
+      const rawCacheData = sessionStorage.getItem(storageKey);
+      const parsedCacheData = rawCacheData ? JSON.parse(rawCacheData) : {};
+      if (!this.isRecord(parsedCacheData))
+        return;
+      const cacheBucket = fatherModule ? this.isRecord(parsedCacheData[cacheId]) ? parsedCacheData[cacheId] : {} : parsedCacheData;
+      const moduleBucket = this.isRecord(cacheBucket[this.name]) ? cacheBucket[this.name] : {};
+      cacheKey.forEach((key) => {
+        moduleBucket[key] = store == null ? void 0 : store[key];
+      });
+      cacheBucket[this.name] = moduleBucket;
       if (fatherModule) {
-        const currentCacheData = window.sessionStorage.getItem(fatherModule);
-        let currentCacheDataObj = JSON.parse(currentCacheData || "{}");
-        if (!currentCacheData || !currentCacheDataObj[cacheId]) {
-          currentCacheDataObj = {
-            [cacheId]: {
-              [this.name]: {}
-            }
-          };
-        }
-        if (!currentCacheDataObj[cacheId][this.name]) {
-          currentCacheDataObj[cacheId][this.name] = {};
-        }
-        cacheKey.forEach((key) => {
-          currentCacheDataObj[cacheId][this.name][key] = store == null ? void 0 : store[key];
-        });
-        window.sessionStorage.setItem(
-          fatherModule,
-          JSON.stringify(currentCacheDataObj)
-        );
-      } else {
-        let currentCacheData = window.sessionStorage.getItem(cacheId);
-        let currentCacheDataObj = JSON.parse(currentCacheData || "{}");
-        if (!currentCacheDataObj) {
-          currentCacheDataObj = {};
-        }
-        if (!currentCacheDataObj[this.name]) {
-          currentCacheDataObj[this.name] = {};
-        }
-        cacheKey.forEach((key) => {
-          currentCacheDataObj[this.name][key] = store[key];
-        });
-        window.sessionStorage.setItem(
-          cacheId,
-          JSON.stringify(currentCacheDataObj)
-        );
+        parsedCacheData[cacheId] = cacheBucket;
       }
+      sessionStorage.setItem(storageKey, JSON.stringify(parsedCacheData));
+    } catch {
     }
   }
   effectsOn(eventType, callback) {

package/lib/modules/BookingContext/utils/buildCacheItemFromOrderLine.js

@@ -184,7 +184,7 @@ function synthesizeProductResourceFromBooking(booking) {
   };
 }
 function buildCacheItemFromOrderLine(input) {
-  var _a, _b, _c, _d, _e, _f;
+  var _a, _b, _c, _d, _e, _f, _g;
   const { product, booking, sourceProduct } = input;
   const resolvedId = product.product_id ?? (sourceProduct == null ? void 0 : sourceProduct.id);
   const selling = Number(product.selling_price ?? 0);
@@ -259,6 +259,7 @@ function buildCacheItemFromOrderLine(input) {
     price: (sourceProduct == null ? void 0 : sourceProduct.price) ?? selling,
     selling_price: product.selling_price,
     original_price: product.original_price,
+    ...Number(((_g = product.product_sku) == null ? void 0 : _g.open_sold_weight) || 0) === 1 ? { product_sku: JSON.parse(JSON.stringify(product.product_sku)) } : {},
     ...productOptionString ? { product_option_string: productOptionString } : {},
     _extend: extend,
     new: 0,

package/lib/modules/BookingContext/utils/buildNormalProductCacheItemFromOrderLine.js

@@ -78,7 +78,7 @@ function mapOrderBundleToOtherBundle(bundle) {
   });
 }
 function buildNormalProductCacheItemFromOrderLine(input) {
-  var _a, _b, _c, _d, _e;
+  var _a, _b, _c, _d, _e, _f;
   const { product, sourceProduct } = input;
   const resolvedId = product.product_id ?? (sourceProduct == null ? void 0 : sourceProduct.id);
   const sourcePrice = resolveSourceProductPrice(product, sourceProduct);
@@ -144,6 +144,7 @@ function buildNormalProductCacheItemFromOrderLine(input) {
     note: product.note,
     order_detail_id: product.order_detail_id ?? null,
     discount_list: discountList,
+    ...Number(((_f = product.product_sku) == null ? void 0 : _f.open_sold_weight) || 0) === 1 ? { product_sku: JSON.parse(JSON.stringify(product.product_sku)) } : {},
     new: 0,
     autoClose: true,
     _extend: extend

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

@@ -27,6 +27,8 @@ export declare class OpenDataModule extends BaseModule implements Module {
     fetchOpenData(params: OpenDataFetchParams): Promise<OpenDataConfig>;
     getOpenData(): OpenDataConfig | null;
     getLastFetchedAt(): number | null;
+    /** 清除内存与 sessionStorage 镜像中的 OpenData，供宿主切店时调用。 */
+    clearCache(): void;
     checkAvailability(scheduleModule?: ScheduleModule): OpenDataAvailabilityResult;
     storeChange(): void;
 }

package/lib/modules/OpenData/index.js

@@ -104,6 +104,11 @@ var OpenDataModule = class extends import_BaseModule.BaseModule {
   getLastFetchedAt() {
     return this.store.lastFetchedAt ?? null;
   }
+  /** 清除内存与 sessionStorage 镜像中的 OpenData，供宿主切店时调用。 */
+  clearCache() {
+    this.store.data = null;
+    this.store.lastFetchedAt = null;
+  }
   checkAvailability(scheduleModule) {
     var _a;
     const scheduleList = scheduleModule ? scheduleModule == null ? void 0 : scheduleModule.getScheduleListByIds(

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

@@ -3,7 +3,7 @@ import { BaseModule } from '../BaseModule';
 import { OrderModuleAPI, CommitOrderParams, UpdateOrderBookingParams, UpdateOrderProductParams, UpdateOrderProductQuantityParams, CancelOrderParams, ChangeBookingStatusParams, CheckoutOrderParams } from './types';
 import { CartItem } from '../Cart/types';
 import { type SubmitPayloadEnhancer } from './utils';
-import type { OrderAmountSnapshot, AddProductBookingInput, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions } from './types';
+import type { OrderAmountSnapshot, AddProductBookingInput, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, OrderPaymentUpdateOptions, OrderPaymentUpdateResult, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions } from './types';
 import type { ICustomer } from '../AccountList/types';
 import type { Discount } from '../Discount/types';
 import { UnavailableReason } from '../Rules/types';
@@ -14,7 +14,12 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private request;
     private logger;
     private window;
+    private appPlugin;
     private cacheId;
+    private fatherModule;
+    private openCache;
+    private sessionStoragePersistEnabled;
+    private sessionStorageRestoreRecord;
     private salesSummaryModuleName;
     private rulesHooksOverride?;
     private moduleHooksOverride?;
@@ -45,6 +50,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     static populateSavedAmounts(productList: Array<Record<string, any>>, discountList: Array<Record<string, any>>): void;
     private applyProductDiscountPrices;
     constructor(name?: string, version?: string);
+    private syncSessionStorageOptions;
     initialize(core: PisellCore, options: ModuleOptions): Promise<void>;
     destroy(): Promise<void>;
     /**
@@ -80,6 +86,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private ensureEditDiscountConfigForProductChange;
     scanCode(code: string, customerId?: number): Promise<{
         isAvailable: boolean;
+        isAccepted?: boolean;
         discountList: Discount[];
         type: 'server' | 'clientCalc';
         unavailableReason?: UnavailableReason;
@@ -135,7 +142,8 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     }): void;
     /**
      * 控制 IndexedDB 草稿（saveDraft）是否写入。
-     * localStorage 版 tempOrder 持久化已废弃，此方法仅影响 saveDraft。
+     * 此开关仅影响 saveDraft；可选 sessionStorage 会话恢复由
+     * enableSessionStoragePersist 独立控制。
      *
      * @example
      * order.setEnableTempOrderPersist(false); // BigSale 弹窗：跳过 ~1s 的 dbUpdate
@@ -143,8 +151,12 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     setEnableTempOrderPersist(enabled: boolean): void;
     /** 是否允许 saveDraft 写入 IndexedDB 草稿。 */
     isTempOrderPersistEnabled(): boolean;
-    /** @deprecated OrderModule 不再负责 tempOrder localStorage 持久化；草稿保存请使用 IndexedDB saveDraft。 */
+    /**
+     * 在 UnifiedBookingSales 显式开启会话恢复时，将完整 tempOrder 写入
+     * sessionStorage 的 cacheId 分桶。写入失败由 BaseModule 静默降级。
+     */
     persistTempOrder(): void;
+    consumeSessionStorageRestore(): Record<string, any> | null;
     notifyTempOrderChanged(): void;
     private createDefaultTempOrderInstance;
     private createExternalSaleNumber;
@@ -177,6 +189,9 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     };
     private calculateDepositPaidAmount;
     private resolveNextOrderPaymentType;
+    private getPaymentNumberAppData;
+    private getPaymentNumberDevicePrefixSync;
+    private getPaymentNumberDevicePrefixAsync;
     private normalizePaymentSource;
     private updateTempOrderPaymentStatus;
     private shouldKeepPaymentStatusAfterAmountRecalc;
@@ -308,19 +323,20 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      * 用一组支付来源覆盖当前订单支付项。
      *
      * 入参允许来自 PaymentModule 的 PaymentItem，内部统一映射为 Sales 协议：
-     * uuid -> metadata.unique_payment_number，id -> custom_payment_id，
+     * 新支付来源的 uuid 会作为 payment_number 的唯一号段，id -> custom_payment_id，
      * isSynced 等运行态字段不会进入 tempOrder.payments。
      */
     setOrderPayments(payments: OrderPaymentSource[]): OrderPaymentData[];
-    /** 追加单个支付项，并立即持久化当前 tempOrder。 */
+    /** 同步兼容入口：按调用当下的 device_id 或 LOCAL 生成支付编号。 */
     addOrderPayment(payment: OrderPaymentSource): OrderPaymentData[];
+    /** 异步入口：创建支付项时读取最新 IoT 设备短号。 */
+    addOrderPaymentAsync(payment: OrderPaymentSource): Promise<OrderPaymentData[]>;
+    private addOrderPaymentWithDevicePrefix;
     /**
-     * 按支付唯一号、后端支付 ID、自定义支付方式 ID 或旧 uuid 更新支付项。
-     *
-     * 该方法服务 PaymentModal 的 void / 编辑场景；更新 metadata 时会做浅合并，
-     * 避免覆盖 unique_payment_number、现金实付/找零等已有元数据。
+     * 默认按支付唯一号精确更新；仅显式指定 legacy 时兼容历史支付标识。
+     * metadata 与 transactions 会分别合并，避免覆盖支付会话号和已有交易记录。
      */
-    updateOrderPayment(paymentIdentity: string | number, updates: Partial<OrderPaymentData> & Record<string, any>): OrderPaymentData[];
+    updateOrderPayment(paymentIdentity: string | number, updates: Partial<OrderPaymentData> & Record<string, any>, options?: OrderPaymentUpdateOptions): Promise<OrderPaymentUpdateResult>;
     /** 从当前订单支付项中移除指定支付项。 */
     deleteOrderPayment(paymentIdentity: string | number): OrderPaymentData[];
     private confirmPendingVoucherPaymentsInList;
@@ -343,7 +359,11 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      */
     updateVoucherOrderPayments(payments: OrderPaymentSource[], options?: {
         status?: 'paid' | 'payment_pending';
+        devicePrefix?: string;
     }): OrderPaymentData[];
+    updateVoucherOrderPaymentsAsync(payments: OrderPaymentSource[], options?: {
+        status?: 'paid' | 'payment_pending';
+    }): Promise<OrderPaymentData[]>;
     private shouldMergeProductToOrder;
     private hasOrderProductLineNote;
     /**
@@ -428,6 +448,14 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
         type?: string;
     }): import("./types").OrderSubmitPayload;
     applyLocalPrintOrderNumbers(order?: Record<string, any> | null): Promise<OrderTempOrder>;
+    saveTempOrderAsDraft<T = any>(params?: {
+        cacheId?: string;
+        platform?: string;
+        businessCode?: string;
+        channel?: string;
+        type?: string;
+        enhancePayload?: SubmitPayloadEnhancer;
+    }): Promise<T>;
     /**
      * 提交当前 Sales tempOrder。
      *
@@ -519,6 +547,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      */
     hydrateTempOrderFromRecord(record: Record<string, any>, options?: {
         recalcOnHydrate?: boolean;
+        source?: 'salesDetail' | 'sessionStorage';
     }): Promise<OrderTempOrder>;
     /**
      * 兼容后端详情将 holder 放在 metadata.holder 的历史形态，统一补到运行时展示路径。
@@ -533,6 +562,8 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
      */
     private seedAnonymousBookingUidsFromProducts;
     private normalizeTempOrderForRuntime;
+    private isSyntheticDraftOrderIdForRuntime;
+    private withoutSyntheticDraftOrderIdForRuntime;
     private hydrateLinkedBookingIdentity;
     private pickHydratedDisplayText;
     private formatHydratedNamePair;