開始使用

TIP

建議使用 Web Worker 運行此模組，以免運算卡住主頁面，導致體驗不佳。

安裝

1. 在根目錄建立 .npmrc

2. 加入以下資訊

   @inner-products:registry=https://gitlab.com/api/v4/projects/43695886/packages/npm/
   //gitlab.com/api/v4/projects/43695886/packages/npm/:_authToken=glpat-zAptxfst6rJSwMEUYLzV

3. 安裝套件

   npm i @inner-products/bgm-promotion-module

如何使用

簡易使用順序為：

1. 準備商品與預期可用優惠資料

2. 呼叫 getPromotionsRanking 取得最佳優惠結果前 3 名

預設取得前 3 名，可以指定名次。

import { 
  getPromotionsRanking, checkPromotionResult, Item, Promotion
} from '@inner-products/bgm-promotion-module';

/** 購物車商品 */
const items: Item[] = [];
/** 可用優惠 */
const promotions: Promotion[] = [];

const rankedResults = getPromotionsRanking({ items, promotions });
// 限制數量
const rankedResultsTop2 = getPromotionsRanking({ 
  items, promotions, topN: 2,
});

// 設定 autoOffsetMode 可以讓贈品自動抵銷商品
const offsetResults = getPromotionsRanking({ 
  items,
  promotions,         
  autoOffsetMode: 'multiple-types-from-highest',
});

// 預設會保證相同輸入會有相同輸出，若希望結果不太一樣，可以將 reproducibility 設為 false
// 不建議這麼做就是惹。(○´･д･)ﾉ
const irreproducibilityResults = getPromotionsRanking({ 
  items,
  promotions,
  reproducibility: false,
});

// 可以使用 checkPromotionResult 檢查優惠結果
rankedResults.forEach((result) => {
  const errorMessage = checkPromotionResult(result);
});

💡 自動抵銷模式

細節請見文件

優惠結果為：

/** 優惠結果 */
export interface PromotionResult<Data = undefined> {
  /** 原始購物清單 */
  originalItems: Item<Data>[];
  /** 剩餘的商品。沒有商品優惠可用，剩下來的商品 */
  remainingItems: Item<Data>[];
  /** 套用優惠的商品 */
  promotedList: PromotedListItem<Data>[];
  /** 可用贈品。 */
  giveawayList: GiveawayListItem<Data>[];
  /** 被贈品抵銷的商品。此區商品要被視為 0 元 */
  offsetList: OffsetListItem<Data>[];
  /** 所有已使用的優惠，彙整自 promotedList.promotion */
  usedPromotions: Promotion[];
}

/** 已套用優惠結果的商品 */
export interface PromotedListItem<Data = undefined> {
  /** 符合條件之商品與優惠結果 */
  appliedList: {
    item: Item<Data>;
    /** 優惠結果 */
    result?: SelectableGiveaway<Data> | Arithmetic;
  }[];
  /** 原始優惠 */
  promotion: Promotion;
  /** 套用的優惠內容 */
  promotedContent: Promotion['contents'][number];
}

/** 可用贈品。
 * 
 * 集結 promotedList.appliedList.result 中的 SelectableGiveaway 資料。
 * 
 * 不包含以自動抵銷的贈品，自動抵銷的贈品在 offsetList 中。
 */
export interface GiveawayListItem<Data = undefined> {
  /** 贈品 */
  item: SelectableGiveaway<Data>;
  /** 原始優惠 */
  promotion: Promotion;
  /** 套用的優惠內容 */
  promotedContent: Promotion['contents'][number];
}
/** 被贈品抵銷的商品 */
export interface OffsetListItem<Data = undefined> {
  /** 商品 */
  item: Item<Data>;
  /** 原始優惠 */
  promotion: Promotion;
  /** 套用的優惠內容 */
  promotedContent: Promotion['contents'][number];
}

/** 已排名後的優惠結果 */
export interface RankedPromotionResult<Data> extends PromotionResult<Data> {
  /** 統計資料 */
  analyticalData: AnalyticalData;
}

3. 內容解析

以下功能可以進行結果解析

getAnalyticalData：計算優惠結果金額

💡 排名結果已有此資料

RankedPromotionResult 內已包含 analyticalData，不用再次進行計算

import { 
  getAnalyticalData, PromotionResult,
} from '@inner-products/bgm-promotion-module';

/** 優惠結果 */
const promotionResult: PromotionResult = {};

const analyticalData = getAnalyticalData(promotionResult);

analyticalData 結果為：

export interface AnalyticalData {
  /** 原始總價 */
  originalTotalPrice: number;
  /** 滿額累積，用於判斷滿額優惠是否可用
   * 
   * 去除不計入滿額贈優惠後的金額總和
   */
  spendTotalPrice: number;
  /** 商品總價。包含剩餘商品和商品優惠（commodity-offer） */
  commodityTotalPrice: number;
  /** commodityTotalPrice 加入訂單優惠（order-offer）後的價格 */
  orderTotalPrice: number;
  /** 包含全部優惠（commodity-offer、order-offer、minimum-spend-offer）總價 */
  totalPrice: number;
}

getItemizedResult：取得每個商品帶入優惠後的價格

❌ 尚未實作

getItemizedResult 功能尚未實作，目前只有定義型別

import { 
  getItemizedResult, PromotionResult,
} from '@inner-products/bgm-promotion-module';

const promotionResult: PromotionResult = {};

const result = getItemizedResult(promotionResult);

result 結果為：

export interface ItemizedResult<Data = undefined> {
  list: {
    item: Item<Data>;
    /** 優惠後的商品單價 */
    promotedPrice: number;
    /** 優惠來源 */
    sources: {
      promotion: Promotion;
      promotedContent: Promotion['contents'][number];
    }[];
  }[];
}

4. 檢查結果有效性

檢查結果是否有效，可用來確認資料是否被竄改

checkParamsAndRankedResult：檢查優惠結果重現性

檢查優惠結果是否與指定參數結果一致。

import { 
  getPromotionsRanking, checkParamsAndRankedResult,
} from '@inner-products/bgm-promotion-module';

/** 購物車商品 */
const items: Item[] = [];
/** 可用優惠 */
const promotions: Promotion[] = [];

const rankedResults = getPromotionsRanking({ items, promotions });

// 結果是否相同
const isSame = checkParamsAndRankedResult({
  items, promotions, results: rankedResults,
});