@pisell/pisellos 0.0.568 → 0.0.570

package/dist/solution/BaseSales/utils/cartPromotion.d.ts

@@ -0,0 +1,287 @@
+import type { OrderProduct } from '../../../modules/Order/types';
+/**
+ * Cart promotion 工具集（OS 内部纯函数）
+ *
+ * 这是 `private-materials/components/booking/hooks/usePromotion.ts` 中促销/赠品
+ * 核心计算（evaluator → 拆分 / 计价 → 赠品差异化 / 未满足提示 / 标签）的 OS 等价实现。
+ *
+ * 与 legacy 的关键差异：
+ * - legacy 操作 booking `_extend.*` 形状；OS 操作 `OrderProduct.metadata.*` 形状。
+ * - 行唯一标识不再用 `_id`，统一改用 `metadata.unique_identification_number`。
+ * - 赠品标签存到 `metadata._giftInfo`；主商品促销信息存到 `metadata._promotion`；
+ *   商品卡列表的促销 tag 存到 `metadata._promotionTags`。
+ *
+ * 仅暴露纯函数，不持有任何状态；评估器以参数注入。
+ *
+ * @example
+ * const evaluator = appHelper.utils.promotionEvaluator;
+ * const result = processCartPromotion(tempOrder.products, evaluator);
+ * // result.products: 处理后的商品（带 _promotion / 拆分）
+ * // result.giftActions: 需要 add / reduce / remove 的赠品操作
+ * // result.unfulfilledPromotions: 未满足策略列表（购物车底部 alert）
+ */
+/** Cart 评估器协议（只描述本文件用到的方法，避免循环依赖） */
+export interface CartPromotionEvaluator {
+    evaluateCartWithPricing(input: {
+        products: any[];
+        channel?: string;
+    }): {
+        products: Array<{
+            id: number;
+            originalId?: number;
+            product_id: number;
+            product_variant_id: number;
+            quantity: number;
+            price: number;
+            finalPrice: number;
+            strategyId?: string;
+            strategyMetadata?: any;
+            inPromotion: boolean;
+            isSplit?: boolean;
+            matchedBundleIndex?: number;
+            bundle?: any[];
+            _originalItem?: any;
+            _originalId?: string;
+            _originalIndex?: number;
+        }>;
+        gifts: Array<{
+            strategyId: string;
+            strategyName: string | Record<string, string>;
+            giftCount: number;
+            giftOptions: Array<{
+                product_id: number;
+                product_variant_id: number;
+            }>;
+        }>;
+        totalDiscount: number;
+    };
+    getProductsApplicableStrategies(input: {
+        products: any[];
+        channel?: string;
+    }, matchVariant?: boolean): Array<{
+        product: any;
+        applicableStrategies: Array<{
+            strategyId: string;
+            strategyName: string | Record<string, string>;
+            strategyMetadata: any;
+            actionType: string;
+            actionDetail: any;
+            display?: {
+                text: string | Record<string, string>;
+                type: string;
+            };
+            requiredQuantity: number;
+            eligibleProducts: Array<{
+                product_id: number;
+                product_variant_id: number;
+            }>;
+        }>;
+        hasApplicableStrategy: boolean;
+    }>;
+}
+/** 单个赠品减量项 */
+export interface GiftReduceItem {
+    /** 赠品行的 `metadata.unique_identification_number` */
+    uid: string;
+    currentQuantity: number;
+    /** 目标数量（>0；==0 走 toRemove） */
+    newQuantity: number;
+}
+/** 赠品新增项 */
+export interface GiftToAddAction {
+    strategyId: string;
+    strategyName: string | Record<string, string>;
+    giftCount: number;
+    giftOptions: Array<{
+        product_id: number;
+        product_variant_id: number;
+    }>;
+    /** 触发此赠品的主商品 uid 列表 */
+    sourceProductIds: string[];
+}
+/** 赠品操作集合（OS 侧根据它落地 tempOrder.products） */
+export interface GiftActions {
+    toAdd: GiftToAddAction[];
+    toReduce: Array<{
+        strategyId: string;
+        items: GiftReduceItem[];
+    }>;
+    /** 需要删除的赠品 uid 列表 */
+    toRemove: string[];
+}
+/** 未满足促销提示项（购物车底部 alert 数据源） */
+export interface UnfulfilledPromotion {
+    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;
+    };
+}
+/** 商品卡促销标签结构（写入 `metadata._promotionTags`） */
+export interface PromotionTag {
+    text: string | Record<string, string>;
+    type: string;
+    strategyId?: string;
+}
+/** processCartPromotion 输出 */
+export interface ProcessCartPromotionResult {
+    /** 处理后的商品列表（含拆分行、_promotion / _giftInfo 元数据） */
+    products: OrderProduct[];
+    totalDiscount: number;
+    gifts: Array<GiftToAddAction>;
+    giftActions: GiftActions;
+    unfulfilledPromotions: UnfulfilledPromotion[];
+}
+/**
+ * 获取商品的「主商品基础价」用于评估器入参。
+ *
+ * 优先级（与 OS v2 schema 一致）：
+ * 1. `metadata.source_product_price`
+ * 2. `metadata.main_product_original_price` 减去 option 合计
+ * 3. `original_price`
+ */
+export declare function getOrderProductBasePrice(product: any): number;
+/**
+ * 促销均摊专用原价（对齐 legacy `getMainOriginalPrice` 语义）。
+ *
+ * 必须用券前原价做 X_ITEMS_FOR_Y_PRICE 比例拆分；`source_product_price` 在上一轮 applyPromotion
+ * 后可能已被写成促销价（如 5 / 9 / 1），若继续用它会导致同商品两行出现 9+1 而非 5+5。
+ *
+ * @example
+ * getOrderProductOriginalPriceForPromotion({ metadata: { source_product_price: '9', main_product_original_price: '5.80' } });
+ * // => 5.8
+ */
+export declare function getOrderProductOriginalPriceForPromotion(product: any): number;
+/**
+ * 合并「同商品 + 同规格指纹 + 同促销策略 + 同促销单价」的参与促销行（num 累加）。
+ * 避免 Browse Items 连续加购同款时拆成多行且单价被错误均摊。
+ *
+ * @example
+ * mergeIdenticalPromotionCartLines(processedProducts);
+ */
+export declare function mergeIdenticalPromotionCartLines(products: any[]): any[];
+/** 获取行 uid（统一以 `metadata.unique_identification_number` 为唯一键） */
+export declare function getOrderProductUid(product: any): string;
+/**
+ * 促销评估前合并同 SKU 拆分行（含促销/原价行），避免加购后仅前 2 件享受优惠。
+ * 带 `booking_uid` 的预约行不参与合并（每次加车独立 booking + 商品行）。
+ *
+ * @example
+ * consolidateMainProductsForPromotion([
+ *   { item: promoLineNum2, originalListIndex: 0 },
+ *   { item: regularLineNum2, originalListIndex: 1 },
+ * ]);
+ * // => 单行 num=4，清除 _promotion 后重新评估
+ */
+export declare function buildConsolidateKeyForPromotion(item: any): string;
+/**
+ * 从策略配置的 product_match 规则提取可参与商品列表。
+ *
+ * @example
+ * extractProductMatchIdentifiersFromStrategyConfig(strategyConfig);
+ * // => [{ product_id: 60736, product_variant_id: 0 }]
+ */
+export declare function extractProductMatchIdentifiersFromStrategyConfig(strategyConfig: any): Array<{
+    product_id: number;
+    product_variant_id: number;
+}>;
+/**
+ * 解析策略凑单所需件数（evaluator 原始返回可能不含 requiredQuantity）。
+ *
+ * @example
+ * resolveStrategyRequiredQuantity({ actionType: 'X_ITEMS_FOR_Y_PRICE', actionDetail: { x: 2 } });
+ */
+export declare function resolveStrategyRequiredQuantity(matched: {
+    requiredQuantity?: number;
+    actionType?: string;
+    actionDetail?: any;
+}): number;
+/**
+ * 解析 Browse Items 弹窗候选商品（优先 eligibleProducts，否则读 strategyConfig）。
+ *
+ * @example
+ * resolveStrategyEligibleProducts(matchedStrategy);
+ */
+export declare function resolveStrategyEligibleProducts(matched: {
+    eligibleProducts?: Array<{
+        product_id: number;
+        product_variant_id: number;
+    }>;
+    strategyConfig?: any;
+}): Array<{
+    product_id: number;
+    product_variant_id: number;
+}>;
+/**
+ * 计算未满足促销条件（用于购物车底部「再买 N 件即可享受 XX」alert）。
+ *
+ * 数据源：商品的 `metadata._promotion.inPromotion === false`（来自 processCartPromotion
+ * 第 8 步追加的「有适用策略但当前未参与促销」标记）。
+ */
+export declare function calculateUnfulfilledPromotions(processedProducts: any[], applicableStrategiesResult: Array<{
+    applicableStrategies: Array<{
+        strategyId: string;
+        strategyName: string | Record<string, string>;
+        strategyMetadata: any;
+        actionType: string;
+        requiredQuantity?: number;
+        eligibleProducts?: Array<{
+            product_id: number;
+            product_variant_id: number;
+        }>;
+        actionDetail?: any;
+        strategyConfig?: any;
+        display?: {
+            text: string | Record<string, string>;
+            type: string;
+        };
+    }>;
+    hasApplicableStrategy: boolean;
+}>, mainProducts: any[]): UnfulfilledPromotion[];
+/**
+ * 给商品列表追加促销标签（写入 `metadata._promotionTags`），供 ProductCard 渲染。
+ *
+ * - 没有适用策略的商品会清除 `_promotionTags`（避免脏数据）。
+ * - 仅基于 product_id 匹配（matchVariant=false），与商品卡通用场景对齐。
+ *
+ * @example
+ * const list = appendPromotionTags(catalog, evaluator);
+ * // list[i].metadata._promotionTags = [{ text, type, strategyId }]
+ */
+export declare function appendPromotionTags<T extends Record<string, any>>(products: T[], evaluator: CartPromotionEvaluator | null | undefined): T[];
+/**
+ * 处理购物车的促销计算与赠品差异化。
+ *
+ * 流程：
+ * 1. 分离 main / gift / edit-product 三类（带 `booking_id` 的编辑态商品不参与促销）
+ * 2. 转 PromotionProduct 喂评估器 → 拿到 `evaluateCartWithPricing` 与 `getProductsApplicableStrategies`
+ * 3. 把 PricedProduct 映射回 OrderProduct 形态：
+ *    - 参与促销的，写 `metadata._promotion` + 调整 `selling_price` / `main_product_selling_price`
+ *    - 拆分的，生成新 uid，复制原行其它字段
+ * 4. 计算 `_giftInfo` 挂主商品（每个策略首个主商品）
+ * 5. 计算 `giftActions`（toAdd / toReduce / toRemove）
+ * 6. 计算 `unfulfilledPromotions`
+ *
+ * @example
+ * const { products, giftActions, unfulfilledPromotions } = processCartPromotion(
+ *   tempOrder.products,
+ *   evaluator,
+ * );
+ */
+export declare function processCartPromotion(list: OrderProduct[] | null | undefined, evaluator: CartPromotionEvaluator | null | undefined, options?: {
+    channel?: string;
+}): ProcessCartPromotionResult;