@pisell/utils 3.0.5 → 3.0.7

package/es/walletValidity.js

@@ -1,3 +1,15 @@
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(obj, key, value) { key = _toPropertyKey(key); if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : String(i); }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+function _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) arr2[i] = arr[i]; return arr2; }
 import dayjs from 'dayjs';
 
 // 文案配置类型定义
@@ -6,12 +18,35 @@ import dayjs from 'dayjs';
 var CONSTANTS = {
   ALL_DAY_START: '00:00',
   ALL_DAY_END: '23:59',
-  DEFAULT_FUTURE_YEARS: 10,
   SECONDS_SUFFIX: ':59'
 };
 
 // 日程项接口定义
 
+// API 日期使用店铺的日历日期；不要把已格式化的 DD/MM/YYYY 文案重新解析为日期。
+function getValidityDate(value) {
+  if (typeof value !== 'string') return null;
+  var match = value.match(/^(\d{4}-\d{2}-\d{2})(?:$|[ T])/);
+  if (!match) return null;
+  var date = dayjs(match[1]);
+  return date.isValid() && date.format('YYYY-MM-DD') === match[1] ? match[1] : null;
+}
+
+/** 仅计算展示日期的交集，不修改日程的重复起点或每日使用时段。 */
+export function getWalletValidityRange(start, end, validity) {
+  var scheduleStart = getValidityDate(start);
+  var scheduleEnd = getValidityDate(end);
+  var passStart = getValidityDate(validity === null || validity === void 0 ? void 0 : validity.start_date);
+  var passEnd = getValidityDate(validity === null || validity === void 0 ? void 0 : validity.expire_date) || getValidityDate(validity === null || validity === void 0 ? void 0 : validity.expire_time);
+  var startDate = passStart && (!scheduleStart || passStart > scheduleStart) ? passStart : scheduleStart;
+  var endDate = passEnd && (!scheduleEnd || passEnd < scheduleEnd) ? passEnd : scheduleEnd;
+  return {
+    startDate: startDate,
+    endDate: endDate,
+    isEmpty: Boolean(startDate && endDate && startDate > endDate)
+  };
+}
+
 // 多语言文案配置
 var textConfig = {
   'zh-HK': {
@@ -28,6 +63,7 @@ var textConfig = {
     year: '年',
     available: '可用',
     unlimited: '无限期',
+    noAvailableDates: '無可用日期',
     multipleRules: '多規則，點詳情',
     multipleSlots: '，多時段',
     until: '至',
@@ -56,6 +92,7 @@ var textConfig = {
     year: '年',
     available: '可用',
     unlimited: '无限期',
+    noAvailableDates: '无可用日期',
     multipleRules: '多规则，点详情',
     multipleSlots: '，多时段',
     until: '至',
@@ -84,6 +121,7 @@ var textConfig = {
     year: 'year',
     available: 'available',
     unlimited: 'unlimited',
+    noAvailableDates: 'No available dates',
     multipleRules: 'Multiple rules, see details',
     multipleSlots: ', multiple slots',
     until: 'Until ',
@@ -109,7 +147,9 @@ var textConfig = {
  */
 function getWeekdayText(dayNumbers, locale, separator) {
   var config = textConfig[locale];
-  return dayNumbers.map(function (day) {
+  return _toConsumableArray(new Set(dayNumbers)).sort(function (a, b) {
+    return a - b;
+  }).map(function (day) {
     return config.weekdays[day];
   }).join(separator || config.separator);
 }
@@ -211,13 +251,20 @@ function isAllDaySchedule(startTime, endTime) {
  */
 function formatDateRange(startDate, endDate, isStarted, locale) {
   var isAllDay = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : false;
+  var validity = arguments.length > 5 ? arguments[5] : undefined;
   var config = getConfig(locale);
-  if (isStarted) {
-    var endDateStr = formatDateTime(endDate, isAllDay, locale);
+  var range = getWalletValidityRange(startDate, endDate, validity);
+  if (range.isEmpty) return config.noAvailableDates;
+  var effectiveStart = range.startDate === getValidityDate(startDate) ? startDate : "".concat(range.startDate, " 00:00:00");
+  var effectiveEnd = range.endDate === getValidityDate(endDate) ? endDate : "".concat(range.endDate, " 23:59:59");
+  if (!range.endDate) return config.unlimited;
+  var hasStarted = range.startDate ? dayjs(effectiveStart).isBefore(dayjs()) : isStarted;
+  if (hasStarted || !range.startDate) {
+    var endDateStr = formatDateTime(effectiveEnd, isAllDay, locale);
     return "".concat(config.until).concat(endDateStr);
   } else {
-    var startDateStr = formatDateTime(startDate, isAllDay, locale);
-    var _endDateStr = formatDateTime(endDate, isAllDay, locale);
+    var startDateStr = formatDateTime(effectiveStart, isAllDay, locale);
+    var _endDateStr = formatDateTime(effectiveEnd, isAllDay, locale);
     return "".concat(startDateStr).concat(config.rangeSeparator).concat(_endDateStr);
   }
 }
@@ -230,15 +277,27 @@ function formatDateRange(startDate, endDate, isStarted, locale) {
  */
 export function getScheduleSummary(scheduleList) {
   var locale = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 'zh-CN';
+  var validity = arguments.length > 2 ? arguments[2] : undefined;
   try {
+    locale = textConfig[locale] ? locale : 'en';
     // 输入验证
     if (!scheduleList || !Array.isArray(scheduleList)) {
       return '';
     }
 
-    // 如果是多个日程，直接返回多规则提示
+    // 多规则摘要仍保留卡的到期边界。
     if (scheduleList.length > 1) {
-      return getText(locale, 'multipleRules');
+      var range = getWalletValidityRange(null, null, validity);
+      if (!range.startDate && !range.endDate) return getText(locale, 'multipleRules');
+      var summaries = scheduleList.map(function (schedule) {
+        return getScheduleSummary([schedule], locale, validity);
+      }).filter(function (summary) {
+        return summary !== getText(locale, 'noAvailableDates');
+      });
+      if (summaries.length === 0) return getText(locale, 'noAvailableDates');
+      if (summaries.length === 1 && summaries[0]) return summaries[0];
+      var prefix = range.endDate ? "".concat(formatDateRange(range.startDate || '', range.endDate, false, locale, true)).concat(getText(locale, 'periodSeparator')) : '';
+      return "".concat(prefix).concat(getText(locale, 'multipleRules'));
     }
 
     // 如果没有日程，返回空字符串
@@ -262,12 +321,42 @@ export function getScheduleSummary(scheduleList) {
         startTime = dayjs("".concat(firstDesignation.start_date, " ").concat(firstDesignation.start_time));
       }
     }
+    var passStart = getValidityDate(validity === null || validity === void 0 ? void 0 : validity.start_date);
+    if (passStart && (!startTime || dayjs(passStart).isAfter(startTime))) {
+      startTime = dayjs(passStart);
+    }
 
     // 判断开始时间是否在当前时间之后
     var isStarted = startTime ? isTimeStarted(now, startTime) : false;
 
     // 根据不同类型和状态返回摘要
-    return generateSummaryText(schedule, isStarted, locale);
+    var summary = generateSummaryText(schedule, isStarted, locale, validity);
+    // 包含日期可独立于循环日程的日期范围生效。
+    if (summary === getText(locale, 'noAvailableDates')) {
+      var _schedule$repeat_rule;
+      var included = (_schedule$repeat_rule = schedule.repeat_rule) === null || _schedule$repeat_rule === void 0 || (_schedule$repeat_rule = _schedule$repeat_rule.included_date) === null || _schedule$repeat_rule === void 0 ? void 0 : _schedule$repeat_rule.filter(function (item) {
+        return !getWalletValidityRange(item.start, item.end, validity).isEmpty;
+      });
+      if (included !== null && included !== void 0 && included.length) {
+        return getScheduleSummary([_objectSpread(_objectSpread({}, schedule), {}, {
+          start_time: null,
+          end_time: null,
+          type: 'designation',
+          repeat_type: 'none',
+          repeat_rule: null,
+          is_all: 1,
+          designation: included.map(function (item) {
+            return {
+              start_date: item.start,
+              end_date: item.end,
+              start_time: '00:00',
+              end_time: '23:59'
+            };
+          })
+        })], locale, validity);
+      }
+    }
+    return summary;
   } catch (error) {
     console.warn('Error in getScheduleSummary:', error);
     return '';
@@ -291,29 +380,45 @@ function isTimeStarted(now, startTime) {
  * @param locale 语言设置
  * @returns 生成的摘要文本
  */
-function generateSummaryText(schedule, isStarted, locale) {
+function generateSummaryText(schedule, isStarted, locale, validity) {
   // 1. 多天多段 (designation类型且有多个日期段)
   if (schedule.type === 'designation' && schedule.designation && schedule.designation.length > 1) {
-    return getText(locale, 'multipleRules');
+    var passRange = getWalletValidityRange(null, null, validity);
+    if (!passRange.startDate && !passRange.endDate) return getText(locale, 'multipleRules');
+    var designation = schedule.designation.filter(function (item) {
+      return !getWalletValidityRange(item.start_date, item.end_date, validity).isEmpty;
+    });
+    if (!designation.length) return getText(locale, 'noAvailableDates');
+    if (designation.length === 1) {
+      return generateSingleScheduleSummary(_objectSpread(_objectSpread({}, schedule), {}, {
+        designation: designation
+      }), isStarted, locale, validity);
+    }
+    var range = getWalletValidityRange(designation.map(function (item) {
+      return item.start_date;
+    }).sort()[0], designation.map(function (item) {
+      return item.end_date;
+    }).sort().pop(), validity);
+    var prefix = range.endDate ? "".concat(formatDateRange(range.startDate || '', range.endDate, isStarted, locale, true)).concat(getText(locale, 'periodSeparator')) : '';
+    return "".concat(prefix).concat(getText(locale, 'multipleRules'));
   }
 
   // 2. 单日多段 (time-slots类型)
   if (schedule.type === 'time-slots') {
-    var endDate = getScheduleEndDate(schedule);
-    if (!endDate) return '';
-    var endDateStr = formatDateTime(endDate, true, locale);
-    var prefix = '';
+    var _range = getWalletValidityRange(schedule.start_time, getScheduleEndDate(schedule), validity);
+    if (_range.isEmpty) return getText(locale, 'noAvailableDates');
+    var endDateStr = _range.endDate ? formatDateTime(_range.endDate, true, locale) : getText(locale, 'unlimited');
     var suffix = getText(locale, 'multipleSlots');
-    return "".concat(prefix).concat(endDateStr).concat(suffix);
+    return "".concat(endDateStr).concat(suffix);
   }
 
   // 3. 循环日程
   if (schedule.repeat_type !== 'none' && schedule.repeat_rule) {
-    return generateRecurringSummary(schedule, isStarted, locale);
+    return generateRecurringSummary(schedule, isStarted, locale, validity);
   }
 
   // 4. 单个日程（包括designation类型的单个日期段）
-  return generateSingleScheduleSummary(schedule, isStarted, locale);
+  return generateSingleScheduleSummary(schedule, isStarted, locale, validity);
 }
 
 /**
@@ -323,29 +428,30 @@ function generateSummaryText(schedule, isStarted, locale) {
  * @param locale 语言设置
  * @returns 循环日程摘要文本
  */
-function generateRecurringSummary(schedule, isStarted, locale) {
+function generateRecurringSummary(schedule, isStarted, locale, validity) {
   var repeat_type = schedule.repeat_type,
     repeat_rule = schedule.repeat_rule;
   if (!repeat_rule) return '';
   var frequency = repeat_rule.frequency,
     frequency_date = repeat_rule.frequency_date,
     end = repeat_rule.end;
+  var range = getWalletValidityRange(schedule.start_time, getScheduleEndDate(schedule), validity);
+  if (range.isEmpty) return getText(locale, 'noAvailableDates');
 
   // 特殊处理：当 end.type === 'never' 时的格式
-  if (end.type === 'never') {
-    return generateNeverEndingRecurringSummary(schedule, isStarted, locale, repeat_type, frequency, frequency_date);
+  if (end.type === 'never' && !range.endDate) {
+    return generateNeverEndingRecurringSummary(schedule, isStarted, locale, repeat_type, frequency, frequency_date, validity);
   }
 
   // 原有逻辑：有结束时间的循环日程
-  var endDate = getScheduleEndDate(schedule);
+  var endDate = range.endDate;
   if (!endDate) return '';
-  var endDateStr = formatDateTime(endDate, true, locale);
 
   // 按天循环
   if (repeat_type === 'daily') {
     var frequencyText = getDailyFrequencyText(frequency, locale);
-    var dateRange = formatDateRange(schedule.start_time, endDate, isStarted, locale, true);
-    return "".concat(dateRange, "\uFF0C").concat(frequencyText);
+    var dateRange = formatDateRange(schedule.start_time, endDate, isStarted, locale, true, validity);
+    return "".concat(dateRange).concat(getText(locale, 'timeSlotSeparator')).concat(frequencyText);
   }
 
   // 按周循环
@@ -353,8 +459,8 @@ function generateRecurringSummary(schedule, isStarted, locale) {
     var weekdaysText = getWeekdayText(frequency_date, locale, '/');
     var frequencyPrefix = getWeeklyFrequencyPrefix(frequency, locale);
     var config = getConfig(locale);
-    var _dateRange = formatDateRange(schedule.start_time, endDate, isStarted, locale, true);
-    return "".concat(_dateRange, "\uFF0C").concat(frequencyPrefix).concat(config.weekPrefix).concat(weekdaysText);
+    var _dateRange = formatDateRange(schedule.start_time, endDate, isStarted, locale, true, validity);
+    return "".concat(_dateRange).concat(config.timeSlotSeparator).concat(frequencyPrefix).concat(config.weekPrefix).concat(weekdaysText);
   }
   return '';
 }
@@ -369,15 +475,16 @@ function generateRecurringSummary(schedule, isStarted, locale) {
  * @param frequencyDate 频率日期数组（用于周循环）
  * @returns 永不结束的循环日程摘要文本
  */
-function generateNeverEndingRecurringSummary(schedule, isStarted, locale, repeatType, frequency, frequencyDate) {
+function generateNeverEndingRecurringSummary(schedule, isStarted, locale, repeatType, frequency, frequencyDate, validity) {
   var config = getConfig(locale);
 
   // 按天循环
   if (repeatType === 'daily') {
     if (frequency === 1) {
       // 频率=1：中文"自 YYYY-MM-DD 起长期有效"，英文"Valid from DD MMM YYYY, no expiry"
-      if (schedule.start_time) {
-        var startDateStr = formatDateTime(schedule.start_time, true, locale);
+      var range = getWalletValidityRange(schedule.start_time, null, validity);
+      if (range.startDate) {
+        var startDateStr = formatDateTime(range.startDate, true, locale);
         return "".concat(config.longTermValidFrom).concat(startDateStr).concat(config.noExpiry);
       }
       return '';
@@ -422,7 +529,7 @@ function generateNeverEndingRecurringSummary(schedule, isStarted, locale, repeat
  * @param locale 语言设置
  * @returns 单个日程摘要文本
  */
-function generateSingleScheduleSummary(schedule, isStarted, locale) {
+function generateSingleScheduleSummary(schedule, isStarted, locale, validity) {
   var isAllDay = schedule.is_all === 1;
 
   // 处理designation类型的单个日期段
@@ -437,12 +544,12 @@ function generateSingleScheduleSummary(schedule, isStarted, locale) {
     var isDesignationAllDay = isAllDaySchedule(startTime, endTime);
     if (isDesignationAllDay || isAllDay) {
       // 全天日程
-      return formatDateRange(startDate, endDate, isStarted, locale, true);
+      return formatDateRange(startDate, endDate, isStarted, locale, true, validity);
     } else {
       // 非全天日程
       var startDateTime = "".concat(startDate, " ").concat(startTime).concat(CONSTANTS.SECONDS_SUFFIX);
       var endDateTime = "".concat(endDate, " ").concat(endTime).concat(CONSTANTS.SECONDS_SUFFIX);
-      return formatDateRange(startDateTime, endDateTime, isStarted, locale, false);
+      return formatDateRange(startDateTime, endDateTime, isStarted, locale, false, validity);
     }
   }
 
@@ -451,10 +558,10 @@ function generateSingleScheduleSummary(schedule, isStarted, locale) {
     // 全天日程
     var _endDate = getScheduleEndDate(schedule);
     if (!_endDate) return '';
-    return formatDateRange(schedule.start_time, _endDate, isStarted, locale, true);
+    return formatDateRange(schedule.start_time, _endDate, isStarted, locale, true, validity);
   } else {
     // 非全天日程
-    return formatDateRange(schedule.start_time, schedule.end_time, isStarted, locale, false);
+    return formatDateRange(schedule.start_time, schedule.end_time, isStarted, locale, false, validity);
   }
 }
 
@@ -468,9 +575,7 @@ function getScheduleEndDate(schedule) {
     // 循环日程
     if (schedule.repeat_rule) {
       if (schedule.repeat_rule.end.type === 'never') {
-        // 无限期的情况，返回一个合理的未来日期作为显示
-        var futureDate = dayjs().add(CONSTANTS.DEFAULT_FUTURE_YEARS, 'year');
-        return "".concat(futureDate.format('YYYY-MM-DD'), " ").concat(CONSTANTS.ALL_DAY_END).concat(CONSTANTS.SECONDS_SUFFIX);
+        return null;
       } else if (schedule.repeat_rule.end.end_date) {
         return "".concat(schedule.repeat_rule.end.end_date, " ").concat(CONSTANTS.ALL_DAY_END).concat(CONSTANTS.SECONDS_SUFFIX);
       }

package/es/weighing.d.ts

@@ -0,0 +1,62 @@
+/** 商品配置与 NativeScale 使用的重量单位。 */
+export declare type WeightUnitName = 'KILOGRAMS' | 'GRAMS' | 'POUNDS' | 'OUNCES';
+/** 订单快照与 UI 使用的标准单位符号。 */
+export declare type WeightUnitSymbol = 'kg' | 'g' | 'lb' | 'oz';
+export declare type WeightUnit = WeightUnitName | WeightUnitSymbol;
+/**
+ * Pisell 的标准重量单位。目录单价、缺省秤单位和缺省展示均以它为准。
+ * 后续标准单位变化时，应优先只修改此处。
+ */
+export declare const STANDARD_WEIGHT_UNIT: WeightUnitName;
+export declare const WEIGHT_PRECISION = 3;
+export declare const UNIT_PRICE_PRECISION = 2;
+export declare const MAX_RETAIL_SCALE_WEIGHT_KG = 1000;
+export declare const WEIGHT_UNIT_SYMBOLS: Record<WeightUnitName, WeightUnitSymbol>;
+export declare const WEIGHT_UNIT_NAMES: Record<WeightUnitSymbol, WeightUnitName>;
+/** 单位对应的克数，作为不依赖 NativeScale 的目录价格换算基准。 */
+export declare const WEIGHT_UNIT_GRAMS: Record<WeightUnit, number>;
+export declare const STANDARD_WEIGHT_UNIT_SYMBOL: WeightUnitSymbol;
+export declare const normalizeWeightUnit: (unit?: string | null, fallback?: WeightUnitName) => WeightUnitName;
+export declare const getWeightUnitSymbol: (unit?: string | null) => string;
+export declare const getWeightUnitGrams: (unit?: string | null) => number | undefined;
+/**
+ * 将“每 sourceUnitValue 个 sourceUnit 的价格”换算到每 1 个目标单位的倍率。
+ * 这里只处理目录单价的单位关系；实际秤读数计价仍应使用 NativeScale。
+ */
+export declare const getWeightUnitPriceConversionFactor: (params: {
+    sourceUnit?: string | null;
+    sourceUnitValue?: string | number | null;
+    targetUnit?: string | null;
+}) => number | undefined;
+export declare const isSupportedWeightUnit: (unit?: unknown) => unit is WeightUnit;
+export declare const formatWeightValue: (value: unknown, precision?: number) => string;
+export declare const formatUnitPriceValue: (value: unknown, precision?: number) => string;
+export declare type ScaleReadingStatus = 'stable' | 'unstable' | 'overload' | 'negative' | string | null;
+export declare const INVALID_SCALE_READING_STATUSES: readonly ["overload", "negative"];
+export declare const isInvalidScaleReadingStatus: (status?: ScaleReadingStatus) => boolean;
+export declare const getUsableScaleWeight: (status: ScaleReadingStatus | undefined, weight: number) => number;
+export interface WeighingSnapshot {
+    open_sold_weight?: number | string | boolean;
+    mode?: 'auto' | 'manual' | string;
+    weight_source?: 'auto' | 'manual' | string;
+    weight?: string | number;
+    tare?: {
+        id?: string;
+        label?: string;
+        value?: string | number;
+        unit?: WeightUnit | string;
+    };
+    tare_name?: string;
+    tare_weight?: string | number;
+    net_weight?: string | number;
+    unit_price?: string | number;
+    unit?: WeightUnit | string;
+    unit_weight?: string | number;
+    unit_data_snapshot?: unknown;
+    scalePriceProduct?: unknown;
+    total_amount?: string | number;
+}
+/**
+ * 解析订单行称重快照：product_sku 是权威源，_extend.weighing 仅用于旧流程兼容。
+ */
+export declare const resolveWeighingSnapshot: (dataSource?: Record<string, any> | null) => WeighingSnapshot | undefined;

package/es/weighing.js

@@ -0,0 +1,119 @@
+/** 商品配置与 NativeScale 使用的重量单位。 */
+
+/** 订单快照与 UI 使用的标准单位符号。 */
+
+/**
+ * Pisell 的标准重量单位。目录单价、缺省秤单位和缺省展示均以它为准。
+ * 后续标准单位变化时，应优先只修改此处。
+ */
+export var STANDARD_WEIGHT_UNIT = 'KILOGRAMS';
+export var WEIGHT_PRECISION = 3;
+export var UNIT_PRICE_PRECISION = 2;
+export var MAX_RETAIL_SCALE_WEIGHT_KG = 1000;
+export var WEIGHT_UNIT_SYMBOLS = {
+  KILOGRAMS: 'kg',
+  GRAMS: 'g',
+  POUNDS: 'lb',
+  OUNCES: 'oz'
+};
+export var WEIGHT_UNIT_NAMES = {
+  kg: 'KILOGRAMS',
+  g: 'GRAMS',
+  lb: 'POUNDS',
+  oz: 'OUNCES'
+};
+
+/** 单位对应的克数，作为不依赖 NativeScale 的目录价格换算基准。 */
+export var WEIGHT_UNIT_GRAMS = {
+  KILOGRAMS: 1000,
+  GRAMS: 1,
+  POUNDS: 453.59237,
+  OUNCES: 28.349523125,
+  kg: 1000,
+  g: 1,
+  lb: 453.59237,
+  oz: 28.349523125
+};
+export var STANDARD_WEIGHT_UNIT_SYMBOL = WEIGHT_UNIT_SYMBOLS[STANDARD_WEIGHT_UNIT];
+export var normalizeWeightUnit = function normalizeWeightUnit(unit) {
+  var fallback = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : STANDARD_WEIGHT_UNIT;
+  if (unit && unit in WEIGHT_UNIT_SYMBOLS) {
+    return unit;
+  }
+  if (unit && unit in WEIGHT_UNIT_NAMES) {
+    return WEIGHT_UNIT_NAMES[unit];
+  }
+  return fallback;
+};
+export var getWeightUnitSymbol = function getWeightUnitSymbol(unit) {
+  if (unit && unit in WEIGHT_UNIT_SYMBOLS) {
+    return WEIGHT_UNIT_SYMBOLS[unit];
+  }
+  if (unit && unit in WEIGHT_UNIT_NAMES) {
+    return unit;
+  }
+  return unit || STANDARD_WEIGHT_UNIT_SYMBOL;
+};
+export var getWeightUnitGrams = function getWeightUnitGrams(unit) {
+  return unit ? WEIGHT_UNIT_GRAMS[unit] : WEIGHT_UNIT_GRAMS[STANDARD_WEIGHT_UNIT];
+};
+
+/**
+ * 将“每 sourceUnitValue 个 sourceUnit 的价格”换算到每 1 个目标单位的倍率。
+ * 这里只处理目录单价的单位关系；实际秤读数计价仍应使用 NativeScale。
+ */
+export var getWeightUnitPriceConversionFactor = function getWeightUnitPriceConversionFactor(params) {
+  var _params$sourceUnitVal;
+  var sourceGrams = getWeightUnitGrams(params.sourceUnit || STANDARD_WEIGHT_UNIT);
+  var targetGrams = getWeightUnitGrams(params.targetUnit || STANDARD_WEIGHT_UNIT);
+  var sourceUnitValue = Number((_params$sourceUnitVal = params.sourceUnitValue) !== null && _params$sourceUnitVal !== void 0 ? _params$sourceUnitVal : 1);
+  if (!sourceGrams || !targetGrams || !Number.isFinite(sourceUnitValue) || sourceUnitValue <= 0) {
+    return undefined;
+  }
+  return targetGrams / (sourceGrams * sourceUnitValue);
+};
+export var isSupportedWeightUnit = function isSupportedWeightUnit(unit) {
+  return typeof unit === 'string' && unit in WEIGHT_UNIT_GRAMS;
+};
+export var formatWeightValue = function formatWeightValue(value) {
+  var precision = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : WEIGHT_PRECISION;
+  var parsedValue = Number(value);
+  return (Number.isFinite(parsedValue) ? parsedValue : 0).toFixed(precision);
+};
+export var formatUnitPriceValue = function formatUnitPriceValue(value) {
+  var precision = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : UNIT_PRICE_PRECISION;
+  var parsedValue = Number(value);
+  return (Number.isFinite(parsedValue) ? parsedValue : 0).toFixed(precision);
+};
+export var INVALID_SCALE_READING_STATUSES = ['overload', 'negative'];
+export var isInvalidScaleReadingStatus = function isInvalidScaleReadingStatus(status) {
+  return INVALID_SCALE_READING_STATUSES.includes(status);
+};
+export var getUsableScaleWeight = function getUsableScaleWeight(status, weight) {
+  return isInvalidScaleReadingStatus(status) ? 0 : weight;
+};
+var hasDisplayWeight = function hasDisplayWeight(value) {
+  return Boolean(value && (Number(value.weight) > 0 || Number(value.net_weight) > 0));
+};
+var resolveProductSkuSnapshot = function resolveProductSkuSnapshot(value) {
+  var snapshot = value;
+  return Number(snapshot === null || snapshot === void 0 ? void 0 : snapshot.open_sold_weight) === 1 && hasDisplayWeight(snapshot) ? snapshot : undefined;
+};
+
+/**
+ * 解析订单行称重快照：product_sku 是权威源，_extend.weighing 仅用于旧流程兼容。
+ */
+export var resolveWeighingSnapshot = function resolveWeighingSnapshot(dataSource) {
+  var _dataSource$_origin, _dataSource$metadata, _dataSource$_origin2, _dataSource$_extend, _dataSource$metadata2;
+  if (!dataSource) return undefined;
+  var productSkuCandidates = [dataSource.product_sku, (_dataSource$_origin = dataSource._origin) === null || _dataSource$_origin === void 0 ? void 0 : _dataSource$_origin.product_sku, (_dataSource$metadata = dataSource.metadata) === null || _dataSource$metadata === void 0 || (_dataSource$metadata = _dataSource$metadata.origin) === null || _dataSource$metadata === void 0 ? void 0 : _dataSource$metadata.product_sku];
+  for (var _i = 0, _productSkuCandidates = productSkuCandidates; _i < _productSkuCandidates.length; _i++) {
+    var candidate = _productSkuCandidates[_i];
+    var snapshot = resolveProductSkuSnapshot(candidate);
+    if (snapshot) return snapshot;
+  }
+  var legacyCandidates = [(_dataSource$_origin2 = dataSource._origin) === null || _dataSource$_origin2 === void 0 || (_dataSource$_origin2 = _dataSource$_origin2._extend) === null || _dataSource$_origin2 === void 0 ? void 0 : _dataSource$_origin2.weighing, (_dataSource$_extend = dataSource._extend) === null || _dataSource$_extend === void 0 ? void 0 : _dataSource$_extend.weighing, (_dataSource$metadata2 = dataSource.metadata) === null || _dataSource$metadata2 === void 0 || (_dataSource$metadata2 = _dataSource$metadata2.origin) === null || _dataSource$metadata2 === void 0 || (_dataSource$metadata2 = _dataSource$metadata2._extend) === null || _dataSource$metadata2 === void 0 ? void 0 : _dataSource$metadata2.weighing];
+  return legacyCandidates.find(function (candidate) {
+    return hasDisplayWeight(candidate);
+  });
+};

package/lib/arrayUtils.d.ts

@@ -1 +1,73 @@
 export declare const uniqueByKey: <T>(arr: T[], key: keyof T) => T[];
+/**
+ * 分组键的基础类型
+ * @description 分组条件计算后得到的标量值
+ */
+export declare type GroupKey = string | number | boolean;
+/**
+ * 分组规则
+ * @template T - 数据项类型
+ * @description
+ * - `string`：单字段路径，支持 `'a.b.c'` 点路径
+ * - `string[]`：多字段组合，按顺序拼接为组合键
+ * - `(item, index) => GroupKey | GroupKey[]`：完全自定义分组键
+ */
+export declare type GroupBySpec<T> = string | string[] | ((item: T, index: number) => GroupKey | GroupKey[]);
+/**
+ * 单个分组的结果模型
+ * @template T - 数据项类型
+ */
+export interface GroupResult<T> {
+    /** 分组唯一标识（默认由各分组键以 `|` 拼接） */
+    groupId: string;
+    /** 分组键值数组，与 `GroupBySpec` 顺序对应 */
+    keys: GroupKey[];
+    /** 字段名 -> 键值映射，便于头部直接按字段名取值（自定义函数分组时为空对象） */
+    keyMap: Record<string, GroupKey>;
+    /** 该分组内的原始数据项（保持原数组中的相对顺序） */
+    items: T[];
+    /** 分组的最终顺序下标 */
+    index: number;
+}
+/**
+ * 分组可选项
+ * @template T - 数据项类型
+ */
+export interface GroupByOptions<T> {
+    /** 自定义分组 id 生成（默认 `keys.join('|')`） */
+    getGroupId?: (keys: GroupKey[]) => string;
+    /** 分组之间的排序；不传则保持各分组首次出现的顺序 */
+    sortGroups?: (a: GroupResult<T>, b: GroupResult<T>) => number;
+    /** 分组内数据项的排序；不传则保持原始相对顺序 */
+    sortItems?: (a: T, b: T) => number;
+}
+/**
+ * 按点路径安全取值
+ * @param obj - 取值对象
+ * @param path - 字段路径，支持 `'a.b.c'`
+ * @returns 路径对应的值，路径不存在时返回 undefined
+ * @example
+ * getByPath({ a: { b: 1 } }, 'a.b') // 1
+ * getByPath({ id: 9 }, 'id') // 9
+ */
+export declare const getByPath: (obj: unknown, path: string) => unknown;
+/**
+ * 将数组按指定条件分组
+ * @template T - 数据项类型
+ * @param dataSource - 待分组的数据数组
+ * @param spec - 分组规则，详见 {@link GroupBySpec}
+ * @param options - 可选项（自定义 groupId、分组/组内排序）
+ * @returns 分组结果数组，默认保持各分组首次出现的顺序、组内保持原始相对顺序
+ * @description
+ * 该函数为纯函数，不修改入参（排序时对内部拷贝操作）。相同分组键的数据会被归入同一分组。
+ * @example
+ * // 单字段
+ * groupBy(list, 'productId');
+ * @example
+ * // 商品 + 时间组合
+ * groupBy(list, ['productId', 'time']);
+ * @example
+ * // 自定义键
+ * groupBy(list, (item) => `${item.productId}_${item.time}`);
+ */
+export declare const groupBy: <T>(dataSource: T[], spec: GroupBySpec<T>, options?: GroupByOptions<T>) => GroupResult<T>[];