@pisell/pisellos 0.0.568 → 0.10.1

package/lib/modules/Order/types.js

@@ -1,26 +1,37 @@
-"use strict";
+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);
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
+// src/modules/Order/types.ts
+var types_exports = {};
+__export(types_exports, {
+  OrderHooks: () => OrderHooks
+});
+module.exports = __toCommonJS(types_exports);
+var OrderHooks = /* @__PURE__ */ ((OrderHooks2) => {
+  OrderHooks2["OnOrderCreate"] = "order:onOrderCreate";
+  OrderHooks2["OnOrderUpdate"] = "order:onOrderUpdate";
+  OrderHooks2["OnOrderCancel"] = "order:onOrderCancel";
+  OrderHooks2["OnOrderStatusChange"] = "order:onOrderStatusChange";
+  OrderHooks2["OnOrderCustomerChange"] = "order:onOrderCustomerChange";
+  OrderHooks2["OnPromotionApplied"] = "order:onPromotionApplied";
+  return OrderHooks2;
+})(OrderHooks || {});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OrderHooks
 });
-exports.OrderHooks = void 0;
-let OrderHooks = exports.OrderHooks = /*#__PURE__*/function (OrderHooks) {
-  OrderHooks["OnOrderCreate"] = "order:onOrderCreate";
-  OrderHooks["OnOrderUpdate"] = "order:onOrderUpdate";
-  OrderHooks["OnOrderCancel"] = "order:onOrderCancel";
-  OrderHooks["OnOrderStatusChange"] = "order:onOrderStatusChange";
-  return OrderHooks;
-}({});
-/** 更新购物车行：仅传 SKU 时命中同 SKU 第一行；多行同 SKU 须传 identity_key / 选项指纹等 */
-/**
- * 订单信息
- */
-/**
- * 支付项数据
- */
-/**
- * Checkout 专用订单创建参数
- */
-/**
- * 订单模块 API
- */

package/lib/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/lib/modules/Order/utils/bundleDiscountHydration.js

@@ -0,0 +1,139 @@
+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);
+
+// src/modules/Order/utils/bundleDiscountHydration.ts
+var bundleDiscountHydration_exports = {};
+__export(bundleDiscountHydration_exports, {
+  expandHydratedProductsForDiscountCollection: () => expandHydratedProductsForDiscountCollection,
+  restoreHydratedBundleDiscounts: () => restoreHydratedBundleDiscounts
+});
+module.exports = __toCommonJS(bundleDiscountHydration_exports);
+var BUNDLE_MAP_ID_KEY = "custom_product_bundle_map_id";
+function getBundleMapId(bundle) {
+  var _a;
+  const metadataMapId = (_a = bundle == null ? void 0 : bundle.metadata) == null ? void 0 : _a[BUNDLE_MAP_ID_KEY];
+  if (metadataMapId !== void 0 && metadataMapId !== null && metadataMapId !== "") {
+    return String(metadataMapId);
+  }
+  if ((bundle == null ? void 0 : bundle._id) !== void 0 && bundle._id !== null && bundle._id !== "") {
+    return String(bundle._id);
+  }
+  return null;
+}
+function getDiscountBundleMapId(discount) {
+  var _a;
+  const mapId = (_a = discount == null ? void 0 : discount.metadata) == null ? void 0 : _a[BUNDLE_MAP_ID_KEY];
+  if (mapId === void 0 || mapId === null || mapId === "")
+    return null;
+  return String(mapId);
+}
+function hasSameBundleDiscount(discountList, discount) {
+  var _a;
+  const targetOrderDiscountId = discount.order_discount_id;
+  if (targetOrderDiscountId !== void 0 && targetOrderDiscountId !== null) {
+    return discountList.some((item) => (item == null ? void 0 : item.order_discount_id) === targetOrderDiscountId);
+  }
+  const targetResourceId = ((_a = discount == null ? void 0 : discount.discount) == null ? void 0 : _a.resource_id) ?? (discount == null ? void 0 : discount.resource_id) ?? (discount == null ? void 0 : discount.discount_id);
+  const targetMapId = getDiscountBundleMapId(discount);
+  return discountList.some((item) => {
+    var _a2;
+    const resourceId = ((_a2 = item == null ? void 0 : item.discount) == null ? void 0 : _a2.resource_id) ?? (item == null ? void 0 : item.resource_id) ?? (item == null ? void 0 : item.discount_id);
+    return resourceId === targetResourceId && String((item == null ? void 0 : item.amount) ?? "") === String((discount == null ? void 0 : discount.amount) ?? "") && getDiscountBundleMapId(item) === targetMapId;
+  });
+}
+function restoreHydratedBundleDiscounts(product, normalizeDiscountList) {
+  if (!Array.isArray(product.product_bundle) || !Array.isArray(product.discount_list)) {
+    return product;
+  }
+  const bundleByMapId = /* @__PURE__ */ new Map();
+  product.product_bundle.forEach((bundle) => {
+    if (!bundle || typeof bundle !== "object")
+      return;
+    const mapId = getBundleMapId(bundle);
+    if (mapId)
+      bundleByMapId.set(mapId, bundle);
+  });
+  if (!bundleByMapId.size)
+    return product;
+  const mainDiscountList = [];
+  const bundleDiscounts = [];
+  product.discount_list.forEach((discount) => {
+    const mapId = getDiscountBundleMapId(discount);
+    if (mapId && bundleByMapId.has(mapId)) {
+      bundleDiscounts.push({ mapId, discount });
+    } else {
+      mainDiscountList.push(discount);
+    }
+  });
+  if (!bundleDiscounts.length)
+    return product;
+  return {
+    ...product,
+    discount_list: normalizeDiscountList(mainDiscountList),
+    product_bundle: product.product_bundle.map((bundle) => {
+      if (!bundle || typeof bundle !== "object")
+        return bundle;
+      const mapId = getBundleMapId(bundle);
+      if (!mapId)
+        return bundle;
+      const matchedDiscounts = bundleDiscounts.filter((item) => item.mapId === mapId).map((item) => item.discount);
+      if (!matchedDiscounts.length)
+        return bundle;
+      const currentDiscountList = Array.isArray(bundle.discount_list) ? [...bundle.discount_list] : [];
+      for (const discount of matchedDiscounts) {
+        if (!hasSameBundleDiscount(currentDiscountList, discount)) {
+          currentDiscountList.push(discount);
+        }
+      }
+      return {
+        ...bundle,
+        discount_list: normalizeDiscountList(currentDiscountList),
+        metadata: {
+          ...bundle.metadata || {},
+          [BUNDLE_MAP_ID_KEY]: mapId
+        }
+      };
+    })
+  };
+}
+function expandHydratedProductsForDiscountCollection(products) {
+  const expanded = [];
+  for (const product of products || []) {
+    expanded.push(product);
+    for (const bundle of (product == null ? void 0 : product.product_bundle) || []) {
+      if (!Array.isArray(bundle == null ? void 0 : bundle.discount_list) || bundle.discount_list.length === 0)
+        continue;
+      expanded.push({
+        ...product,
+        product_id: bundle.bundle_product_id ?? bundle._bundle_product_id ?? bundle.product_id ?? (product == null ? void 0 : product.product_id),
+        num: bundle.num ?? bundle.quantity ?? (product == null ? void 0 : product.num),
+        product_quantity: bundle.quantity ?? bundle.num ?? (product == null ? void 0 : product.product_quantity),
+        original_price: bundle.original_price ?? bundle.product_price ?? bundle.price,
+        selling_price: bundle.bundle_selling_price ?? bundle.price,
+        is_charge_tax: bundle.is_charge_tax ?? (product == null ? void 0 : product.is_charge_tax),
+        discount_list: bundle.discount_list
+      });
+    }
+  }
+  return expanded;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  expandHydratedProductsForDiscountCollection,
+  restoreHydratedBundleDiscounts
+});

package/lib/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/lib/modules/Order/utils/manualProductDiscount.js

@@ -0,0 +1,206 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/modules/Order/utils/manualProductDiscount.ts
+var manualProductDiscount_exports = {};
+__export(manualProductDiscount_exports, {
+  buildManualProductDiscountItem: () => buildManualProductDiscountItem,
+  ensureManualProductDiscountList: () => ensureManualProductDiscountList,
+  findManualProductDiscountItem: () => findManualProductDiscountItem,
+  hasManualProductDiscountFlag: () => hasManualProductDiscountFlag,
+  mergeManualProductDiscountIntoList: () => mergeManualProductDiscountIntoList,
+  resolveManualDiscountMessage: () => resolveManualDiscountMessage,
+  resolveManualDiscountOriginTotal: () => resolveManualDiscountOriginTotal,
+  resolveManualDiscountReasonFromSources: () => resolveManualDiscountReasonFromSources,
+  resolveSafeProductNum: () => resolveSafeProductNum,
+  shouldBuildManualProductDiscount: () => shouldBuildManualProductDiscount,
+  stripManualProductDiscountItems: () => stripManualProductDiscountItems,
+  syncManualProductDiscountProductNum: () => syncManualProductDiscountProductNum
+});
+module.exports = __toCommonJS(manualProductDiscount_exports);
+var import_decimal = __toESM(require("decimal.js"));
+function resolveSafeProductNum(num) {
+  const parsed = Number(num);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    return 1;
+  return Math.floor(parsed);
+}
+function syncManualProductDiscountProductNum(discountList, productNum) {
+  const quantity = resolveSafeProductNum(productNum);
+  return (discountList || []).map((item) => {
+    if ((item == null ? void 0 : item.type) !== "product")
+      return item;
+    return {
+      ...item,
+      discount: {
+        ...item.discount || {},
+        product_num: quantity
+      }
+    };
+  });
+}
+function resolveManualDiscountOriginTotal(sources) {
+  const candidates = [
+    sources.originTotal,
+    sources.extendOriginTotal,
+    sources.originExtendOriginTotal,
+    sources.sourceExtendOriginTotal
+  ];
+  for (const candidate of candidates) {
+    if (candidate === void 0 || candidate === null || candidate === "")
+      continue;
+    const parsed = Number(candidate);
+    if (Number.isFinite(parsed))
+      return parsed;
+  }
+  const unit = Number(sources.catalogUnitPrice);
+  const quantity = sources.quantity ?? 1;
+  if (Number.isFinite(unit) && unit > 0) {
+    return new import_decimal.default(unit).mul(quantity).toNumber();
+  }
+  return NaN;
+}
+function resolveManualDiscountReasonFromSources(sources) {
+  for (const candidate of [
+    sources.discountReason,
+    sources.extendDiscountReason,
+    sources.originExtendDiscountReason
+  ]) {
+    if (candidate != null && String(candidate).trim() !== "") {
+      return String(candidate);
+    }
+  }
+  return "";
+}
+function hasManualProductDiscountFlag(metadata) {
+  if (!metadata)
+    return false;
+  const override = metadata.price_override;
+  if (override !== void 0 && override !== null && override !== "") {
+    return true;
+  }
+  return metadata.is_manual_discount === 1 || metadata.is_manual_discount === true;
+}
+function ensureManualProductDiscountList(params) {
+  var _a, _b, _c, _d, _e, _f, _g, _h;
+  const list = params.discountList || [];
+  const quantity = resolveSafeProductNum(params.quantity);
+  if (findManualProductDiscountItem(list)) {
+    return syncManualProductDiscountProductNum(list, quantity);
+  }
+  const metadata = params.metadata || {};
+  const originalNum = Number(params.originalPrice);
+  const sellingNum = Number(params.sellingPrice);
+  const hasPriceOverride = hasManualProductDiscountFlag(metadata);
+  const shouldBuild = shouldBuildManualProductDiscount({
+    hasPriceOverride,
+    originTotal: originalNum,
+    sellingTotal: sellingNum
+  });
+  if (!shouldBuild) {
+    return list;
+  }
+  if (!Number.isFinite(originalNum) || !Number.isFinite(sellingNum) || originalNum === sellingNum) {
+    return list;
+  }
+  const message = resolveManualDiscountMessage(
+    list,
+    resolveManualDiscountReasonFromSources({
+      extendDiscountReason: (_b = (_a = metadata.origin) == null ? void 0 : _a._extend) == null ? void 0 : _b.discount_reason,
+      originExtendDiscountReason: (_d = (_c = metadata.origin) == null ? void 0 : _c._extend) == null ? void 0 : _d.discount_reason
+    })
+  );
+  return mergeManualProductDiscountIntoList(
+    list,
+    buildManualProductDiscountItem({
+      originTotal: originalNum,
+      sellingTotal: sellingNum,
+      quantity,
+      message,
+      discountway: (_f = (_e = metadata.origin) == null ? void 0 : _e._extend) == null ? void 0 : _f.discountway,
+      discount_per: (_h = (_g = metadata.origin) == null ? void 0 : _g._extend) == null ? void 0 : _h.discount_per
+    })
+  );
+}
+function findManualProductDiscountItem(discountList) {
+  return (discountList || []).find((item) => (item == null ? void 0 : item.type) === "product");
+}
+function resolveManualDiscountMessage(discountList, fallback) {
+  var _a, _b;
+  const message = (_b = (_a = findManualProductDiscountItem(discountList)) == null ? void 0 : _a.discount) == null ? void 0 : _b.message;
+  if (message != null && String(message).trim() !== "") {
+    return String(message);
+  }
+  return fallback ?? "";
+}
+function stripManualProductDiscountItems(discountList) {
+  return (discountList || []).filter((item) => (item == null ? void 0 : item.type) !== "product");
+}
+function buildManualProductDiscountItem(params) {
+  const origin = new import_decimal.default(Number(params.originTotal) || 0);
+  const selling = new import_decimal.default(Number(params.sellingTotal) || 0);
+  const diff = origin.minus(selling);
+  const quantity = resolveSafeProductNum(params.quantity);
+  return {
+    amount: diff.toDecimalPlaces(2).toNumber(),
+    type: "product",
+    discount: {
+      message: params.message ?? "",
+      discountway: params.discountway ?? "num",
+      product_num: quantity,
+      discount_per: params.discount_per ?? "",
+      discount_type: diff.isNegative() ? "change_price" : "discount"
+    }
+  };
+}
+function mergeManualProductDiscountIntoList(discountList, manualItem) {
+  const base = stripManualProductDiscountItems(discountList);
+  if (!manualItem)
+    return base;
+  if (manualItem.amount === 0 && !manualItem.discount.message)
+    return base;
+  return [...base, manualItem];
+}
+function shouldBuildManualProductDiscount(params) {
+  return Boolean(params.hasPriceOverride);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  buildManualProductDiscountItem,
+  ensureManualProductDiscountList,
+  findManualProductDiscountItem,
+  hasManualProductDiscountFlag,
+  mergeManualProductDiscountIntoList,
+  resolveManualDiscountMessage,
+  resolveManualDiscountOriginTotal,
+  resolveManualDiscountReasonFromSources,
+  resolveSafeProductNum,
+  shouldBuildManualProductDiscount,
+  stripManualProductDiscountItems,
+  syncManualProductDiscountProductNum
+});

package/lib/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>;