@pisell/pisellos 0.0.568 → 0.10.1

package/dist/modules/Order/types.js

@@ -3,10 +3,69 @@ export var OrderHooks = /*#__PURE__*/function (OrderHooks) {
   OrderHooks["OnOrderUpdate"] = "order:onOrderUpdate";
   OrderHooks["OnOrderCancel"] = "order:onOrderCancel";
   OrderHooks["OnOrderStatusChange"] = "order:onOrderStatusChange";
+  OrderHooks["OnOrderCustomerChange"] = "order:onOrderCustomerChange";
+  OrderHooks["OnPromotionApplied"] = "order:onPromotionApplied";
   return OrderHooks;
 }({});
 
-/** 更新购物车行：仅传 SKU 时命中同 SKU 第一行；多行同 SKU 须传 identity_key / 选项指纹等 */
+/**
+ * 促销评估器协议（OS 与 PromotionEvaluator 之间的桥接接口）。
+ *
+ * 与 `pisell_os/src/model/strategy/adapter/promotion/evaluator.ts` 中的
+ * `PromotionEvaluator` 实例结构保持兼容。SalesSdkProvider 会从 `appHelper.utils.promotionEvaluator`
+ * 读取实例并通过 `setPromotionEvaluator` 注入到 OrderModule。
+ *
+ * 这里只声明 OrderModule 需要调用的子集，避免反向依赖具体 evaluator 实现。
+ */
+
+/** 赠品解析回调 context（OS → SDK 的请求体） */
+
+/**
+ * 赠品 resolver 返回值。
+ *
+ * @example
+ * return { products: [giftProduct], bookings: [giftBooking] };
+ */
+
+/**
+ * 赠品解析回调签名（SDK → OS 的返回值）。
+ *
+ * - 单选项：SDK 内部自动构造商品，不弹窗
+ * - 多选项：SDK 弹窗等用户确认后构造
+ * - 用户取消：抛错或返回空数组（OS 视为放弃本次添加）
+ *
+ * 返回数组时沿用旧协议，只写 tempOrder.products；返回对象时可同时写入预约 bookings。
+ */
+
+/** 未满足的促销策略（购物车底部 alert 渲染源） */
+
+/** 上一次 applyPromotion 计算出的赠品操作（仅供调试/读取使用） */
+
+/** onPromotionApplied 事件 payload */
+
+/**
+ * tempOrder 上的下单客户协议字段视图。
+ * 这些字段会随订单提交到后端。
+ *
+ * customer_id 与 OrderTempOrder.customer_id 保持一致（number | null），
+ * 调用方若持有 string id（如 ICustomer.id 联合类型），需自行 Number() 转型。
+ */
+
+/**
+ * 写入下单客户的协议字段输入。
+ * `customer_id` 必传（null 表示无客户）；其余字段缺省视为「清空」（全量覆盖语义）。
+ */
+
+/**
+ * 下单客户变更事件 payload。
+ * - `patch`：tempOrder 上的协议字段视图（会随订单提交）
+ * - `snapshot`：UI 富字段快照（仅本地，不随订单提交）
+ * 清空时整个 payload 为 null。
+ */
+
+/** 更新购物车行：仅传 SKU 时命中同 SKU 第一行；多行同 SKU 须传 unique_identification_number / 选项指纹等 */
+
+/** 仅更新购物车行数量；行定位语义与 updateOrderProduct / removeProductFromOrder 保持一致 */
 
 /**
  * 订单信息
@@ -20,6 +79,14 @@ export var OrderHooks = /*#__PURE__*/function (OrderHooks) {
  * Checkout 专用订单创建参数
  */
 
+/**
+ * 取消订单参数
+ */
+
+/**
+ * 变更预约状态参数
+ */
+
 /**
  * 订单模块 API
  */

package/dist/modules/Order/utils/bundleDiscountHydration.d.ts

@@ -0,0 +1,5 @@
+import type { OrderProductDiscountItem } from '../types';
+type NormalizeDiscountList = (discountList?: unknown[] | null) => OrderProductDiscountItem[];
+export declare function restoreHydratedBundleDiscounts<T extends Record<string, any>>(product: T, normalizeDiscountList: NormalizeDiscountList): T;
+export declare function expandHydratedProductsForDiscountCollection(products: any[] | undefined | null): any[];
+export {};

package/dist/modules/Order/utils/bundleDiscountHydration.js

@@ -0,0 +1,144 @@
+function _createForOfIteratorHelper(o, allowArrayLike) { var it = typeof Symbol !== "undefined" && o[Symbol.iterator] || o["@@iterator"]; if (!it) { if (Array.isArray(o) || (it = _unsupportedIterableToArray(o)) || allowArrayLike && o && typeof o.length === "number") { if (it) o = it; var i = 0; var F = function F() {}; return { s: F, n: function n() { if (i >= o.length) return { done: true }; return { done: false, value: o[i++] }; }, e: function e(_e) { throw _e; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var normalCompletion = true, didErr = false, err; return { s: function s() { it = it.call(o); }, n: function n() { var step = it.next(); normalCompletion = step.done; return step; }, e: function e(_e2) { didErr = true; err = _e2; }, f: function f() { try { if (!normalCompletion && it.return != null) it.return(); } finally { if (didErr) throw err; } } }; }
+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; }
+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 _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); }
+var BUNDLE_MAP_ID_KEY = 'custom_product_bundle_map_id';
+function getBundleMapId(bundle) {
+  var _bundle$metadata;
+  var metadataMapId = bundle === null || bundle === void 0 || (_bundle$metadata = bundle.metadata) === null || _bundle$metadata === void 0 ? void 0 : _bundle$metadata[BUNDLE_MAP_ID_KEY];
+  if (metadataMapId !== undefined && metadataMapId !== null && metadataMapId !== '') {
+    return String(metadataMapId);
+  }
+  if ((bundle === null || bundle === void 0 ? void 0 : bundle._id) !== undefined && bundle._id !== null && bundle._id !== '') {
+    return String(bundle._id);
+  }
+  return null;
+}
+function getDiscountBundleMapId(discount) {
+  var _discount$metadata;
+  var mapId = discount === null || discount === void 0 || (_discount$metadata = discount.metadata) === null || _discount$metadata === void 0 ? void 0 : _discount$metadata[BUNDLE_MAP_ID_KEY];
+  if (mapId === undefined || mapId === null || mapId === '') return null;
+  return String(mapId);
+}
+function hasSameBundleDiscount(discountList, discount) {
+  var _ref, _discount$discount$re, _discount$discount;
+  var targetOrderDiscountId = discount.order_discount_id;
+  if (targetOrderDiscountId !== undefined && targetOrderDiscountId !== null) {
+    return discountList.some(function (item) {
+      return (item === null || item === void 0 ? void 0 : item.order_discount_id) === targetOrderDiscountId;
+    });
+  }
+  var targetResourceId = (_ref = (_discount$discount$re = discount === null || discount === void 0 || (_discount$discount = discount.discount) === null || _discount$discount === void 0 ? void 0 : _discount$discount.resource_id) !== null && _discount$discount$re !== void 0 ? _discount$discount$re : discount === null || discount === void 0 ? void 0 : discount.resource_id) !== null && _ref !== void 0 ? _ref : discount === null || discount === void 0 ? void 0 : discount.discount_id;
+  var targetMapId = getDiscountBundleMapId(discount);
+  return discountList.some(function (item) {
+    var _ref2, _item$discount$resour, _item$discount, _item$amount, _discount$amount;
+    var resourceId = (_ref2 = (_item$discount$resour = item === null || item === void 0 || (_item$discount = item.discount) === null || _item$discount === void 0 ? void 0 : _item$discount.resource_id) !== null && _item$discount$resour !== void 0 ? _item$discount$resour : item === null || item === void 0 ? void 0 : item.resource_id) !== null && _ref2 !== void 0 ? _ref2 : item === null || item === void 0 ? void 0 : item.discount_id;
+    return resourceId === targetResourceId && String((_item$amount = item === null || item === void 0 ? void 0 : item.amount) !== null && _item$amount !== void 0 ? _item$amount : '') === String((_discount$amount = discount === null || discount === void 0 ? void 0 : discount.amount) !== null && _discount$amount !== void 0 ? _discount$amount : '') && getDiscountBundleMapId(item) === targetMapId;
+  });
+}
+export function restoreHydratedBundleDiscounts(product, normalizeDiscountList) {
+  if (!Array.isArray(product.product_bundle) || !Array.isArray(product.discount_list)) {
+    return product;
+  }
+  var bundleByMapId = new Map();
+  product.product_bundle.forEach(function (bundle) {
+    if (!bundle || _typeof(bundle) !== 'object') return;
+    var mapId = getBundleMapId(bundle);
+    if (mapId) bundleByMapId.set(mapId, bundle);
+  });
+  if (!bundleByMapId.size) return product;
+  var mainDiscountList = [];
+  var bundleDiscounts = [];
+  product.discount_list.forEach(function (discount) {
+    var mapId = getDiscountBundleMapId(discount);
+    if (mapId && bundleByMapId.has(mapId)) {
+      bundleDiscounts.push({
+        mapId: mapId,
+        discount: discount
+      });
+    } else {
+      mainDiscountList.push(discount);
+    }
+  });
+  if (!bundleDiscounts.length) return product;
+  return _objectSpread(_objectSpread({}, product), {}, {
+    discount_list: normalizeDiscountList(mainDiscountList),
+    product_bundle: product.product_bundle.map(function (bundle) {
+      if (!bundle || _typeof(bundle) !== 'object') return bundle;
+      var mapId = getBundleMapId(bundle);
+      if (!mapId) return bundle;
+      var matchedDiscounts = bundleDiscounts.filter(function (item) {
+        return item.mapId === mapId;
+      }).map(function (item) {
+        return item.discount;
+      });
+      if (!matchedDiscounts.length) return bundle;
+      var currentDiscountList = Array.isArray(bundle.discount_list) ? _toConsumableArray(bundle.discount_list) : [];
+      var _iterator = _createForOfIteratorHelper(matchedDiscounts),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var discount = _step.value;
+          if (!hasSameBundleDiscount(currentDiscountList, discount)) {
+            currentDiscountList.push(discount);
+          }
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return _objectSpread(_objectSpread({}, bundle), {}, {
+        discount_list: normalizeDiscountList(currentDiscountList),
+        metadata: _objectSpread(_objectSpread({}, bundle.metadata || {}), {}, _defineProperty({}, BUNDLE_MAP_ID_KEY, mapId))
+      });
+    })
+  });
+}
+export function expandHydratedProductsForDiscountCollection(products) {
+  var expanded = [];
+  var _iterator2 = _createForOfIteratorHelper(products || []),
+    _step2;
+  try {
+    for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+      var product = _step2.value;
+      expanded.push(product);
+      var _iterator3 = _createForOfIteratorHelper((product === null || product === void 0 ? void 0 : product.product_bundle) || []),
+        _step3;
+      try {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var _ref3, _ref4, _bundle$bundle_produc, _ref5, _bundle$num, _ref6, _bundle$quantity, _ref7, _bundle$original_pric, _bundle$bundle_sellin, _bundle$is_charge_tax;
+          var bundle = _step3.value;
+          if (!Array.isArray(bundle === null || bundle === void 0 ? void 0 : bundle.discount_list) || bundle.discount_list.length === 0) continue;
+          expanded.push(_objectSpread(_objectSpread({}, product), {}, {
+            product_id: (_ref3 = (_ref4 = (_bundle$bundle_produc = bundle.bundle_product_id) !== null && _bundle$bundle_produc !== void 0 ? _bundle$bundle_produc : bundle._bundle_product_id) !== null && _ref4 !== void 0 ? _ref4 : bundle.product_id) !== null && _ref3 !== void 0 ? _ref3 : product === null || product === void 0 ? void 0 : product.product_id,
+            num: (_ref5 = (_bundle$num = bundle.num) !== null && _bundle$num !== void 0 ? _bundle$num : bundle.quantity) !== null && _ref5 !== void 0 ? _ref5 : product === null || product === void 0 ? void 0 : product.num,
+            product_quantity: (_ref6 = (_bundle$quantity = bundle.quantity) !== null && _bundle$quantity !== void 0 ? _bundle$quantity : bundle.num) !== null && _ref6 !== void 0 ? _ref6 : product === null || product === void 0 ? void 0 : product.product_quantity,
+            original_price: (_ref7 = (_bundle$original_pric = bundle.original_price) !== null && _bundle$original_pric !== void 0 ? _bundle$original_pric : bundle.product_price) !== null && _ref7 !== void 0 ? _ref7 : bundle.price,
+            selling_price: (_bundle$bundle_sellin = bundle.bundle_selling_price) !== null && _bundle$bundle_sellin !== void 0 ? _bundle$bundle_sellin : bundle.price,
+            is_charge_tax: (_bundle$is_charge_tax = bundle.is_charge_tax) !== null && _bundle$is_charge_tax !== void 0 ? _bundle$is_charge_tax : product === null || product === void 0 ? void 0 : product.is_charge_tax,
+            discount_list: bundle.discount_list
+          }));
+        }
+      } catch (err) {
+        _iterator3.e(err);
+      } finally {
+        _iterator3.f();
+      }
+    }
+  } catch (err) {
+    _iterator2.e(err);
+  } finally {
+    _iterator2.f();
+  }
+  return expanded;
+}

package/dist/modules/Order/utils/manualProductDiscount.d.ts

@@ -0,0 +1,106 @@
+/** 解析商品行数量（checkout 协议 product_num 语义 = 当前行 num） */
+export declare function resolveSafeProductNum(num?: number | null): number;
+/**
+ * 将 discount_list 中 type=product 项的 product_num 同步为当前商品数量。
+ *
+ * @example
+ * syncManualProductDiscountProductNum(line.discount_list, line.num);
+ */
+export declare function syncManualProductDiscountProductNum(discountList: any[] | undefined | null, productNum?: number | null): any[];
+/** 从多源解析改价前行总价（与 cacheItem._extend.origin_total 语义一致） */
+export declare function resolveManualDiscountOriginTotal(sources: {
+    originTotal?: unknown;
+    extendOriginTotal?: unknown;
+    originExtendOriginTotal?: unknown;
+    sourceExtendOriginTotal?: unknown;
+    catalogUnitPrice?: unknown;
+    quantity?: number;
+}): number;
+/** 从 payload / extend / origin 解析手动折扣原因 */
+export declare function resolveManualDiscountReasonFromSources(sources: {
+    discountReason?: unknown;
+    extendDiscountReason?: unknown;
+    originExtendDiscountReason?: unknown;
+}): string;
+/** 是否带手动改价标记（price_override / is_manual_discount） */
+export declare function hasManualProductDiscountFlag(metadata?: Record<string, any> | null): boolean;
+/**
+ * normalize 兜底：手动改价但 discount_list 缺 type=product 时，按行级原价/折后价补写。
+ *
+ * @example
+ * ensureManualProductDiscountList({
+ *   discountList: [],
+ *   metadata: { price_override: '5', is_manual_discount: 1 },
+ *   originalPrice: '11.00',
+ *   sellingPrice: '5.00',
+ *   quantity: 1,
+ * });
+ */
+export declare function ensureManualProductDiscountList(params: {
+    discountList?: any[] | null;
+    metadata?: Record<string, any> | null;
+    originalPrice: string | number;
+    sellingPrice: string | number;
+    quantity?: number;
+}): any[];
+/** 商品手动折扣 discount_list 项（checkout 协议，type = product） */
+export interface ManualProductDiscountItem {
+    amount: number;
+    type: 'product';
+    discount: {
+        message: string;
+        discountway: string;
+        product_num: number;
+        discount_per: string;
+        discount_type: 'discount' | 'change_price';
+    };
+}
+/**
+ * 从 discount_list 中取手动改价项（type = product）。
+ *
+ * @example
+ * const manual = findManualProductDiscountItem(product.discount_list);
+ * manual?.discount.message; // 折扣原因
+ */
+export declare function findManualProductDiscountItem(discountList?: any[] | null): ManualProductDiscountItem | undefined;
+/**
+ * 解析折扣原因：优先 discount_list[type=product].discount.message。
+ *
+ * @example
+ * resolveManualDiscountMessage(line.discount_list, line.metadata?.legacy_reason);
+ */
+export declare function resolveManualDiscountMessage(discountList?: any[] | null, fallback?: string): string;
+/** 去掉 discount_list 中已有的手动改价项，避免重复叠加 */
+export declare function stripManualProductDiscountItems(discountList?: any[] | null): any[];
+/**
+ * 由改价前后行总价构建手动折扣项；amount = |originTotal - sellingTotal|（行级差额）。
+ *
+ * @example
+ * buildManualProductDiscountItem({
+ *   originTotal: 11,
+ *   sellingTotal: 4,
+ *   quantity: 1,
+ *   message: 'VIP',
+ * });
+ */
+export declare function buildManualProductDiscountItem(params: {
+    originTotal: number;
+    sellingTotal: number;
+    quantity?: number;
+    message?: string;
+    discountway?: string;
+    discount_per?: string;
+}): ManualProductDiscountItem;
+/**
+ * 将手动改价项合并进 discount_list（替换已有 type=product 项）。
+ *
+ * @example
+ * mergeManualProductDiscountIntoList(coupons, manualItem);
+ */
+export declare function mergeManualProductDiscountIntoList(discountList: any[] | undefined | null, manualItem: ManualProductDiscountItem | null | undefined): any[];
+/** 是否应写入手动改价 discount_list 项 */
+export declare function shouldBuildManualProductDiscount(params: {
+    hasPriceOverride?: boolean;
+    originTotal?: number;
+    sellingTotal?: number;
+}): boolean;

package/dist/modules/Order/utils/manualProductDiscount.js

@@ -0,0 +1,210 @@
+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 _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; }
+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); }
+import Decimal from 'decimal.js';
+
+/** 解析商品行数量（checkout 协议 product_num 语义 = 当前行 num） */
+export function resolveSafeProductNum(num) {
+  var parsed = Number(num);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 1;
+  return Math.floor(parsed);
+}
+
+/**
+ * 将 discount_list 中 type=product 项的 product_num 同步为当前商品数量。
+ *
+ * @example
+ * syncManualProductDiscountProductNum(line.discount_list, line.num);
+ */
+export function syncManualProductDiscountProductNum(discountList, productNum) {
+  var quantity = resolveSafeProductNum(productNum);
+  return (discountList || []).map(function (item) {
+    if ((item === null || item === void 0 ? void 0 : item.type) !== 'product') return item;
+    return _objectSpread(_objectSpread({}, item), {}, {
+      discount: _objectSpread(_objectSpread({}, item.discount || {}), {}, {
+        product_num: quantity
+      })
+    });
+  });
+}
+
+/** 从多源解析改价前行总价（与 cacheItem._extend.origin_total 语义一致） */
+export function resolveManualDiscountOriginTotal(sources) {
+  var _sources$quantity;
+  var candidates = [sources.originTotal, sources.extendOriginTotal, sources.originExtendOriginTotal, sources.sourceExtendOriginTotal];
+  for (var _i = 0, _candidates = candidates; _i < _candidates.length; _i++) {
+    var candidate = _candidates[_i];
+    if (candidate === undefined || candidate === null || candidate === '') continue;
+    var parsed = Number(candidate);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  var unit = Number(sources.catalogUnitPrice);
+  var quantity = (_sources$quantity = sources.quantity) !== null && _sources$quantity !== void 0 ? _sources$quantity : 1;
+  if (Number.isFinite(unit) && unit > 0) {
+    return new Decimal(unit).mul(quantity).toNumber();
+  }
+  return NaN;
+}
+
+/** 从 payload / extend / origin 解析手动折扣原因 */
+export function resolveManualDiscountReasonFromSources(sources) {
+  for (var _i2 = 0, _arr = [sources.discountReason, sources.extendDiscountReason, sources.originExtendDiscountReason]; _i2 < _arr.length; _i2++) {
+    var candidate = _arr[_i2];
+    if (candidate != null && String(candidate).trim() !== '') {
+      return String(candidate);
+    }
+  }
+  return '';
+}
+
+/** 是否带手动改价标记（price_override / is_manual_discount） */
+export function hasManualProductDiscountFlag(metadata) {
+  if (!metadata) return false;
+  var override = metadata.price_override;
+  if (override !== undefined && override !== null && override !== '') {
+    return true;
+  }
+  return metadata.is_manual_discount === 1 || metadata.is_manual_discount === true;
+}
+
+/**
+ * normalize 兜底：手动改价但 discount_list 缺 type=product 时，按行级原价/折后价补写。
+ *
+ * @example
+ * ensureManualProductDiscountList({
+ *   discountList: [],
+ *   metadata: { price_override: '5', is_manual_discount: 1 },
+ *   originalPrice: '11.00',
+ *   sellingPrice: '5.00',
+ *   quantity: 1,
+ * });
+ */
+export function ensureManualProductDiscountList(params) {
+  var _metadata$origin, _metadata$origin2, _metadata$origin3, _metadata$origin4;
+  var list = params.discountList || [];
+  var quantity = resolveSafeProductNum(params.quantity);
+  if (findManualProductDiscountItem(list)) {
+    return syncManualProductDiscountProductNum(list, quantity);
+  }
+  var metadata = params.metadata || {};
+  var originalNum = Number(params.originalPrice);
+  var sellingNum = Number(params.sellingPrice);
+  var hasPriceOverride = hasManualProductDiscountFlag(metadata);
+  var shouldBuild = shouldBuildManualProductDiscount({
+    hasPriceOverride: hasPriceOverride,
+    originTotal: originalNum,
+    sellingTotal: sellingNum
+  });
+  if (!shouldBuild) {
+    return list;
+  }
+  if (!Number.isFinite(originalNum) || !Number.isFinite(sellingNum) || originalNum === sellingNum) {
+    return list;
+  }
+  var message = resolveManualDiscountMessage(list, resolveManualDiscountReasonFromSources({
+    extendDiscountReason: (_metadata$origin = metadata.origin) === null || _metadata$origin === void 0 || (_metadata$origin = _metadata$origin._extend) === null || _metadata$origin === void 0 ? void 0 : _metadata$origin.discount_reason,
+    originExtendDiscountReason: (_metadata$origin2 = metadata.origin) === null || _metadata$origin2 === void 0 || (_metadata$origin2 = _metadata$origin2._extend) === null || _metadata$origin2 === void 0 ? void 0 : _metadata$origin2.discount_reason
+  }));
+  return mergeManualProductDiscountIntoList(list, buildManualProductDiscountItem({
+    originTotal: originalNum,
+    sellingTotal: sellingNum,
+    quantity: quantity,
+    message: message,
+    discountway: (_metadata$origin3 = metadata.origin) === null || _metadata$origin3 === void 0 || (_metadata$origin3 = _metadata$origin3._extend) === null || _metadata$origin3 === void 0 ? void 0 : _metadata$origin3.discountway,
+    discount_per: (_metadata$origin4 = metadata.origin) === null || _metadata$origin4 === void 0 || (_metadata$origin4 = _metadata$origin4._extend) === null || _metadata$origin4 === void 0 ? void 0 : _metadata$origin4.discount_per
+  }));
+}
+
+/** 商品手动折扣 discount_list 项（checkout 协议，type = product） */
+
+/**
+ * 从 discount_list 中取手动改价项（type = product）。
+ *
+ * @example
+ * const manual = findManualProductDiscountItem(product.discount_list);
+ * manual?.discount.message; // 折扣原因
+ */
+export function findManualProductDiscountItem(discountList) {
+  return (discountList || []).find(function (item) {
+    return (item === null || item === void 0 ? void 0 : item.type) === 'product';
+  });
+}
+
+/**
+ * 解析折扣原因：优先 discount_list[type=product].discount.message。
+ *
+ * @example
+ * resolveManualDiscountMessage(line.discount_list, line.metadata?.legacy_reason);
+ */
+export function resolveManualDiscountMessage(discountList, fallback) {
+  var _findManualProductDis;
+  var message = (_findManualProductDis = findManualProductDiscountItem(discountList)) === null || _findManualProductDis === void 0 || (_findManualProductDis = _findManualProductDis.discount) === null || _findManualProductDis === void 0 ? void 0 : _findManualProductDis.message;
+  if (message != null && String(message).trim() !== '') {
+    return String(message);
+  }
+  return fallback !== null && fallback !== void 0 ? fallback : '';
+}
+
+/** 去掉 discount_list 中已有的手动改价项，避免重复叠加 */
+export function stripManualProductDiscountItems(discountList) {
+  return (discountList || []).filter(function (item) {
+    return (item === null || item === void 0 ? void 0 : item.type) !== 'product';
+  });
+}
+
+/**
+ * 由改价前后行总价构建手动折扣项；amount = |originTotal - sellingTotal|（行级差额）。
+ *
+ * @example
+ * buildManualProductDiscountItem({
+ *   originTotal: 11,
+ *   sellingTotal: 4,
+ *   quantity: 1,
+ *   message: 'VIP',
+ * });
+ */
+export function buildManualProductDiscountItem(params) {
+  var _params$message, _params$discountway, _params$discount_per;
+  var origin = new Decimal(Number(params.originTotal) || 0);
+  var selling = new Decimal(Number(params.sellingTotal) || 0);
+  var diff = origin.minus(selling);
+  var quantity = resolveSafeProductNum(params.quantity);
+  return {
+    amount: diff.toDecimalPlaces(2).toNumber(),
+    type: 'product',
+    discount: {
+      message: (_params$message = params.message) !== null && _params$message !== void 0 ? _params$message : '',
+      discountway: (_params$discountway = params.discountway) !== null && _params$discountway !== void 0 ? _params$discountway : 'num',
+      product_num: quantity,
+      discount_per: (_params$discount_per = params.discount_per) !== null && _params$discount_per !== void 0 ? _params$discount_per : '',
+      discount_type: diff.isNegative() ? 'change_price' : 'discount'
+    }
+  };
+}
+
+/**
+ * 将手动改价项合并进 discount_list（替换已有 type=product 项）。
+ *
+ * @example
+ * mergeManualProductDiscountIntoList(coupons, manualItem);
+ */
+export function mergeManualProductDiscountIntoList(discountList, manualItem) {
+  var base = stripManualProductDiscountItems(discountList);
+  if (!manualItem) return base;
+  if (manualItem.amount === 0 && !manualItem.discount.message) return base;
+  return [].concat(_toConsumableArray(base), [manualItem]);
+}
+
+/** 是否应写入手动改价 discount_list 项 */
+export function shouldBuildManualProductDiscount(params) {
+  return Boolean(params.hasPriceOverride);
+}

package/dist/modules/Order/utils/orderCollectionIdentity.d.ts

@@ -0,0 +1,53 @@
+export type OrderCollectionKind = 'product' | 'booking' | 'payment';
+export interface OrderCollectionIdentityStats {
+    backfilledUidCount: number;
+    collapsedDuplicateCount: number;
+    uidConflictCount: number;
+    anonymousRowCount: number;
+}
+export interface OrderCollectionUidRemap {
+    kind: OrderCollectionKind;
+    from: string;
+    to: string;
+    persistentId: string | null;
+    /** 默认全局迁移；UID 冲突时只能迁移能由另一侧 UID 明确定位的引用。 */
+    scope?: 'global' | 'linked-owner';
+    referenceOwnerUid?: string | null;
+}
+export interface NormalizeOrderCollectionResult<T> {
+    items: T[];
+    stats: OrderCollectionIdentityStats;
+    uidRemaps: OrderCollectionUidRemap[];
+}
+export interface NormalizeOrderCollectionsResult<T> {
+    order: T;
+    stats: Record<OrderCollectionKind, OrderCollectionIdentityStats>;
+    uidRemaps: OrderCollectionUidRemap[];
+}
+export declare function createUuidV4(): string;
+export declare function isBlankOrderCollectionIdentity(value: unknown): boolean;
+export declare function getOrderCollectionPersistentId(kind: OrderCollectionKind, item: unknown): string | null;
+export declare function getOrderCollectionUid(kind: OrderCollectionKind, item: unknown): string | null;
+export declare function buildOrderCollectionFallbackUid(kind: OrderCollectionKind, persistentId: string | number): string;
+export declare function getOrderCollectionReferenceUid(kind: OrderCollectionKind, item: unknown): string | null;
+export declare function setOrderCollectionUid<T>(kind: OrderCollectionKind, item: T, uid: string): T;
+/**
+ * 持久化行 ID 是服务端事实主键；只有至少一侧尚未持久化时，才允许用 runtime UID 对齐。
+ */
+export declare function isSameOrderCollectionItem(kind: OrderCollectionKind, left: unknown, right: unknown): boolean;
+export declare function mergeOrderCollectionItems<T>(kind: OrderCollectionKind, currentItem: T, incomingItem: T, options?: {
+    ensureUid?: boolean;
+    createAnonymousUid?: () => string;
+}): T;
+/**
+ * 规范化单一数组：强身份重复时保留首次位置、用最后一条业务字段覆盖，并统一补 UID。
+ */
+export declare function normalizeOrderCollection<T>(kind: OrderCollectionKind, items: T[] | null | undefined, options?: {
+    ensureUid?: boolean;
+    createAnonymousUid?: () => string;
+}): NormalizeOrderCollectionResult<T>;
+export declare function applyOrderCollectionUidRemaps<T extends Record<string, any>>(sourceOrder: T, uidRemaps: OrderCollectionUidRemap[]): T;
+export declare function normalizeOrderCollections<T extends Record<string, any>>(sourceOrder: T, options?: {
+    ensureUid?: boolean;
+    createAnonymousUid?: () => string;
+}): NormalizeOrderCollectionsResult<T>;