@pisell/pisellos/lib/model/strategy/adapter/promotion/evaluator.d.ts

一个可扩展的前端模块化SDK框架，支持插件系统

import type { StrategyConfig } from '../../type';
import { type PromotionProduct, type PromotionActionDetail, type PromotionEvaluatorInput, type ProductPromotionResult, type ApplicablePromotion, type CartEvaluationResult, type CartWithPricingResult } from './type';
/**
 * Promotion 评估器
 *
 * 用于评估商品适用的促销活动
 * 封装了 StrategyEngine 和 PromotionAdapter 的调用逻辑
 */
export declare class PromotionEvaluator {
    private engine;
    private adapter;
    private strategyConfigs;
    private locale;
    private locales;
    constructor();
    /**
     * 设置策略配置列表
     */
    setStrategyConfigs(strategyConfigs: StrategyConfig[]): void;
    /**
     * 获取策略配置列表
     */
    getStrategyConfigs(): StrategyConfig[];
    /**
     * 添加策略配置
     */
    addStrategyConfig(strategyConfig: StrategyConfig): void;
    /**
     * 设置语言
     */
    setLocale(locale: string): void;
    /**
     * 设置自定义多语言文案
     */
    setLocales(locales: Record<string, Record<string, string>>): void;
    /**
     * 获取多语言文案
     */
    getText(key: string): string;
    /**
     * 获取多语言名称
     */
    getLocalizedName(name: string | Record<string, string>): string;
    /**
     * 评估商品列表
     *
     * 判断每个商品适用哪些促销活动
     * 支持主商品和 bundle 子商品的匹配
     *
     * @param input 评估输入
     * @returns 每个商品的促销评估结果
     */
    evaluateProducts(input: PromotionEvaluatorInput): ProductPromotionResult[];
    /**
     * 评估购物车
     *
     * 返回所有适用的促销及按促销分组的商品
     * 支持 bundle 子商品的数量计算（主商品数量 × 子商品数量）
     *
     * @param input 评估输入
     * @returns 购物车评估结果
     */
    evaluateCart(input: PromotionEvaluatorInput): CartEvaluationResult;
    /**
     * 评估购物车并计算定价
     *
     * 返回处理后的商品数组（包含拆分、finalPrice）和赠品信息
     * - 对于 X_ITEMS_FOR_Y_PRICE：按原价比例均摊价格，优先使用高价商品
     * - 对于 BUY_X_GET_Y_FREE：计算赠品数量和可选赠品列表
     *
     * @param input 评估输入
     * @returns 带定价的购物车评估结果
     */
    evaluateCartWithPricing(input: PromotionEvaluatorInput): CartWithPricingResult;
    /**
     * 获取商品适用的促销列表
     *
     * 简化方法，用于商品卡片展示
     *
     * @param product 商品
     * @param strategyConfigs 策略配置（可选）
     * @returns 适用的促销列表
     */
    getProductPromotions(product: PromotionProduct, strategyConfigs?: StrategyConfig[]): ApplicablePromotion[];
    /**
     * 获取商品的促销标签
     *
     * 用于商品卡片展示
     *
     * @param product 商品
     * @param strategyConfigs 策略配置（可选）
     * @returns 促销标签列表
     */
    getProductPromotionTags(product: PromotionProduct, strategyConfigs?: StrategyConfig[]): Array<{
        text: string;
        type: string;
        strategyId: string;
    }>;
    /**
     * 查找商品适用的策略配置
     *
     * @param product 商品
     * @param strategyConfigs 策略配置列表（可选）
     * @returns 适用的策略配置列表
     */
    findApplicableStrategies(product: PromotionProduct, strategyConfigs?: StrategyConfig[]): StrategyConfig[];
    /**
     * 批量获取商品列表的适用策略信息
     *
     * 用于给商品列表追加策略标签信息
     * 只检查商品 ID 匹配和策略时间范围
     *
     * @param input 评估输入（商品列表）
     * @param matchVariant 是否需要匹配 product_variant_id，默认 true（严格匹配），false 时只匹配 product_id
     * @returns 每个商品的适用策略完整数据
     */
    getProductsApplicableStrategies(input: PromotionEvaluatorInput, matchVariant?: boolean): Array<{
        product: PromotionProduct;
        applicableStrategies: Array<{
            strategyId: string;
            strategyName: string | Record<string, string>;
            strategyMetadata: any;
            actionType: string;
            actionDetail: PromotionActionDetail;
            display?: {
                text: string | Record<string, string>;
                type: string;
            };
            strategyConfig: StrategyConfig;
            /** 满足促销所需的商品数量 */
            requiredQuantity: number;
            /** 可参与此促销的商品列表 */
            eligibleProducts: Array<{
                product_id: number;
                product_variant_id: number;
            }>;
        }>;
        hasApplicableStrategy: boolean;
    }>;
    /**
     * 获取促销所需数量和可参与商品列表
     *
     * @param actionType 促销类型
     * @param actionDetail 促销详情
     * @param config 策略配置
     * @returns { requiredQuantity, eligibleProducts }
     */
    private getPromotionRequirements;
    /**
     * 按优先级排序促销组
     * 优先级从 strategyConfig.actions[0].priority 获取，数值越小优先级越高
     */
    private sortPromotionGroupsByPriority;
    /**
     * 处理 X件Y元 促销
     *
     * 1. 展开商品为单件列表，按价格从高到低排序
     * 2. 计算可凑成的组数
     * 3. 按原价比例均摊价格
     * 4. 拆分商品（部分参与促销、部分原价）
     *
     * 注意：每个商品按 id 独立处理，不会合并不同 id 的商品
     */
    private processXItemsForYPrice;
    /**
     * 处理 买X送Y 促销
     *
     * 计算赠品数量，商品本身价格不变
     * 支持 bundle 子商品的数量计算（主商品数量 × 子商品数量）
     */
    private processBuyXGetYFree;
    /**
     * 获取未参与任何促销的商品
     */
    private getRemainingProducts;
    /**
     * 价格统一保留两位小数
     */
    private formatPrice;
    /**
     * 获取商品唯一标识 key
     * 使用商品的 id 作为唯一标识，不同 id 的商品不会被合并
     */
    private getProductKey;
    /**
     * 生成随机ID
     */
    private generateRandomId;
    /**
     * 商品匹配结果信息
     */
    private getProductMatchInfo;
    /**
     * 检查商品是否在策略的适用范围内
     */
    private isProductInStrategy;
    /**
     * 查找商品匹配规则
     */
    private findProductMatchRule;
    /**
     * 检查商品ID是否匹配配置列表
     */
    private isProductIdMatch;
    /**
     * 检查商品是否匹配配置（兼容旧方法）
     */
    private isProductMatch;
    /**
     * 获取展示配置
     */
    private getDisplayConfig;
}