@pisell/pisellos 2.3.74 → 2.3.76

package/lib/solution/BookingTicket/utils/resolveBestAddTimePlan.js

@@ -1,39 +1,173 @@
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+"use strict";
 
-// src/solution/BookingTicket/utils/resolveBestAddTimePlan.ts
-var resolveBestAddTimePlan_exports = {};
-__export(resolveBestAddTimePlan_exports, {
-  ADD_TIME_UNIT_MINUTES: () => ADD_TIME_UNIT_MINUTES,
-  buildAddTimeCandidates: () => buildAddTimeCandidates,
-  resolveBestAddTimePlan: () => resolveBestAddTimePlan
+Object.defineProperty(exports, "__esModule", {
+  value: true
 });
-module.exports = __toCommonJS(resolveBestAddTimePlan_exports);
-var ADD_TIME_UNIT_MINUTES = [10, 15, 20, 30, 45, 60];
-var toPositiveNumber = (value) => {
+exports.ADD_TIME_UNIT_MINUTES = void 0;
+exports.buildAddTimeCandidates = buildAddTimeCandidates;
+exports.resolveBestAddTimePlan = resolveBestAddTimePlan;
+/**
+ * 计算指定加时时长下的最优购买方案。
+ *
+ * 输入的商品结构来自旧版 booking addTimeModal 的加时商品配置映射：
+ * - `minMinutes`：该商品第一次可选择的最小时长。
+ * - `maxMinutes`：单次购买该商品可覆盖的最大时长。
+ * - `unitMinutes`：超过最小时长后，每次递增的时长切片。
+ * - `price`：每个 `unitMinutes` 切片的价格。
+ * - `unlimited`：固定价格商品，可覆盖任意目标时长。
+ *
+ * 算法流程：
+ *
+ * ```
+ * products
+ *   |
+ *   v
+ * 将每个普通商品展开成有限候选档位
+ *   商品 A: min=30, max=60, unit=10, price=10
+ *   => 30m/$30, 40m/$40, 50m/$50, 60m/$60
+ *   |
+ *   v
+ * 单独加入 unlimited 候选
+ *   unlimited 商品 => targetMinutes / 固定商品价格
+ *   |
+ *   v
+ * 按 covered minutes 做动态规划
+ *   dp[minutes] = 正好覆盖 `minutes` 时的最低价候选组合
+ *   |
+ *   v
+ * 从所有 dp[minutes >= targetMinutes] 中挑选最优方案
+ * ```
+ *
+ * 候选档位生成刻意对齐旧版 addTimeModal：
+ * `totalPrice = minutes / unitMinutes * price`.
+ * 例如 `minMinutes=30`、`unitMinutes=10`、`price=10` 时：
+ * - 30 分钟 => 30 / 10 * 10 = 30
+ * - 60 分钟 => 60 / 10 * 10 = 60
+ *
+ * 目标时长不要求精确命中某个档位，只需要覆盖即可。例如目标是 51 分钟时，
+ * 60 分钟档位可以作为候选。动态规划也允许跨商品组合，例如商品 A 的 30m
+ * 加上商品 B 的 30m。最终方案按以下优先级比较：
+ * 1. 总价更低；
+ * 2. 超出时长更少，即 `coveredMinutes - targetMinutes` 更小；
+ * 3. 结果行数更少，让购买方案尽量简单。
+ *
+ * 典型匹配示例：
+ *
+ * 示例 1：精确命中，直接选择更便宜的商品。
+ * ```
+ * target = 30
+ * 商品 A: min=30, max=30, unit=30, price=10 => 30m/$10
+ * 商品 B: min=30, max=30, unit=30, price=8  => 30m/$8
+ * 结果：选择商品 B，coveredMinutes=30，totalPrice=8
+ * ```
+ *
+ * 示例 2：目标时长落在两个档位之间，向上选择可覆盖的档位。
+ * ```
+ * target = 51
+ * 商品 A: min=30, max=120, unit=10, price=10
+ * 候选：30m/$30, 40m/$40, 50m/$50, 60m/$60 ...
+ * 结果：50m 不足以覆盖 51m，因此选择 60m/$60
+ * ```
+ *
+ * 示例 3：不同商品都能覆盖同一目标时长，比较最终价格。
+ * ```
+ * target = 51
+ * 商品 A: min=30, max=120, unit=10, price=10 => 60m/$60
+ * 商品 B: min=30, max=120, unit=30, price=25 => 60m/$50
+ * 结果：两个方案都覆盖 60m，但商品 B 更便宜，所以选择商品 B
+ * ```
+ *
+ * 示例 4：允许跨商品组合，组合价更低时会选择组合。
+ * ```
+ * target = 90
+ * 商品 A: min=30, max=30, unit=30, price=5  => 30m/$5
+ * 商品 B: min=60, max=60, unit=60, price=8  => 60m/$8
+ * 商品 C: min=90, max=90, unit=90, price=20 => 90m/$20
+ * 结果：商品 A + 商品 B = 90m/$13，比商品 C 更便宜
+ * ```
+ *
+ * 示例 5：允许重复购买同一个候选档位。
+ * ```
+ * target = 90
+ * 商品 A: min=30, max=30, unit=30, price=5 => 30m/$5
+ * 结果：购买 3 份商品 A，coveredMinutes=90，totalPrice=15，
+ * lines 中会合并为一行：product_add_schedule_time=30，num=3
+ * ```
+ *
+ * 示例 6：unlimited 可以覆盖任意目标时长，并参与价格比较。
+ * ```
+ * target = 180
+ * 商品 A: min=30, max=120, unit=30, price=10
+ * 商品 B: unlimited=true, price=35
+ * 普通商品可以组合成 180m，例如 120m + 60m，总价 $60
+ * unlimited 商品固定 $35
+ * 结果：选择 unlimited 商品，coveredMinutes=180，totalPrice=35
+ * ```
+ *
+ * 示例 7：unlimited 不一定优先，普通商品更便宜时选择普通商品。
+ * ```
+ * target = 60
+ * 商品 A: min=30, max=60, unit=30, price=10 => 60m/$20
+ * 商品 B: unlimited=true, price=50
+ * 结果：选择商品 A 的 60m 档位
+ * ```
+ *
+ * 示例 8：价格相同，优先选择超出时长更少的方案。
+ * ```
+ * target = 51
+ * 商品 A: 60m/$20
+ * 商品 B: 90m/$20
+ * 结果：选择 60m，因为 overage=9，小于 90m 的 overage=39
+ * ```
+ *
+ * 示例 9：价格和覆盖时长都相同，优先选择结果行数更少的方案。
+ * ```
+ * target = 60
+ * 商品 A: 60m/$20
+ * 商品 B: 30m/$10
+ * 商品 C: 30m/$10
+ * 结果：商品 A 单行方案和 B+C 两行方案价格、时长相同，选择商品 A
+ * ```
+ *
+ * 示例 10：没有任何有效商品时返回 `NO_PRODUCTS`。
+ * ```
+ * target = 30
+ * products = []
+ * 结果：available=false，unavailableReason='NO_PRODUCTS'
+ * ```
+ *
+ * 示例 11：有商品但没有可用候选时返回 `NO_COVERAGE`。
+ * ```
+ * target = 30
+ * 商品 A: price=0，或 minMinutes 缺失/无效
+ * 结果：available=false，unavailableReason='NO_COVERAGE'
+ * ```
+ *
+ * 示例 12：目标时长小于等于 0 时无需购买。
+ * ```
+ * target = 0
+ * 结果：available=true，coveredMinutes=0，totalPrice=0，lines=[]
+ * ```
+ *
+ * 搜索边界：
+ * 有限档位只需要搜索到 `targetMinutes + maxFiniteCandidateMinutes`。
+ * 这里的 `maxFiniteCandidateMinutes` 是所有普通候选档位里的最大时长。
+ * 例如目标是 51 分钟，最大普通档位是 120 分钟，则只搜索到 171 分钟。
+ * 如果某个组合覆盖了 180 分钟，那么移除其中任意一个普通档位后，剩余时长
+ * 仍然有机会覆盖 51 分钟，而且价格一定不会更高，所以 180 分钟这个组合不
+ * 可能是最优解。
+ */
+
+const ADD_TIME_UNIT_MINUTES = exports.ADD_TIME_UNIT_MINUTES = [10, 15, 20, 30, 45, 60];
+const toPositiveNumber = value => {
   const n = Number(value);
   return Number.isFinite(n) && n > 0 ? n : null;
 };
-var normalizeTargetMinutes = (minutes) => {
+const normalizeTargetMinutes = minutes => {
   const n = Number(minutes);
   return Number.isFinite(n) ? Math.max(0, Math.ceil(n)) : 0;
 };
-var gcd = (a, b) => {
+const gcd = (a, b) => {
   let x = Math.abs(a);
   let y = Math.abs(b);
   while (y !== 0) {
@@ -43,26 +177,28 @@ var gcd = (a, b) => {
   }
   return x;
 };
-var getDpStepMinutes = (candidates) => {
-  return candidates.reduce(
-    (current, candidate) => gcd(current, candidate.product_add_schedule_time),
-    0
-  ) || 1;
+const getDpStepMinutes = candidates => {
+  return candidates.reduce((current, candidate) => gcd(current, candidate.product_add_schedule_time), 0) || 1;
 };
-var comparePlans = (left, right) => {
-  if (!left)
-    return right;
+const comparePlans = (left, right) => {
+  if (!left) return right;
+
+  // 第一优先级：总价更低。例：同样覆盖 60 分钟，$50 优先于 $60。
   if (right.totalPrice !== left.totalPrice) {
     return right.totalPrice < left.totalPrice ? right : left;
   }
+
+  // 第二优先级：价格相同时，选择超出目标更少的方案。例：target=51 时，60m 优先于 90m。
   const leftOverage = left.coveredMinutes - left.targetMinutes;
   const rightOverage = right.coveredMinutes - right.targetMinutes;
   if (rightOverage !== leftOverage) {
     return rightOverage < leftOverage ? right : left;
   }
+
+  // 第三优先级：价格和超出时长都相同时，选择购买行数更少的方案，减少下单复杂度。
   return right.lines.length < left.lines.length ? right : left;
 };
-var toPlanLine = (candidate) => ({
+const toPlanLine = candidate => ({
   product_id: candidate.product_id,
   product_title: candidate.product_title,
   product_add_schedule_time: Number.isFinite(candidate.product_add_schedule_time) ? candidate.product_add_schedule_time : 0,
@@ -70,10 +206,11 @@ var toPlanLine = (candidate) => ({
   price: candidate.price,
   _originalProduct: candidate._originalProduct
 });
-var mergePlanLines = (candidates) => {
-  const map = /* @__PURE__ */ new Map();
+const mergePlanLines = candidates => {
+  const map = new Map();
   for (const candidate of candidates) {
-    const key = `${candidate.product_id}-${candidate.product_add_schedule_time}-${candidate.unlimited ? "u" : "n"}`;
+    // 同一个商品、同一个档位可以重复购买，合并成 num。例：30m 档买 3 次 => 一行 num=3。
+    const key = `${candidate.product_id}-${candidate.product_add_schedule_time}-${candidate.unlimited ? 'u' : 'n'}`;
     const existing = map.get(key);
     if (existing) {
       existing.num += candidate.num;
@@ -83,17 +220,13 @@ var mergePlanLines = (candidates) => {
   }
   return Array.from(map.values());
 };
-var sumPlanLineMinutes = (lines) => lines.reduce(
-  (total, line) => total + line.product_add_schedule_time * line.num,
-  0
-);
-var restoreDpCandidates = (dp, finiteCandidates, index) => {
+const sumPlanLineMinutes = lines => lines.reduce((total, line) => total + line.product_add_schedule_time * line.num, 0);
+const restoreDpCandidates = (dp, finiteCandidates, index) => {
   const candidates = [];
   let currentIndex = index;
   while (currentIndex > 0) {
     const current = dp[currentIndex];
-    if (!current || current.candidateIndex < 0)
-      break;
+    if (!current || current.candidateIndex < 0) break;
     candidates.push(finiteCandidates[current.candidateIndex]);
     currentIndex = current.prevIndex;
   }
@@ -102,10 +235,11 @@ var restoreDpCandidates = (dp, finiteCandidates, index) => {
 function buildAddTimeCandidates(products) {
   const candidates = [];
   for (const product of products) {
+    // 价格无效的商品无法参与比价，直接跳过，避免生成 0 元或 NaN 候选。
     const price = toPositiveNumber(product.price);
-    if (price == null)
-      continue;
+    if (price == null) continue;
     if (product.unlimited) {
+      // unlimited 是固定价商品，可覆盖任意目标时长；这里先用 Infinity 标记，最终按 targetMinutes 输出。
       candidates.push({
         product_id: product.id,
         product_title: product.title,
@@ -118,12 +252,18 @@ function buildAddTimeCandidates(products) {
       });
       continue;
     }
+
+    // 普通商品必须有有效的起购时长，否则无法知道第一档应该从哪里开始。
     const minMinutes = toPositiveNumber(product.minMinutes);
-    if (minMinutes == null)
-      continue;
+    if (minMinutes == null) continue;
+
+    // 旧版配置中 max/unit 可能缺失：缺失时退化为只有 minMinutes 这一档。
     const maxMinutes = toPositiveNumber(product.maxMinutes) ?? minMinutes;
     const unitMinutes = toPositiveNumber(product.unitMinutes) ?? minMinutes;
+    // 当 maxMinutes 小于 minMinutes 时，至少保留 minMinutes 这一档，避免错误配置导致无候选。
     const safeMax = Math.max(minMinutes, maxMinutes);
+
+    // 将一个商品展开为多个可购买档位。例：min=30,max=60,unit=10 => 30/40/50/60 四个候选。
     for (let minutes = minMinutes; minutes <= safeMax; minutes += unitMinutes) {
       candidates.push({
         product_id: product.id,
@@ -139,8 +279,10 @@ function buildAddTimeCandidates(products) {
   return candidates;
 }
 function resolveBestAddTimePlan(products, targetMinutes) {
+  // 目标时长按分钟向上取整，避免 50.2 分钟被当成 50 分钟而覆盖不足。
   const normalizedTarget = normalizeTargetMinutes(targetMinutes);
   if (normalizedTarget <= 0) {
+    // 目标时长为 0 或负数时表示无需加时，直接返回 0 元可用方案。
     return {
       available: true,
       targetMinutes: 0,
@@ -152,7 +294,7 @@ function resolveBestAddTimePlan(products, targetMinutes) {
   if (!products.length) {
     return {
       available: false,
-      unavailableReason: "NO_PRODUCTS",
+      unavailableReason: 'NO_PRODUCTS',
       targetMinutes: normalizedTarget,
       coveredMinutes: 0,
       totalPrice: 0,
@@ -160,23 +302,19 @@ function resolveBestAddTimePlan(products, targetMinutes) {
     };
   }
   const candidates = buildAddTimeCandidates(products);
-  const finiteCandidates = candidates.filter(
-    (item) => Number.isFinite(item.product_add_schedule_time)
-  );
-  const unlimitedCandidates = candidates.filter((item) => item.unlimited);
-  const maxFiniteMinutes = Math.max(
-    0,
-    ...finiteCandidates.map((item) => item.product_add_schedule_time)
-  );
+  // 普通候选参与 DP 组合；unlimited 单独比较，因为它本身可以覆盖任意时长，不需要组合。
+  const finiteCandidates = candidates.filter(item => Number.isFinite(item.product_add_schedule_time));
+  const unlimitedCandidates = candidates.filter(item => item.unlimited);
+  // 搜索上限只需要多看一个最大档位。超过这个范围的组合，去掉其中一个档位后通常仍可覆盖且更便宜。
+  const maxFiniteMinutes = Math.max(0, ...finiteCandidates.map(item => item.product_add_schedule_time));
   const searchLimit = normalizedTarget + maxFiniteMinutes;
   let best = null;
   for (const unlimited of unlimitedCandidates) {
-    const lines = [
-      toPlanLine({
-        ...unlimited,
-        product_add_schedule_time: normalizedTarget
-      })
-    ];
+    // unlimited 按目标时长输出 lineItem 时长，但价格保持商品固定价，并参与普通方案的统一比价。
+    const lines = [toPlanLine({
+      ...unlimited,
+      product_add_schedule_time: normalizedTarget
+    })];
     best = comparePlans(best, {
       available: true,
       targetMinutes: normalizedTarget,
@@ -189,9 +327,9 @@ function resolveBestAddTimePlan(products, targetMinutes) {
     const stepMinutes = getDpStepMinutes(finiteCandidates);
     const searchLimitIndex = Math.ceil(searchLimit / stepMinutes);
     const targetIndex = Math.ceil(normalizedTarget / stepMinutes);
-    const finiteCandidateSteps = finiteCandidates.map(
-      (candidate) => candidate.product_add_schedule_time / stepMinutes
-    );
+    const finiteCandidateSteps = finiteCandidates.map(candidate => candidate.product_add_schedule_time / stepMinutes);
+
+    // dp[x] 表示“刚好覆盖 x * stepMinutes 分钟”的当前最低价状态；状态只存前驱，最后再回溯生成明细。
     const dp = [];
     dp[0] = {
       price: 0,
@@ -201,16 +339,18 @@ function resolveBestAddTimePlan(products, targetMinutes) {
     };
     for (let index = 0; index <= searchLimitIndex; index += 1) {
       const current = dp[index];
-      if (!current)
-        continue;
+      // 当前压缩状态不可达时跳过。例：只有 30m 档且 step=30 时，dp[1] 才代表 30 分钟。
+      if (!current) continue;
       for (let candidateIndex = 0; candidateIndex < finiteCandidates.length; candidateIndex += 1) {
+        // 尝试在当前组合后再买一个候选档位，形成新的覆盖时长。
         const nextIndex = index + finiteCandidateSteps[candidateIndex];
-        if (nextIndex > searchLimitIndex)
-          continue;
+        if (nextIndex > searchLimitIndex) continue;
         const candidate = finiteCandidates[candidateIndex];
         const nextPrice = current.price + candidate.totalPrice;
         const nextItemCount = current.itemCount + 1;
         const prev = dp[nextIndex];
+
+        // 更新 dp[nextIndex]：价格更低则替换；价格相同则用更少档位，便于后续输出更简单的方案。
         if (!prev || nextPrice < prev.price || nextPrice === prev.price && nextItemCount < prev.itemCount) {
           dp[nextIndex] = {
             price: nextPrice,
@@ -221,13 +361,12 @@ function resolveBestAddTimePlan(products, targetMinutes) {
         }
       }
     }
+
+    // 目标不要求精确命中：从 target 到 searchLimit 的所有可达方案里选最优。
     for (let index = targetIndex; index <= searchLimitIndex; index += 1) {
       const current = dp[index];
-      if (!current)
-        continue;
-      const lines = mergePlanLines(
-        restoreDpCandidates(dp, finiteCandidates, index)
-      );
+      if (!current) continue;
+      const lines = mergePlanLines(restoreDpCandidates(dp, finiteCandidates, index));
       best = comparePlans(best, {
         available: true,
         targetMinutes: normalizedTarget,
@@ -239,16 +378,10 @@ function resolveBestAddTimePlan(products, targetMinutes) {
   }
   return best ?? {
     available: false,
-    unavailableReason: "NO_COVERAGE",
+    unavailableReason: 'NO_COVERAGE',
     targetMinutes: normalizedTarget,
     coveredMinutes: 0,
     totalPrice: 0,
     lines: []
   };
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ADD_TIME_UNIT_MINUTES,
-  buildAddTimeCandidates,
-  resolveBestAddTimePlan
-});
+}