@pisell/pisellos 2.2.174 → 2.2.176

package/dist/solution/BookingTicket/index.js

@@ -883,6 +883,10 @@ export var BookingTicketImpl = /*#__PURE__*/function (_BaseSalesImpl) {
       var next = this.buildOrderCustomerPayload();
       this.core.effects.emit("".concat(this.name, ":onOrderCustomerChange"), next);
       this.refreshDiscountConfigAfterOrderCustomerChange(patch.customer_id);
+      // 客户切换可能改变可用促销/赠品；触发一次重算（recursion-safe）。
+      void this.store.order.applyPromotion().catch(function (error) {
+        console.error('[BookingTicket] applyPromotion after customer change failed', error);
+      });
     }
 
     /**

package/dist/solution/BookingTicket/utils/cartView.js

@@ -67,8 +67,10 @@ export function buildCartView(lines, bookings) {
     });
   });
   var items = productLines.filter(function (line) {
-    var _line$metadata2;
-    var uid = (_line$metadata2 = line.metadata) === null || _line$metadata2 === void 0 ? void 0 : _line$metadata2.unique_identification_number;
+    var _line$metadata2, _line$metadata3;
+    // 促销赠品行仅通过主商品 Gift 行展示，不在 items 单独占一行（对齐 legacy `isGift: !!_giftInfo`）
+    if ((_line$metadata2 = line.metadata) !== null && _line$metadata2 !== void 0 && _line$metadata2._giftInfo) return false;
+    var uid = (_line$metadata3 = line.metadata) === null || _line$metadata3 === void 0 ? void 0 : _line$metadata3.unique_identification_number;
     if (uid === undefined || uid === null || uid === '') return true;
     return !claimedUids.has(String(uid));
   });

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

@@ -1,49 +0,0 @@
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/model/strategy/adapter/promotion/index.ts
-var promotion_exports = {};
-__export(promotion_exports, {
-  BUY_X_GET_Y_FREE_STRATEGY: () => import_examples.BUY_X_GET_Y_FREE_STRATEGY,
-  PromotionAdapter: () => import_adapter.PromotionAdapter,
-  PromotionEvaluator: () => import_evaluator.PromotionEvaluator,
-  X_ITEMS_FOR_Y_PRICE_STRATEGY: () => import_examples.X_ITEMS_FOR_Y_PRICE_STRATEGY,
-  default: () => import_adapter2.default
-});
-module.exports = __toCommonJS(promotion_exports);
-var import_evaluator = require("./evaluator");
-var import_adapter = require("./adapter");
-var import_adapter2 = __toESM(require("./adapter"));
-var import_examples = require("./examples");
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  BUY_X_GET_Y_FREE_STRATEGY,
-  PromotionAdapter,
-  PromotionEvaluator,
-  X_ITEMS_FOR_Y_PRICE_STRATEGY
-});

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

@@ -3,7 +3,7 @@ import { BaseModule } from '../BaseModule';
 import { OrderModuleAPI, CommitOrderParams, UpdateOrderBookingParams, UpdateOrderProductParams, UpdateOrderProductQuantityParams, CheckoutOrderParams, CancelOrderParams, ChangeBookingStatusParams } 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, OrderScanCodeResult, ReplaceTempOrderOptions } from './types';
+import type { OrderAmountSnapshot, AddProductBookingInput, OrderIdentitySnapshot, OrderPaymentSource, OrderSnapshot, OrderSyncState, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, SubmitSalesOrderParams, OrderProduct, OrderProductIdentity, OrderSummary, OrderTempOrder, OrderPaymentData, SendCustomerPayLinkParams, UpdateTempOrderCustomerInput, OrderCustomerPatch, OrderCustomerView, OrderScanCodeResult, ReplaceTempOrderOptions, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions } from './types';
 import type { ICustomer } from '../AccountList/types';
 import type { Discount } from '../Discount/types';
 export declare class OrderModule extends BaseModule implements Module, OrderModuleAPI {
@@ -19,6 +19,16 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private rulesHooksOverride?;
     private orderHooks?;
     private otherParams?;
+    /** 评估器引用；由 SalesSdkProvider 注入，未注入时 applyPromotion 静默跳过 */
+    private promotionEvaluator;
+    /** 赠品选择 resolver；由 SDK host bridge 注入 */
+    private giftSelectResolver;
+    /** applyPromotion 递归保护 flag（写路径同步调 applyPromotion，禁止重入） */
+    private isApplyingPromotion;
+    /** 最近一次 applyPromotion 的未满足促销提示 */
+    private lastUnfulfilledPromotions;
+    /** 最近一次 applyPromotion 的赠品操作 diff（debug / SDK 读取使用） */
+    private lastGiftActions;
     /**
      * Populate `savedAmount` on each discount based on product-level discount details.
      * Only selected discounts get a non-zero value.
@@ -50,6 +60,46 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     getDiscountList(): Discount[];
     scanCode(code: string, customerId?: number): Promise<OrderScanCodeResult>;
     applyDiscount(): void;
+    /**
+     * 注入促销评估器。
+     *
+     * @example
+     * order.setPromotionEvaluator(appHelper.utils.promotionEvaluator);
+     */
+    setPromotionEvaluator(evaluator: OrderPromotionEvaluator | null): void;
+    /**
+     * 注入赠品选择 resolver。OS 需要补赠品时会 await 调用 resolver；缺省时跳过新增并 console.warn。
+     *
+     * @example
+     * order.setGiftSelectResolver(async (ctx) => {
+     *   // SDK 内部决定弹窗 or 自动选第一项，返回完整 OrderProduct[]
+     *   return giftSelectBridge.request(ctx);
+     * });
+     */
+    setGiftSelectResolver(resolver: OrderGiftSelectResolver | null): void;
+    /**
+     * 为商品目录追加促销标签，供上层 Sales 门面复用。
+     *
+     * @example
+     * const products = order.appendPromotionTags(catalogProducts);
+     */
+    appendPromotionTags<T extends Record<string, any>>(products: T[]): T[];
+    /**
+     * 应用购物车促销：计算 → 差异化赠品 → 写回 tempOrder.products → emit onPromotionApplied。
+     *
+     * 调用时机：写路径（add/update/remove/clear/setCustomer）末尾自动触发；外部一般无需手动调。
+     *
+     * 关键约束：
+     * - 不调用任何公开 CRUD API（如 removeProductFromOrder），全部内部 mutate tempOrder.products，避免事件风暴；
+     * - 用 `isApplyingPromotion` 防递归；
+     * - 多选项赠品依赖 giftSelectResolver，未注入则跳过且 console.warn；
+     * - 不主动调用 applyDiscount / recalculateSummary，调用方负责跟进。
+     */
+    applyPromotion(): Promise<void>;
+    /** 最近一次 applyPromotion 输出的未满足促销列表 */
+    getUnfulfilledPromotions(): OrderUnfulfilledPromotion[];
+    /** 最近一次 applyPromotion 输出的赠品操作 diff */
+    getLastGiftActions(): OrderLastGiftActions | null;
     initTempOrder(params: {
         cacheId?: string;
         salesSummaryModuleName?: string;
@@ -64,6 +114,7 @@ export declare class OrderModule extends BaseModule implements Module, OrderModu
     private createExternalSaleNumber;
     private ensureExternalSaleNumber;
     private ensureRequestUniqueIdempotencyToken;
+    private buildPaymentSyncIdempotencyToken;
     hasLocalDatabase(): boolean;
     private buildLocalOrderRecord;
     getLocalOrderByOrderId(orderId: number | string): Promise<Record<string, any> | null>;

package/lib/modules/Order/index.js

@@ -37,6 +37,7 @@ var import_types = require("./types");
 var import_utils = require("./utils");
 var import_utils2 = require("../Product/utils");
 var import_dayjs = __toESM(require("dayjs"));
+var import_cartPromotion = require("../../solution/BaseSales/utils/cartPromotion");
 var import_utils3 = require("../../solution/ScanOrder/utils");
 var import_manualProductDiscount = require("./utils/manualProductDiscount");
 var import_Discount = require("../Discount");
@@ -50,6 +51,17 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     super(name || "order", version);
     this.defaultName = "order";
     this.defaultVersion = "1.0.0";
+    // ─── 促销/赠品 ────────────────────────────────────
+    /** 评估器引用；由 SalesSdkProvider 注入，未注入时 applyPromotion 静默跳过 */
+    this.promotionEvaluator = null;
+    /** 赠品选择 resolver；由 SDK host bridge 注入 */
+    this.giftSelectResolver = null;
+    /** applyPromotion 递归保护 flag（写路径同步调 applyPromotion，禁止重入） */
+    this.isApplyingPromotion = false;
+    /** 最近一次 applyPromotion 的未满足促销提示 */
+    this.lastUnfulfilledPromotions = [];
+    /** 最近一次 applyPromotion 的赠品操作 diff（debug / SDK 读取使用） */
+    this.lastGiftActions = null;
   }
   /**
    * Populate `savedAmount` on each discount based on product-level discount details.
@@ -81,10 +93,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       var _a, _b, _c;
       if ((_a = product.metadata) == null ? void 0 : _a.is_manual_discount)
         return product;
-      const totalPerUnitDiscount = (product.discount_list || []).reduce(
-        (sum, discount) => sum + Number(discount.amount || 0),
-        0
-      );
+      const totalPerUnitDiscount = (0, import_utils.resolveEffectivePerUnitDiscount)(product);
       const optionSum = (0, import_utils.sumOptionUnitPrice)(product.product_option_item);
       const sourcePrice = ((_b = product.metadata) == null ? void 0 : _b.source_product_price) ?? (((_c = product.metadata) == null ? void 0 : _c.main_product_original_price) != null ? new import_decimal.default(Number(product.metadata.main_product_original_price) || 0).minus(optionSum).toFixed(2) : product.original_price ?? "0");
       const newSourceSellingPrice = new import_decimal.default(Number(sourcePrice) || 0).minus(totalPerUnitDiscount).toDecimalPlaces(2).toString();
@@ -317,6 +326,160 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       (_e = this.store.discount) == null ? void 0 : _e.setDiscountList(result.discountList);
     }
   }
+  // ─── 促销/赠品 ──────────────────────────────────────
+  /**
+   * 注入促销评估器。
+   *
+   * @example
+   * order.setPromotionEvaluator(appHelper.utils.promotionEvaluator);
+   */
+  setPromotionEvaluator(evaluator) {
+    this.promotionEvaluator = evaluator || null;
+  }
+  /**
+   * 注入赠品选择 resolver。OS 需要补赠品时会 await 调用 resolver；缺省时跳过新增并 console.warn。
+   *
+   * @example
+   * order.setGiftSelectResolver(async (ctx) => {
+   *   // SDK 内部决定弹窗 or 自动选第一项，返回完整 OrderProduct[]
+   *   return giftSelectBridge.request(ctx);
+   * });
+   */
+  setGiftSelectResolver(resolver) {
+    this.giftSelectResolver = resolver || null;
+  }
+  /**
+   * 为商品目录追加促销标签，供上层 Sales 门面复用。
+   *
+   * @example
+   * const products = order.appendPromotionTags(catalogProducts);
+   */
+  appendPromotionTags(products) {
+    return (0, import_cartPromotion.appendPromotionTags)(products, this.promotionEvaluator);
+  }
+  /**
+   * 应用购物车促销：计算 → 差异化赠品 → 写回 tempOrder.products → emit onPromotionApplied。
+   *
+   * 调用时机：写路径（add/update/remove/clear/setCustomer）末尾自动触发；外部一般无需手动调。
+   *
+   * 关键约束：
+   * - 不调用任何公开 CRUD API（如 removeProductFromOrder），全部内部 mutate tempOrder.products，避免事件风暴；
+   * - 用 `isApplyingPromotion` 防递归；
+   * - 多选项赠品依赖 giftSelectResolver，未注入则跳过且 console.warn；
+   * - 不主动调用 applyDiscount / recalculateSummary，调用方负责跟进。
+   */
+  async applyPromotion() {
+    if (this.isApplyingPromotion)
+      return;
+    if (!this.promotionEvaluator)
+      return;
+    const tempOrder = this.store.tempOrder;
+    if (!tempOrder)
+      return;
+    this.isApplyingPromotion = true;
+    try {
+      const result = (0, import_cartPromotion.processCartPromotion)(
+        tempOrder.products,
+        this.promotionEvaluator
+      );
+      if (result.giftActions.toRemove.length > 0) {
+        const removeSet = new Set(result.giftActions.toRemove.map(String));
+        result.products = result.products.filter((p) => {
+          const uid = (0, import_cartPromotion.getOrderProductUid)(p);
+          return uid ? !removeSet.has(String(uid)) : true;
+        });
+      }
+      for (const reduce of result.giftActions.toReduce) {
+        for (const item of reduce.items) {
+          const product = result.products.find(
+            (p) => (0, import_cartPromotion.getOrderProductUid)(p) === item.uid
+          );
+          if (product) {
+            product.num = item.newQuantity;
+          }
+        }
+      }
+      if (result.giftActions.toAdd.length > 0) {
+        if (!this.giftSelectResolver) {
+          if (result.giftActions.toAdd.some((g) => g.giftOptions.length > 1)) {
+            console.warn(
+              "[OrderModule] giftSelectResolver not set, skip applying gifts",
+              result.giftActions.toAdd
+            );
+          } else {
+            console.warn(
+              "[OrderModule] giftSelectResolver not set, skip applying single-option gifts",
+              result.giftActions.toAdd
+            );
+          }
+        } else {
+          for (const addAction of result.giftActions.toAdd) {
+            if (addAction.giftOptions.length === 1) {
+              const sameStrategy = result.products.find(
+                (p) => {
+                  var _a, _b;
+                  return ((_b = (_a = p.metadata) == null ? void 0 : _a._giftInfo) == null ? void 0 : _b.strategyId) === addAction.strategyId;
+                }
+              );
+              if (sameStrategy) {
+                sameStrategy.num = (Number(sameStrategy.num) || 0) + (addAction.giftCount || 1);
+                continue;
+              }
+            }
+            try {
+              const giftProducts = await this.giftSelectResolver({
+                strategyId: addAction.strategyId,
+                strategyName: addAction.strategyName,
+                giftCount: addAction.giftCount,
+                giftOptions: addAction.giftOptions,
+                sourceProductIds: addAction.sourceProductIds
+              });
+              if (Array.isArray(giftProducts) && giftProducts.length > 0) {
+                for (const gp of giftProducts) {
+                  if (!gp)
+                    continue;
+                  result.products.push(gp);
+                }
+              }
+            } catch (error) {
+              console.warn(
+                "[OrderModule] giftSelectResolver rejected, skip add gift",
+                addAction.strategyId,
+                error
+              );
+            }
+          }
+        }
+      }
+      tempOrder.products = result.products;
+      this.lastUnfulfilledPromotions = result.unfulfilledPromotions;
+      this.lastGiftActions = result.giftActions;
+      const payload = {
+        unfulfilledPromotions: result.unfulfilledPromotions,
+        giftActions: result.giftActions,
+        gifts: result.gifts.map((g) => ({
+          strategyId: g.strategyId,
+          strategyName: g.strategyName,
+          giftCount: g.giftCount,
+          giftOptions: g.giftOptions
+        })),
+        products: tempOrder.products
+      };
+      this.effectsEmit("onPromotionApplied", payload);
+    } catch (error) {
+      console.error("[OrderModule] applyPromotion failed", error);
+    } finally {
+      this.isApplyingPromotion = false;
+    }
+  }
+  /** 最近一次 applyPromotion 输出的未满足促销列表 */
+  getUnfulfilledPromotions() {
+    return this.lastUnfulfilledPromotions;
+  }
+  /** 最近一次 applyPromotion 输出的赠品操作 diff */
+  getLastGiftActions() {
+    return this.lastGiftActions;
+  }
   // ─── TempOrder: 初始化入口 ───
   initTempOrder(params) {
     if (params.cacheId !== void 0)
@@ -376,6 +539,14 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     }
     return tempOrder.request_unique_idempotency_token;
   }
+  buildPaymentSyncIdempotencyToken(tempOrder, payments) {
+    const baseToken = this.ensureRequestUniqueIdempotencyToken(tempOrder);
+    const paidPaymentsCount = (payments || []).filter((payment) => {
+      return String((payment == null ? void 0 : payment.status) || "").toLowerCase() === "paid";
+    }).length;
+    const paidCount = paidPaymentsCount > 0 ? paidPaymentsCount : payments.length;
+    return `${baseToken}_payment_${paidCount}`;
+  }
   hasLocalDatabase() {
     return !!this.dbManager;
   }
@@ -1207,6 +1378,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     if (linked) {
       tempOrder.bookings = [...tempOrder.bookings || [], linked.booking];
     }
+    await this.applyPromotion();
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
     this.persistTempOrder();
@@ -1337,6 +1509,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       tempOrder.products[productIndex],
       (_g = tempOrder.products[productIndex].metadata) == null ? void 0 : _g.unique_identification_number
     );
+    await this.applyPromotion();
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
     this.persistTempOrder();
@@ -1399,6 +1572,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       normalizedProduct.discount_list
     );
     tempOrder.products[productIndex] = normalizedProduct;
+    await this.applyPromotion();
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
     this.persistTempOrder();
@@ -1443,6 +1617,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     for (const product of removedProducts) {
       this.removeLinkedBookingsForProduct(tempOrder, product);
     }
+    await this.applyPromotion();
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
     this.persistTempOrder();
@@ -1462,6 +1637,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
         productsByUid: {}
       };
     }
+    await this.applyPromotion();
     this.applyDiscount();
     await this.recalculateSummary({ createIfMissing: true });
     this.persistTempOrder();
@@ -1493,7 +1669,8 @@ var OrderModule = class extends import_BaseModule.BaseModule {
         ...hasPaymentStatusOverride ? { payment_status: params == null ? void 0 : params.paymentStatus } : {},
         ...hasSmallTicketDataFlagOverride ? { small_ticket_data_flag: params == null ? void 0 : params.smallTicketDataFlag } : {}
       };
-      return (params == null ? void 0 : params.enhancePayload) ? params.enhancePayload(nextPayload, ctx) : nextPayload;
+      const enhancedPayload = (params == null ? void 0 : params.enhancePayload) ? params.enhancePayload(nextPayload, ctx) : nextPayload;
+      return enhancedPayload;
     } : void 0;
     const payload = (0, import_utils.buildSubmitPayload)({
       tempOrder,
@@ -1510,6 +1687,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       this.logInfo("submitTempOrder calling sales checkout", {
         orderId: payload.order_id,
         externalSaleNumber: payload.external_sale_number,
+        requestUniqueIdempotencyToken: payload.request_unique_idempotency_token,
         paymentStatus: payload.payment_status,
         paymentsCount: ((_b = payload.payments) == null ? void 0 : _b.length) || 0,
         smallTicketDataFlag: payload.small_ticket_data_flag
@@ -1611,11 +1789,22 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       return { isFullyPaid };
     }
     this.store.syncState = "submitting";
+    const paymentSyncIdempotencyToken = this.buildPaymentSyncIdempotencyToken(
+      tempOrder,
+      mappedPayments
+    );
     const submitResult = await this.submitTempOrder({
       payments: mappedPayments,
       paymentStatus,
       smallTicketDataFlag: params.smallTicketDataFlag,
-      channel: params.channel
+      channel: params.channel,
+      enhancePayload: (payload) => {
+        const nextPayload = {
+          ...payload,
+          request_unique_idempotency_token: paymentSyncIdempotencyToken
+        };
+        return nextPayload;
+      }
     });
     return { isFullyPaid, submitResult };
   }

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

@@ -13,7 +13,106 @@ export declare enum OrderHooks {
     OnOrderUpdate = "order:onOrderUpdate",
     OnOrderCancel = "order:onOrderCancel",
     OnOrderStatusChange = "order:onOrderStatusChange",
-    OnOrderCustomerChange = "order:onOrderCustomerChange"
+    OnOrderCustomerChange = "order:onOrderCustomerChange",
+    OnPromotionApplied = "order:onPromotionApplied"
+}
+/**
+ * 促销评估器协议（OS 与 PromotionEvaluator 之间的桥接接口）。
+ *
+ * 与 `pisell_os/src/model/strategy/adapter/promotion/evaluator.ts` 中的
+ * `PromotionEvaluator` 实例结构保持兼容。SalesSdkProvider 会从 `appHelper.utils.promotionEvaluator`
+ * 读取实例并通过 `setPromotionEvaluator` 注入到 OrderModule。
+ *
+ * 这里只声明 OrderModule 需要调用的子集，避免反向依赖具体 evaluator 实现。
+ */
+export interface OrderPromotionEvaluator {
+    evaluateCartWithPricing(input: {
+        products: any[];
+        channel?: string;
+    }): any;
+    getProductsApplicableStrategies(input: {
+        products: any[];
+        channel?: string;
+    }, matchVariant?: boolean): any[];
+}
+/** 赠品解析回调 context（OS → SDK 的请求体） */
+export interface OrderGiftSelectContext {
+    strategyId: string;
+    strategyName: string | Record<string, string>;
+    giftCount: number;
+    giftOptions: Array<{
+        product_id: number;
+        product_variant_id: number;
+    }>;
+    /** 触发此赠品的主商品 metadata.unique_identification_number 列表 */
+    sourceProductIds: string[];
+}
+/**
+ * 赠品解析回调签名（SDK → OS 的返回值）。
+ *
+ * - 单选项：SDK 内部自动构造商品，不弹窗
+ * - 多选项：SDK 弹窗等用户确认后构造
+ * - 用户取消：抛错或返回空数组（OS 视为放弃本次添加）
+ *
+ * 返回的 OrderProduct 必须是完整的购物车行（含 metadata._giftInfo 标记），OS 会直接 push 入 tempOrder.products。
+ */
+export type OrderGiftSelectResolver = (ctx: OrderGiftSelectContext) => Promise<Partial<OrderProduct>[] | null>;
+/** 未满足的促销策略（购物车底部 alert 渲染源） */
+export interface OrderUnfulfilledPromotion {
+    strategyId: string;
+    strategyName: string | Record<string, string>;
+    actionType: string;
+    needQuantity: number;
+    currentQuantity: number;
+    requiredQuantity: number;
+    eligibleProducts: Array<{
+        product_id: number;
+        product_variant_id: number;
+    }>;
+    strategyMetadata?: any;
+    display?: {
+        text: string | Record<string, string>;
+        type: string;
+    };
+}
+/** 上一次 applyPromotion 计算出的赠品操作（仅供调试/读取使用） */
+export interface OrderLastGiftActions {
+    toAdd: Array<{
+        strategyId: string;
+        strategyName: string | Record<string, string>;
+        giftCount: number;
+        giftOptions: Array<{
+            product_id: number;
+            product_variant_id: number;
+        }>;
+        sourceProductIds: string[];
+    }>;
+    toReduce: Array<{
+        strategyId: string;
+        items: Array<{
+            uid: string;
+            currentQuantity: number;
+            newQuantity: number;
+        }>;
+    }>;
+    toRemove: string[];
+}
+/** onPromotionApplied 事件 payload */
+export interface OrderPromotionAppliedPayload {
+    unfulfilledPromotions: OrderUnfulfilledPromotion[];
+    giftActions: OrderLastGiftActions;
+    /** evaluator 返回的赠品摘要 */
+    gifts: Array<{
+        strategyId: string;
+        strategyName: string | Record<string, string>;
+        giftCount: number;
+        giftOptions: Array<{
+            product_id: number;
+            product_variant_id: number;
+        }>;
+    }>;
+    /** 处理后的商品列表 */
+    products: OrderProduct[];
 }
 /**
  * tempOrder 上的下单客户协议字段视图。
@@ -561,6 +660,46 @@ export interface OrderModuleAPI {
     }) => Promise<Discount[]>;
     getDiscountList: () => Discount[];
     applyDiscount: () => void;
+    /**
+     * 注入促销评估器。
+     *
+     * SalesSdkProvider 在初始化 bookingTicket 后会自动从 `appHelper.utils.promotionEvaluator`
+     * 读取实例并调用本方法注入。host 透明，业务 UI 不感知。
+     *
+     * @example
+     * order.setPromotionEvaluator(appHelper.utils.promotionEvaluator);
+     */
+    setPromotionEvaluator: (evaluator: OrderPromotionEvaluator | null) => void;
+    /**
+     * 注入赠品选择 resolver。OS 在 applyPromotion 内部当需要新增赠品时会 await 调用 resolver。
+     *
+     * 缺省时 OS 会 `console.warn` 并跳过新增（既有赠品的 reduce/remove 仍会执行）。
+     *
+     * @example
+     * order.setGiftSelectResolver((ctx) => giftSelectBridge.request(ctx));
+     */
+    setGiftSelectResolver: (resolver: OrderGiftSelectResolver | null) => void;
+    /**
+     * 为商品目录追加促销标签。
+     *
+     * @example
+     * const taggedProducts = order.appendPromotionTags(products);
+     */
+    appendPromotionTags: <T extends Record<string, any>>(products: T[]) => T[];
+    /**
+     * 应用购物车促销（评估 → 差异化赠品 → 写回 tempOrder.products → emit onPromotionApplied）。
+     *
+     * 自动在 addProductToOrder / updateOrderProductQuantity / removeProductFromOrder /
+     * clearOrderCartLines / setOrderCustomer 等写路径末尾触发，业务一般无需手动调用。
+     *
+     * 多选项赠品依赖 giftSelectResolver；如未注入则跳过且 console.warn。
+     * 内部以 `_isApplyingPromotion` flag 防递归。
+     */
+    applyPromotion: () => Promise<void>;
+    /** 读取上次 applyPromotion 产出的未满足促销提示 */
+    getUnfulfilledPromotions: () => OrderUnfulfilledPromotion[];
+    /** 读取上次 applyPromotion 产出的赠品操作 diff（toAdd / toReduce / toRemove） */
+    getLastGiftActions: () => OrderLastGiftActions | null;
     /**
    * 取消订单
    * @param params 取消订单参数

package/lib/modules/Order/types.js

@@ -28,6 +28,7 @@ var OrderHooks = /* @__PURE__ */ ((OrderHooks2) => {
   OrderHooks2["OnOrderCancel"] = "order:onOrderCancel";
   OrderHooks2["OnOrderStatusChange"] = "order:onOrderStatusChange";
   OrderHooks2["OnOrderCustomerChange"] = "order:onOrderCustomerChange";
+  OrderHooks2["OnPromotionApplied"] = "order:onPromotionApplied";
   return OrderHooks2;
 })(OrderHooks || {});
 // Annotate the CommonJS export names for ESM import in node:

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

@@ -85,6 +85,17 @@ export declare function resolveManualOverrideLineOriginalPrice(params: {
     /** 已有行级 original_price（origin 被裁剪时兜底划线价） */
     lineOriginalPrice?: string | number | null;
 }, fallbackCompositeOriginal: string): string;
+/**
+ * 计算商品行「每单位有效折扣」：discount_list 合计 + 被 Rules 剥离但仍 inPromotion 的差额。
+ *
+ * Rules.calcDiscount 会把 type=promotion 从 discount_list 去掉，但 metadata._promotion 仍保留；
+ * applyProductDiscountPrices 必须回读 _promotion，否则抬价/降价都会在第二步被 source 原价覆盖。
+ *
+ * @example
+ * resolveEffectivePerUnitDiscount({ metadata: { _promotion: { inPromotion: true, originalPrice: 1, finalPrice: 5 } }, discount_list: [] });
+ * // => -4
+ */
+export declare function resolveEffectivePerUnitDiscount(product: Record<string, any>): number;
 export declare function createDefaultOrderRulesHooks(): RulesParamsHooks;
 /**
  * 通过 session 类商品的开始时间结束时间生成商品的时长