@pisell/pisellos 2.3.29 → 2.3.31

package/lib/modules/Order/index.js

@@ -37,6 +37,8 @@ var import_types = require("./types");
 var import_utils = require("./utils");
 var import_utils2 = require("../Product/utils");
 var import_dayjs = __toESM(require("dayjs"));
+var import_payment_utils = require("./payment-utils");
+var import_payment_number = require("../../utils/payment-number");
 var import_cartPromotion = require("../../solution/BaseSales/utils/cartPromotion");
 var import_utils3 = require("../../solution/ScanOrder/utils");
 var import_manualProductDiscount = require("./utils/manualProductDiscount");
@@ -313,11 +315,11 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       this.store.availableWalletIds = [];
     }
     this.request = this.core.getPlugin("request");
-    const appPlugin = this.core.getPlugin("app");
-    if (!appPlugin) {
+    this.appPlugin = this.core.getPlugin("app");
+    if (!this.appPlugin) {
       throw new Error("Order 模块需要 app 插件支持");
     }
-    const app = appPlugin.getApp();
+    const app = this.appPlugin.getApp();
     this.logger = app.logger;
     this.window = this.core.getPlugin("window");
     const otherParams = options.otherParams || {};
@@ -1053,17 +1055,40 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     const depositPaidAmount = this.calculateDepositPaidAmount(tempOrder.payments || []);
     return depositPaidAmount.lt(depositAmount) ? "deposit" : "normal";
   }
+  getPaymentNumberAppData(key) {
+    var _a, _b, _c, _d, _e;
+    const appPlugin = this.appPlugin;
+    if (!appPlugin)
+      return void 0;
+    const getData = (_a = appPlugin.getData) == null ? void 0 : _a.call(appPlugin);
+    if (typeof getData === "function")
+      return getData(key);
+    const app = appPlugin.getApp();
+    const coreData = (_e = (_c = (_b = app == null ? void 0 : app.models) == null ? void 0 : _b.getStore) == null ? void 0 : (_d = _c.call(_b)).getDataByModel) == null ? void 0 : _e.call(_d, "core", "core");
+    return coreData == null ? void 0 : coreData[key];
+  }
+  getPaymentNumberDevicePrefixSync() {
+    return (0, import_payment_number.resolvePaymentNumberDevicePrefixFromDeviceId)(
+      (key) => this.getPaymentNumberAppData(key)
+    );
+  }
+  getPaymentNumberDevicePrefixAsync() {
+    return (0, import_payment_number.resolvePaymentNumberDevicePrefix)(
+      (key) => this.getPaymentNumberAppData(key)
+    );
+  }
   normalizePaymentSource(payment, options) {
     const paymentRecord = payment;
     const metadata = paymentRecord.metadata && typeof paymentRecord.metadata === "object" ? { ...paymentRecord.metadata } : {};
-    if (!metadata.unique_payment_number) {
-      metadata.unique_payment_number = (0, import_utils.createUuidV4)();
-    }
-    const normalized = {
-      ...paymentRecord,
-      metadata,
-      origin_amount: paymentRecord.origin_amount ?? paymentRecord.amount ?? "0.00"
-    };
+    const normalized = (0, import_payment_utils.ensureOrderPaymentNumber)(
+      {
+        ...paymentRecord,
+        metadata,
+        origin_amount: paymentRecord.origin_amount ?? paymentRecord.amount ?? "0.00"
+      },
+      (options == null ? void 0 : options.devicePrefix) || this.getPaymentNumberDevicePrefixSync(),
+      import_utils.createUuidV4
+    );
     if (paymentRecord.status !== void 0) {
       normalized.status = paymentRecord.status;
     } else if ((options == null ? void 0 : options.defaultPaid) !== false) {
@@ -2484,17 +2509,36 @@ var OrderModule = class extends import_BaseModule.BaseModule {
    * 用一组支付来源覆盖当前订单支付项。
    *
    * 入参允许来自 PaymentModule 的 PaymentItem，内部统一映射为 Sales 协议：
-   * uuid -> metadata.unique_payment_number，id -> custom_payment_id，
+   * 新支付来源的 uuid 会作为 payment_number 的唯一号段，id -> custom_payment_id，
    * isSynced 等运行态字段不会进入 tempOrder.payments。
    */
   setOrderPayments(payments) {
     const tempOrder = this.ensureTempOrder();
-    tempOrder.payments = (0, import_utils.mapPaymentItemsToOrderPayments)(payments);
+    tempOrder.payments = (0, import_utils.mapPaymentItemsToOrderPayments)(
+      (payments || []).map((payment) => this.normalizePaymentSource(payment, { defaultPaid: false }))
+    );
     this.persistTempOrder();
     return tempOrder.payments;
   }
-  /** 追加单个支付项，并立即持久化当前 tempOrder。 */
+  /** 同步兼容入口：按调用当下的 device_id 或 LOCAL 生成支付编号。 */
   addOrderPayment(payment) {
+    const hasPaymentNumber = String(
+      payment.payment_number || ""
+    ).trim() !== "";
+    return this.addOrderPaymentWithDevicePrefix(
+      payment,
+      hasPaymentNumber ? "LOCAL" : this.getPaymentNumberDevicePrefixSync()
+    );
+  }
+  /** 异步入口：创建支付项时读取最新 IoT 设备短号。 */
+  async addOrderPaymentAsync(payment) {
+    const hasPaymentNumber = String(
+      payment.payment_number || ""
+    ).trim() !== "";
+    const devicePrefix = hasPaymentNumber ? "LOCAL" : await this.getPaymentNumberDevicePrefixAsync();
+    return this.addOrderPaymentWithDevicePrefix(payment, devicePrefix);
+  }
+  addOrderPaymentWithDevicePrefix(payment, devicePrefix) {
     this.logInfo("addOrderPayment", {
       payment
     });
@@ -2507,7 +2551,7 @@ var OrderModule = class extends import_BaseModule.BaseModule {
           type: orderPaymentType,
           order_payment_type: orderPaymentType
         },
-        { defaultPaid: true }
+        { defaultPaid: true, devicePrefix }
       )
     ]);
     tempOrder.payments = [...tempOrder.payments || [], ...mapped];
@@ -2520,57 +2564,55 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     return tempOrder.payments;
   }
   /**
-   * 按支付唯一号、后端支付 ID、自定义支付方式 ID 或旧 uuid 更新支付项。
-   *
-   * 该方法服务 PaymentModal 的 void / 编辑场景；更新 metadata 时会做浅合并，
-   * 避免覆盖 unique_payment_number、现金实付/找零等已有元数据。
+   * 默认按支付唯一号精确更新；仅显式指定 legacy 时兼容历史支付标识。
+   * metadata 与 transactions 会分别合并，避免覆盖支付会话号和已有交易记录。
    */
-  updateOrderPayment(paymentIdentity, updates) {
+  async updateOrderPayment(paymentIdentity, updates, options = {}) {
     const tempOrder = this.ensureTempOrder();
     const identity = String(paymentIdentity);
-    tempOrder.payments = (tempOrder.payments || []).map((payment) => {
-      var _a;
-      const uniquePaymentNumber = (_a = payment == null ? void 0 : payment.metadata) == null ? void 0 : _a.unique_payment_number;
-      const orderPaymentId = payment == null ? void 0 : payment.order_payment_id;
-      const customPaymentId = payment == null ? void 0 : payment.custom_payment_id;
-      const uuid = payment == null ? void 0 : payment.uuid;
-      const matched = [
-        uniquePaymentNumber,
-        orderPaymentId,
-        customPaymentId,
-        uuid
-      ].some((value) => value !== void 0 && String(value) === identity);
-      if (!matched)
+    const matchMode = options.matchBy === "compat" || options.matchBy === "legacy" ? "compat" : "payment_number";
+    const matchedPayment = (0, import_payment_utils.resolveOrderPaymentIdentity)(
+      tempOrder.payments || [],
+      identity,
+      matchMode
+    );
+    if (!matchedPayment) {
+      throw new Error(`未找到支付项: ${identity}`);
+    }
+    let updatedPayment = null;
+    tempOrder.payments = (tempOrder.payments || []).map((payment, index) => {
+      if (index !== matchedPayment.index)
         return payment;
-      return {
-        ...payment,
+      const nextPayment = (0, import_payment_utils.mergeOrderPaymentRecord)(payment, {
         ...updates,
-        metadata: {
-          ...payment.metadata || {},
-          ...updates.metadata || {}
-        }
-      };
+        updated_at: updates.updated_at || (0, import_dayjs.default)().format("YYYY-MM-DD HH:mm:ss")
+      });
+      updatedPayment = nextPayment;
+      return nextPayment;
     });
     this.persistTempOrder();
-    return tempOrder.payments;
+    const summary = await this.recalculateSummary({ createIfMissing: true });
+    this.persistTempOrder();
+    const payments = tempOrder.payments;
+    return {
+      updated: true,
+      payment: payments[matchedPayment.index] || updatedPayment,
+      payments,
+      summary
+    };
   }
   /** 从当前订单支付项中移除指定支付项。 */
   deleteOrderPayment(paymentIdentity) {
     const tempOrder = this.ensureTempOrder();
     const identity = String(paymentIdentity);
-    tempOrder.payments = (tempOrder.payments || []).filter((payment) => {
-      var _a;
-      const uniquePaymentNumber = (_a = payment == null ? void 0 : payment.metadata) == null ? void 0 : _a.unique_payment_number;
-      const orderPaymentId = payment == null ? void 0 : payment.order_payment_id;
-      const customPaymentId = payment == null ? void 0 : payment.custom_payment_id;
-      const uuid = payment == null ? void 0 : payment.uuid;
-      return ![
-        uniquePaymentNumber,
-        orderPaymentId,
-        customPaymentId,
-        uuid
-      ].some((value) => value !== void 0 && String(value) === identity);
-    });
+    const matchedPayment = (0, import_payment_utils.resolveOrderPaymentIdentity)(
+      tempOrder.payments || [],
+      identity,
+      "compat"
+    );
+    if (!matchedPayment)
+      return tempOrder.payments;
+    tempOrder.payments = (tempOrder.payments || []).filter((_, index) => index !== matchedPayment.index);
     this.persistTempOrder();
     return tempOrder.payments;
   }
@@ -2679,7 +2721,10 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       payments.map(
         (payment) => this.normalizePaymentSource(
           normalizeVoucherPaymentStatus(withVoucherPaymentType(payment)),
-          { defaultPaid: false }
+          {
+            defaultPaid: false,
+            devicePrefix: options == null ? void 0 : options.devicePrefix
+          }
         )
       )
     ).filter((payment) => {
@@ -2730,6 +2775,14 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     });
     return tempOrder.payments;
   }
+  async updateVoucherOrderPaymentsAsync(payments, options) {
+    const needsPaymentNumber = (payments || []).some((payment) => String(payment.payment_number || "").trim() === "");
+    const devicePrefix = needsPaymentNumber ? await this.getPaymentNumberDevicePrefixAsync() : "LOCAL";
+    return this.updateVoucherOrderPayments(payments, {
+      ...options,
+      devicePrefix
+    });
+  }
   async shouldMergeProductToOrder(params) {
     var _a;
     const onBeforeMergeProductToOrder = (_a = this.orderHooks) == null ? void 0 : _a.onBeforeMergeProductToOrder;
@@ -3496,6 +3549,38 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     await this.saveDraft();
     return tempOrder;
   }
+  async saveTempOrderAsDraft(params) {
+    var _a, _b, _c, _d, _e;
+    const tempOrder = this.ensureTempOrder();
+    this.ensureExternalSaleNumber(tempOrder);
+    this.persistTempOrder();
+    const latestSummary = await this.recalculateSummary({ createIfMissing: true }) || this.store.summary || (0, import_utils.createEmptySummary)();
+    const payload = (0, import_utils.buildSubmitPayload)({
+      tempOrder,
+      cacheId: (params == null ? void 0 : params.cacheId) ?? this.cacheId,
+      platform: (params == null ? void 0 : params.platform) || ((_a = this.otherParams) == null ? void 0 : _a.platform),
+      businessCode: (params == null ? void 0 : params.businessCode) ?? ((_b = this.otherParams) == null ? void 0 : _b.businessCode) ?? ((_c = this.otherParams) == null ? void 0 : _c.business_code),
+      channel: params == null ? void 0 : params.channel,
+      type: (params == null ? void 0 : params.type) ?? ((_d = this.otherParams) == null ? void 0 : _d.type),
+      summary: latestSummary,
+      enhance: params == null ? void 0 : params.enhancePayload
+    });
+    if (!payload.created_at) {
+      payload.created_at = (0, import_dayjs.default)().format("YYYY-MM-DD HH:mm:ss");
+    }
+    payload.need_sync = 0;
+    payload.is_draft_order = 1;
+    this.logInfo("saveTempOrderAsDraft calling sales draft", {
+      orderId: payload.order_id,
+      externalSaleNumber: payload.external_sale_number,
+      productsCount: ((_e = payload.products) == null ? void 0 : _e.length) || 0
+    });
+    return this.request.post("/order/sales/draft", payload, {
+      osServer: true,
+      customToast: () => {
+      }
+    });
+  }
   /**
    * 提交当前 Sales tempOrder。
    *
@@ -3696,8 +3781,13 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   }
   async syncPaymentsToOrder(params) {
     const tempOrder = this.ensureTempOrder();
+    const needsPaymentNumber = (params.payments || []).some((payment) => String(payment.payment_number || "").trim() === "");
+    const devicePrefix = needsPaymentNumber ? await this.getPaymentNumberDevicePrefixAsync() : "LOCAL";
     const mappedPayments = (0, import_utils.mapPaymentItemsToOrderPayments)(
-      params.payments || []
+      (params.payments || []).map((payment) => this.normalizePaymentSource(payment, {
+        defaultPaid: false,
+        devicePrefix
+      }))
     );
     const shouldConfirmPendingVoucherPayments = params.confirmPendingVoucherPayments ?? params.submitWhenPaid === true;
     const effectivePayments = shouldConfirmPendingVoucherPayments ? this.confirmPendingVoucherPaymentsInList(mappedPayments) : params.confirmPendingVoucherPayments === false ? this.discardPendingVoucherPaymentsFromList(mappedPayments) : mappedPayments;
@@ -4073,6 +4163,12 @@ var OrderModule = class extends import_BaseModule.BaseModule {
       }
     }
     const nextTempOrder = this.normalizeTempOrderForRuntime(raw, { makeEditMark: true });
+    const sourceLastOrderInfo = raw.lastOrderInfo || raw;
+    const isDraftOrder = Number(nextTempOrder.is_draft_order || 0) === 1;
+    const syntheticIdentityOptions = {
+      isDraftOrder,
+      externalSaleNumber: nextTempOrder.external_sale_number
+    };
     const rawSummary = raw.summary && typeof raw.summary === "object" ? raw.summary : {};
     const summarySurcharges = Array.isArray(rawSummary.surcharges) ? rawSummary.surcharges.map((s) => ({ ...s || {} })) : (0, import_lodash_es.cloneDeep)(nextTempOrder.surcharges || []);
     this.store.tempOrder = nextTempOrder;
@@ -4093,7 +4189,14 @@ var OrderModule = class extends import_BaseModule.BaseModule {
         productFingerprint: this.buildOrderProductsFingerprint(nextTempOrder.products || [])
       }
     };
-    this.store.lastOrderInfo = sourceRaw.lastOrderInfo || sourceRaw;
+    this.store.lastOrderInfo = this.withoutSyntheticDraftOrderIdForRuntime(
+      sourceLastOrderInfo,
+      syntheticIdentityOptions
+    );
+    const hadSyntheticDraftOrderId = this.isSyntheticDraftOrderIdForRuntime(raw, syntheticIdentityOptions) || this.isSyntheticDraftOrderIdForRuntime(sourceLastOrderInfo, syntheticIdentityOptions);
+    if (hadSyntheticDraftOrderId && this.store.syncState !== "submitting") {
+      this.store.syncState = "local";
+    }
     const hydratedEditDiscounts = this.collectHydratedEditDiscounts(nextTempOrder.products);
     const currentDiscounts = typeof ((_a = this.store.discount) == null ? void 0 : _a.getDiscountList) === "function" ? this.store.discount.getDiscountList() || [] : [];
     const currentScanDiscounts = currentDiscounts.filter((discount) => discount == null ? void 0 : discount.isScan);
@@ -4206,12 +4309,13 @@ var OrderModule = class extends import_BaseModule.BaseModule {
   }
   normalizeTempOrderForRuntime(raw, options) {
     var _a, _b;
+    const runtimeRaw = this.withoutSyntheticDraftOrderIdForRuntime(raw);
     const nextTempOrder = {
       ...this.createDefaultTempOrderInstance(),
-      ...raw || {}
+      ...runtimeRaw || {}
     };
-    if ((nextTempOrder.order_id === void 0 || nextTempOrder.order_id === null) && (raw == null ? void 0 : raw.id) !== void 0 && (raw == null ? void 0 : raw.id) !== null) {
-      nextTempOrder.order_id = raw.id;
+    if ((nextTempOrder.order_id === void 0 || nextTempOrder.order_id === null) && (runtimeRaw == null ? void 0 : runtimeRaw.id) !== void 0 && (runtimeRaw == null ? void 0 : runtimeRaw.id) !== null) {
+      nextTempOrder.order_id = runtimeRaw.id;
     }
     delete nextTempOrder.summary;
     delete nextTempOrder.lastOrderInfo;
@@ -4279,6 +4383,22 @@ var OrderModule = class extends import_BaseModule.BaseModule {
     nextTempOrder.vouchers = raw.vouchers || [];
     return nextTempOrder;
   }
+  isSyntheticDraftOrderIdForRuntime(record, options) {
+    const isDraftOrder = (options == null ? void 0 : options.isDraftOrder) ?? Number((record == null ? void 0 : record.is_draft_order) || 0) === 1;
+    const externalSaleNumber = (record == null ? void 0 : record.external_sale_number) ?? (options == null ? void 0 : options.externalSaleNumber);
+    const orderId = record == null ? void 0 : record.order_id;
+    return Boolean(
+      isDraftOrder && orderId !== void 0 && orderId !== null && orderId !== "" && externalSaleNumber !== void 0 && externalSaleNumber !== null && externalSaleNumber !== "" && String(orderId) === String(externalSaleNumber)
+    );
+  }
+  withoutSyntheticDraftOrderIdForRuntime(record, options) {
+    if (!this.isSyntheticDraftOrderIdForRuntime(record, options))
+      return record;
+    return {
+      ...record,
+      order_id: null
+    };
+  }
   hydrateLinkedBookingIdentity(tempOrder) {
     const bookingUidByProductUid = /* @__PURE__ */ new Map();
     const productByUid = /* @__PURE__ */ new Map();

package/lib/modules/Order/payment-utils.d.ts

@@ -0,0 +1,23 @@
+export type OrderPaymentTransactionStatus = 'success' | 'fail';
+export interface OrderPaymentTransaction {
+    number: string;
+    status: OrderPaymentTransactionStatus;
+}
+export type OrderPaymentIdentityType = 'order_payment_id' | 'payment_number' | 'unique_payment_number';
+export interface OrderPaymentIdentityMatch<T> {
+    index: number;
+    payment: T;
+    matchedBy: OrderPaymentIdentityType;
+}
+export declare function getOrderPaymentIdentityKeys(payment: unknown): string[];
+export declare function hasOrderPaymentIdentityOverlap(left: unknown, right: unknown): boolean;
+export declare function resolveOrderPaymentIdentity<T extends Record<string, any>>(payments: T[] | null | undefined, identity: string | number, mode?: 'payment_number' | 'compat'): OrderPaymentIdentityMatch<T> | null;
+export declare function ensureOrderPaymentNumber<T extends Record<string, any>>(payment: T, devicePrefix: string, createPaymentNumber: () => string): T & {
+    payment_number: string;
+};
+export declare function mergeOrderPaymentTransactions(current: unknown, incoming: unknown): OrderPaymentTransaction[];
+export declare function mergeOrderPaymentRecord<T extends Record<string, any>>(payment: T, updates: Record<string, any>): T;
+export declare function mergeOrderPaymentSnapshot<T extends Record<string, any>>(current: T, incoming: T): T;
+export declare function mergeOrderPaymentListsByIdentity<T extends Record<string, any>>(existing: T[] | null | undefined, incoming: T[] | null | undefined, options?: {
+    preserveUnmatchedExisting?: boolean;
+}): T[];

package/lib/modules/Order/payment-utils.js

@@ -0,0 +1,193 @@
+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/payment-utils.ts
+var payment_utils_exports = {};
+__export(payment_utils_exports, {
+  ensureOrderPaymentNumber: () => ensureOrderPaymentNumber,
+  getOrderPaymentIdentityKeys: () => getOrderPaymentIdentityKeys,
+  hasOrderPaymentIdentityOverlap: () => hasOrderPaymentIdentityOverlap,
+  mergeOrderPaymentListsByIdentity: () => mergeOrderPaymentListsByIdentity,
+  mergeOrderPaymentRecord: () => mergeOrderPaymentRecord,
+  mergeOrderPaymentSnapshot: () => mergeOrderPaymentSnapshot,
+  mergeOrderPaymentTransactions: () => mergeOrderPaymentTransactions,
+  resolveOrderPaymentIdentity: () => resolveOrderPaymentIdentity
+});
+module.exports = __toCommonJS(payment_utils_exports);
+var PAYMENT_IDENTITY_TYPES = [
+  "payment_number",
+  "order_payment_id",
+  "unique_payment_number"
+];
+function normalizePaymentIdentityValue(value) {
+  if (value === void 0 || value === null || value === "")
+    return null;
+  return String(value);
+}
+function getPaymentIdentityValue(payment, type) {
+  var _a;
+  if (type === "unique_payment_number") {
+    return (_a = payment == null ? void 0 : payment.metadata) == null ? void 0 : _a.unique_payment_number;
+  }
+  return payment == null ? void 0 : payment[type];
+}
+function getOrderPaymentIdentityKeys(payment) {
+  const record = payment;
+  if (!record)
+    return [];
+  return PAYMENT_IDENTITY_TYPES.flatMap((type) => {
+    const value = normalizePaymentIdentityValue(getPaymentIdentityValue(record, type));
+    return value === null ? [] : [`${type}:${value}`];
+  });
+}
+function hasOrderPaymentIdentityOverlap(left, right) {
+  const leftKeys = new Set(getOrderPaymentIdentityKeys(left));
+  if (leftKeys.size === 0)
+    return false;
+  return getOrderPaymentIdentityKeys(right).some((key) => leftKeys.has(key));
+}
+function resolveOrderPaymentIdentity(payments, identity, mode = "payment_number") {
+  const target = String(identity);
+  const identityTypes = mode === "payment_number" ? ["payment_number"] : PAYMENT_IDENTITY_TYPES;
+  const matchesByIndex = /* @__PURE__ */ new Map();
+  for (const type of identityTypes) {
+    (payments || []).forEach((payment, index) => {
+      const value = normalizePaymentIdentityValue(getPaymentIdentityValue(payment, type));
+      if (value === target && !matchesByIndex.has(index)) {
+        matchesByIndex.set(index, { index, payment, matchedBy: type });
+      }
+    });
+  }
+  const matches = [...matchesByIndex.values()];
+  if (matches.length > 1) {
+    throw new Error(`支付项身份存在歧义: ${target}`);
+  }
+  return matches[0] || null;
+}
+function ensureOrderPaymentNumber(payment, devicePrefix, createPaymentNumber) {
+  const existing = normalizePaymentIdentityValue(payment.payment_number);
+  if (existing)
+    return { ...payment, payment_number: existing };
+  const uuid = normalizePaymentIdentityValue(payment.uuid) || createPaymentNumber();
+  const prefix = normalizePaymentIdentityValue(devicePrefix) || "LOCAL";
+  return { ...payment, payment_number: `${prefix}_${uuid}` };
+}
+function mergeOrderPaymentTransactions(current, incoming) {
+  const records = /* @__PURE__ */ new Map();
+  const append = (value) => {
+    if (!Array.isArray(value))
+      return;
+    value.forEach((item) => {
+      const number = item && typeof item === "object" ? String(item.number || "") : "";
+      const status = item && typeof item === "object" ? item.status : void 0;
+      if (!number || status !== "success" && status !== "fail")
+        return;
+      const previous = records.get(number);
+      if ((previous == null ? void 0 : previous.status) === "success" && status === "fail")
+        return;
+      records.set(number, { number, status });
+    });
+  };
+  append(current);
+  append(incoming);
+  return [...records.values()];
+}
+function mergeOrderPaymentRecord(payment, updates) {
+  const currentMetadata = payment.metadata || {};
+  const incomingMetadata = updates.metadata || {};
+  const transactions = mergeOrderPaymentTransactions(
+    currentMetadata.transactions,
+    incomingMetadata.transactions
+  );
+  const currentPaid = payment.status === "paid";
+  const nextStatus = currentPaid && updates.status !== "paid" ? "paid" : updates.status ?? payment.status;
+  return {
+    ...payment,
+    ...updates,
+    status: nextStatus,
+    updated_at: updates.updated_at ?? payment.updated_at,
+    metadata: {
+      ...currentMetadata,
+      ...incomingMetadata,
+      ...transactions.length > 0 || Array.isArray(incomingMetadata.transactions) ? { transactions } : {}
+    }
+  };
+}
+function mergeOrderPaymentSnapshot(current, incoming) {
+  const currentMetadata = current.metadata || {};
+  const incomingMetadata = incoming.metadata || {};
+  const transactions = mergeOrderPaymentTransactions(
+    currentMetadata.transactions,
+    incomingMetadata.transactions
+  );
+  return {
+    ...current,
+    ...incoming,
+    payment_number: incoming.payment_number || current.payment_number,
+    metadata: {
+      ...currentMetadata,
+      ...incomingMetadata,
+      ...transactions.length > 0 ? { transactions } : {}
+    }
+  };
+}
+function compactOrderPaymentList(payments) {
+  const result = [];
+  for (const payment of payments) {
+    const matchingIndexes = result.flatMap((existing, index) => hasOrderPaymentIdentityOverlap(existing, payment) ? [index] : []);
+    if (matchingIndexes.length === 0) {
+      result.push(mergeOrderPaymentSnapshot({}, payment));
+      continue;
+    }
+    const firstIndex = matchingIndexes[0];
+    let merged = result[firstIndex];
+    for (const index of matchingIndexes.slice(1)) {
+      merged = mergeOrderPaymentSnapshot(merged, result[index]);
+    }
+    result[firstIndex] = mergeOrderPaymentSnapshot(merged, payment);
+    for (const index of matchingIndexes.slice(1).sort((a, b) => b - a)) {
+      result.splice(index, 1);
+    }
+  }
+  return result;
+}
+function mergeOrderPaymentListsByIdentity(existing, incoming, options = {}) {
+  const existingList = compactOrderPaymentList([...existing || []]);
+  const incomingList = compactOrderPaymentList([...incoming || []]);
+  if (options.preserveUnmatchedExisting) {
+    return compactOrderPaymentList([...existingList, ...incomingList]);
+  }
+  return compactOrderPaymentList(incomingList.map((incomingPayment) => {
+    const matchingExisting = existingList.filter((existingPayment) => hasOrderPaymentIdentityOverlap(existingPayment, incomingPayment));
+    return matchingExisting.reduce(
+      (merged, existingPayment) => mergeOrderPaymentSnapshot(existingPayment, merged),
+      incomingPayment
+    );
+  }));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ensureOrderPaymentNumber,
+  getOrderPaymentIdentityKeys,
+  hasOrderPaymentIdentityOverlap,
+  mergeOrderPaymentListsByIdentity,
+  mergeOrderPaymentRecord,
+  mergeOrderPaymentSnapshot,
+  mergeOrderPaymentTransactions,
+  resolveOrderPaymentIdentity
+});

package/lib/modules/Order/types.d.ts

@@ -468,6 +468,8 @@ export interface SubmitSalesOrderParams {
 export interface PaymentItemData {
     /** 当前支付项的唯一 ID */
     uuid: string;
+    /** 支付项稳定唯一号 */
+    payment_number?: string;
     /** 当前支付方式付出去多少钱 */
     amount: string;
     /** 支付类型代码 */
@@ -490,13 +492,22 @@ export interface PaymentItemData {
 export interface OrderPaymentMetadata {
     rounding_rule?: Record<string, any>;
     unique_payment_number?: string;
+    /** 刷卡机设备快照；OS 不解析内部字段，仅透传并持久化 */
+    card_reader_snapshot?: Record<string, unknown>;
     shop_wallet_pass_id?: number | string;
     actual_paid_amount?: number | string;
     change_given_amount?: number | string;
+    transactions?: OrderPaymentTransaction[];
     [key: string]: any;
 }
+export interface OrderPaymentTransaction {
+    number: string;
+    status: 'success' | 'fail';
+}
 export interface OrderPaymentData {
     order_payment_id?: number | string;
+    /** 支付项稳定唯一号；历史支付项允许缺失 */
+    payment_number?: string;
     amount: string;
     code: string;
     custom_payment_id: number;
@@ -523,6 +534,15 @@ export interface OrderPaymentData {
     created_at?: string;
     updated_at?: string;
 }
+export interface OrderPaymentUpdateOptions {
+    matchBy?: 'payment_number' | 'compat' | 'legacy';
+}
+export interface OrderPaymentUpdateResult {
+    updated: boolean;
+    payment: OrderPaymentData | null;
+    payments: OrderPaymentData[];
+    summary: OrderSummary | null;
+}
 export type OrderPaymentSource = PaymentItem | OrderPaymentData | Record<string, any>;
 export interface MapOrderPaymentsOptions {
     includeVoided?: boolean;
@@ -673,6 +693,14 @@ export interface OrderModuleAPI {
         channel?: string;
         type?: string;
     }) => OrderSubmitPayload;
+    saveTempOrderAsDraft: <T = any>(params?: {
+        cacheId?: string;
+        platform?: string;
+        businessCode?: string;
+        channel?: string;
+        type?: string;
+        enhancePayload?: SubmitPayloadEnhancer;
+    }) => Promise<T>;
     applyLocalPrintOrderNumbers: (order?: Record<string, any> | null) => Promise<OrderTempOrder>;
     getTempOrderNote: () => string;
     updateTempOrderNote: {
@@ -730,11 +758,15 @@ export interface OrderModuleAPI {
     getOrderPayments: () => OrderPaymentData[];
     setOrderPayments: (payments: OrderPaymentSource[]) => OrderPaymentData[];
     addOrderPayment: (payment: OrderPaymentSource) => OrderPaymentData[];
-    updateOrderPayment: (paymentIdentity: string | number, updates: Partial<OrderPaymentData> & Record<string, any>) => OrderPaymentData[];
+    addOrderPaymentAsync: (payment: OrderPaymentSource) => Promise<OrderPaymentData[]>;
+    updateOrderPayment: (paymentIdentity: string | number, updates: Partial<OrderPaymentData> & Record<string, any>, options?: OrderPaymentUpdateOptions) => Promise<OrderPaymentUpdateResult>;
     deleteOrderPayment: (paymentIdentity: string | number) => OrderPaymentData[];
     updateVoucherOrderPayments: (payments: OrderPaymentSource[], options?: {
         status?: 'paid' | 'payment_pending';
     }) => OrderPaymentData[];
+    updateVoucherOrderPaymentsAsync: (payments: OrderPaymentSource[], options?: {
+        status?: 'paid' | 'payment_pending';
+    }) => Promise<OrderPaymentData[]>;
     confirmPendingVoucherPayments: (options?: {
         persist?: boolean;
         recalculateSummary?: boolean;