@pisell/pisellos 2.3.100 → 2.3.102

package/lib/modules/Order/index.js

@@ -18,6 +18,7 @@ var _manualProductDiscount = require("./utils/manualProductDiscount");
 var _bundleDiscountHydration = require("./utils/bundleDiscountHydration");
 var _orderCollectionIdentity = require("./utils/orderCollectionIdentity");
 var _discountProductLineIdentity = require("./utils/discountProductLineIdentity");
+var _virtualSettlement = require("./utils/virtualSettlement");
 var _Discount = require("../Discount");
 var _Rules = require("../Rules");
 var _types2 = require("../Rules/types");
@@ -298,6 +299,7 @@ class OrderModule extends _BaseModule.BaseModule {
       this.store.tempOrder = null;
       this.store.summary = (0, _utils.createEmptySummary)();
       this.store.availableWalletIds = [];
+      this.store.virtualCurrencyList = [];
       this.store.lastOrderInfo = undefined;
       this.store.syncState = undefined;
       this.store.discountList = [];
@@ -310,6 +312,9 @@ class OrderModule extends _BaseModule.BaseModule {
     if (!Array.isArray(this.store.availableWalletIds)) {
       this.store.availableWalletIds = [];
     }
+    if (!Array.isArray(this.store.virtualCurrencyList)) {
+      this.store.virtualCurrencyList = [];
+    }
     this.request = this.core.getPlugin('request');
     const appPlugin = this.core.getPlugin('app');
     if (!appPlugin) {
@@ -364,6 +369,12 @@ class OrderModule extends _BaseModule.BaseModule {
     this.otherParams = otherParams;
   }
 
+  /** PC/H5 属于在线店铺；其它或缺失平台统一沿用 POS 行为。 */
+  isOnlineStorePlatform() {
+    const platform = String(this.otherParams?.platform || '').trim().toLowerCase();
+    return platform === 'pc' || platform === 'h5';
+  }
+
   /**
    * 记录信息日志
    */
@@ -451,6 +462,7 @@ class OrderModule extends _BaseModule.BaseModule {
       with_wallet_pass_holder: 1,
       with_available_wallet_flag: 1,
       with_available_wallet_pass_flag: 1,
+      with_virtual_currency: 1,
       request_timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
       ...(orderId ? {
         order_id: orderId
@@ -458,6 +470,7 @@ class OrderModule extends _BaseModule.BaseModule {
     });
     const discountList = prepareConfigResult?.discountList;
     this.store.availableWalletIds = prepareConfigResult?.availableWalletIds || [];
+    this.store.virtualCurrencyList = prepareConfigResult?.virtualCurrencyList || [];
     if (discountList) {
       const currentDiscountList = this.store.discount?.getDiscountList() || [];
       const currentEditDiscounts = currentDiscountList.filter(discount => discount?.isEditMode);
@@ -485,6 +498,9 @@ class OrderModule extends _BaseModule.BaseModule {
   getAvailableWalletIds() {
     return Array.isArray(this.store.availableWalletIds) ? [...this.store.availableWalletIds] : [];
   }
+  getVirtualCurrencyList() {
+    return (0, _lodashEs.cloneDeep)(this.store.virtualCurrencyList || []);
+  }
   async syncScannedDiscountsToOriginalDiscountList(discountList) {
     const scanDiscounts = (discountList || []).filter(discount => discount?.isScan);
     if (!scanDiscounts.length) return;
@@ -508,6 +524,16 @@ class OrderModule extends _BaseModule.BaseModule {
     });
   }
   async scanCode(code, customerId) {
+    if (this.isActiveVirtualSettlementOrder(this.store.tempOrder)) {
+      return {
+        type: 'clientCalc',
+        isAvailable: false,
+        isAccepted: false,
+        discountList: [],
+        scannedDiscountList: [],
+        unavailableReason: _types2.UnavailableReason.ProductNotApplicable
+      };
+    }
     const resultDiscountWithReason = (await this.store.discount?.batchSearch(code, {
       customerId
     })) || {
@@ -603,6 +629,14 @@ class OrderModule extends _BaseModule.BaseModule {
     // 也需要让 Rules.calcDiscount 把 DiscountModule 的 isSelected / isAvailable /
     // appliedProductDetails / savedAmount 复位。
     if (!tempOrder) return;
+    if (this.isActiveVirtualSettlementOrder(tempOrder)) {
+      tempOrder.products = (0, _virtualSettlement.normalizeVirtualSettlementProducts)(tempOrder.products);
+      tempOrder.discount_list = [];
+      tempOrder.shop_discount = '0.00';
+      void this.store.discount?.setDiscountList([]);
+      void this.store.discount?.setOriginalDiscountList([]);
+      return;
+    }
     this.syncLinkedBookingHoldersToProducts(tempOrder);
     delete tempOrder.discount_list;
     const discountList = this.store.discount?.getDiscountList() || [];
@@ -700,6 +734,10 @@ class OrderModule extends _BaseModule.BaseModule {
     if (!tempOrder) {
       return;
     }
+    if (this.isActiveVirtualSettlementOrder(tempOrder)) {
+      tempOrder.products = (0, _virtualSettlement.normalizeVirtualSettlementProducts)(tempOrder.products);
+      return;
+    }
     const strategyConfigs = this.promotionEvaluator.getStrategyConfigs?.();
     if (Array.isArray(strategyConfigs) && strategyConfigs.length === 0) {
       return;
@@ -1830,7 +1868,8 @@ class OrderModule extends _BaseModule.BaseModule {
     return product;
   }
   sanitizeTempOrderProducts(tempOrder) {
-    tempOrder.products = (tempOrder.products || []).map(product => this.sanitizeOrderProductForTempOrder(product));
+    tempOrder.products = (tempOrder.products || []).map(product => this.sanitizeOrderProductForTempOrder(this.normalizeVirtualSettlementProductIfEnabled(product)));
+    this.syncTempOrderSettlementState(tempOrder);
     (0, _discountProductLineIdentity.ensureUniqueProductLineUids)(tempOrder);
   }
   ensureExtend(tempOrder) {
@@ -2151,6 +2190,7 @@ class OrderModule extends _BaseModule.BaseModule {
       products: summaryProducts,
       isPriceIncludeTax: tempOrder.is_price_include_tax,
       shopDiscount: tempOrder.shop_discount,
+      virtualSettlementMode: this.shouldUseVirtualSettlementSummary(tempOrder),
       ...(this.otherParams?.channel ? {
         channel: this.otherParams.channel
       } : {})
@@ -2619,6 +2659,7 @@ class OrderModule extends _BaseModule.BaseModule {
     const nextCustomerId = tempOrder.customer_id ?? null;
     if (String(previousCustomerId ?? '') !== String(nextCustomerId ?? '')) {
       this.store.availableWalletIds = [];
+      this.store.virtualCurrencyList = [];
       (0, _utils.clearTempOrderHolderAssignments)(tempOrder);
       this.clearCustomerBoundDiscounts(tempOrder);
       this.applyDiscount();
@@ -2657,6 +2698,7 @@ class OrderModule extends _BaseModule.BaseModule {
     tempOrder.customer = null;
     if (tempOrder._extend) delete tempOrder._extend.customerSnapshot;
     this.store.availableWalletIds = [];
+    this.store.virtualCurrencyList = [];
     this.clearCustomerBoundDiscounts(tempOrder);
     this.applyDiscount();
     this.persistTempOrder();
@@ -2976,6 +3018,78 @@ class OrderModule extends _BaseModule.BaseModule {
     const bookingUid = product?.booking_uid ?? product?.metadata?.booking_uid;
     return bookingUid !== undefined && bookingUid !== null && String(bookingUid) !== '';
   }
+  isMultiCurrencySettlementEnabled() {
+    return this.otherParams?.enableMultiCurrencySettlement === true;
+  }
+  isActiveVirtualSettlementOrder(tempOrder) {
+    return this.isMultiCurrencySettlementEnabled() && (0, _virtualSettlement.isVirtualSettlementOrder)(tempOrder);
+  }
+  shouldUseVirtualSettlementSummary(tempOrder) {
+    return this.isActiveVirtualSettlementOrder(tempOrder) || tempOrder?.metadata?.currency_settlement_config?.settlement_type === 'virtual_currency';
+  }
+  normalizeVirtualSettlementProductIfEnabled(product) {
+    return this.isMultiCurrencySettlementEnabled() ? (0, _virtualSettlement.normalizeVirtualSettlementOrderProduct)(product) : product;
+  }
+  assertAndLockProductSettlement(tempOrder, product) {
+    if (!this.isMultiCurrencySettlementEnabled()) return;
+    const currentKey = (0, _virtualSettlement.getTempOrderSettlementKey)(tempOrder);
+    const incomingKey = (0, _virtualSettlement.getSettlementKey)((0, _virtualSettlement.getSelectedSettlementSnapshot)(product)) || 'legal_currency';
+    if (currentKey && currentKey !== incomingKey) {
+      throw new _virtualSettlement.OrderSettlementConflictError(currentKey, incomingKey);
+    }
+    const snapshot = (0, _virtualSettlement.getSelectedSettlementSnapshot)(product);
+    if (snapshot?.settlement_type === 'virtual_currency' && tempOrder.customer_id && Number(tempOrder.customer_id) !== 1) {
+      const currencyProductId = Number(snapshot.currency_product_id);
+      const asset = (this.store.virtualCurrencyList || []).find(item => Number(item?.product_id) === currencyProductId);
+      if (!asset) {
+        throw new _virtualSettlement.VirtualCurrencyAssetNotFoundError(currencyProductId);
+      }
+      const existedAmount = tempOrder.products.reduce((sum, item) => sum.plus(new _decimal.default(item.selling_price || 0).times(item.num || 1)), new _decimal.default(0));
+      const requiredAmount = existedAmount.plus(new _decimal.default(snapshot.price || 0).times(product.num || 1));
+      const balance = new _decimal.default(asset.balance || 0);
+      if (balance.lt(requiredAmount)) {
+        throw new _virtualSettlement.VirtualCurrencyBalanceError(balance.toFixed(2), requiredAmount.toFixed(2));
+      }
+    }
+    (0, _virtualSettlement.applyTempOrderSettlementState)(tempOrder, snapshot || {
+      settlement_type: 'legal_currency',
+      price: product.selling_price ?? product.original_price ?? product.payment_price ?? 0,
+      unit_label: tempOrder.currency_code,
+      symbol: tempOrder.currency_symbol,
+      amount_format: tempOrder.currency_format
+    });
+  }
+  syncTempOrderSettlementState(tempOrder) {
+    if (!this.isMultiCurrencySettlementEnabled()) return;
+    tempOrder.metadata = tempOrder.metadata || {};
+    if (!tempOrder.products.length) {
+      (0, _virtualSettlement.releaseTempOrderSettlementState)(tempOrder);
+      return;
+    }
+    const snapshot = (0, _virtualSettlement.getTempOrderSettlementSnapshot)(tempOrder);
+    if (snapshot) {
+      (0, _virtualSettlement.applyTempOrderSettlementState)(tempOrder, snapshot);
+      return;
+    }
+    tempOrder.metadata.cart_settlement_key = 'legal_currency';
+  }
+  prepareVirtualSettlementTempOrder(tempOrder) {
+    if (!this.isMultiCurrencySettlementEnabled()) return;
+    this.syncTempOrderSettlementState(tempOrder);
+    if (!this.isActiveVirtualSettlementOrder(tempOrder)) return;
+    tempOrder.products = (0, _virtualSettlement.normalizeVirtualSettlementProducts)(tempOrder.products);
+    tempOrder.discount_list = [];
+    tempOrder.shop_discount = '0.00';
+    tempOrder.surcharge_fee = '0.00';
+    tempOrder.surcharges = [];
+    const virtualOrder = tempOrder;
+    virtualOrder.discount_amount = '0.00';
+    virtualOrder.product_tax_fee = '0.00';
+    virtualOrder.tax_fee = '0.00';
+    virtualOrder.shipping_fee = '0.00';
+    virtualOrder.shipping_tax_fee = '0.00';
+    virtualOrder.tip_fee = '0.00';
+  }
 
   // ─── TempOrder: 商品 CRUD ───
 
@@ -2987,13 +3101,15 @@ class OrderModule extends _BaseModule.BaseModule {
    */
   async finalizeProductOrderMutation(tempOrder, options) {
     this.syncTempOrderHolderFromBookings(tempOrder);
-    if (!options?.skipEditDiscountConfigRefresh) {
+    this.prepareVirtualSettlementTempOrder(tempOrder);
+    const isVirtualSettlement = this.isActiveVirtualSettlementOrder(tempOrder);
+    if (!options?.skipEditDiscountConfigRefresh && !isVirtualSettlement) {
       await this.ensureEditDiscountConfigForProductChange(tempOrder);
     }
-    if (!options?.skipDiscountRecalculation) {
+    if (!options?.skipDiscountRecalculation && !isVirtualSettlement) {
       await this.applyPromotion();
     }
-    if (!options?.skipDiscountRecalculation) {
+    if (!options?.skipDiscountRecalculation && !isVirtualSettlement) {
       this.applyDiscount();
     }
     this.sanitizeTempOrderProducts(tempOrder);
@@ -3021,9 +3137,10 @@ class OrderModule extends _BaseModule.BaseModule {
       booking
     }) : null;
     const productToAdd = linked?.product || product;
+    this.assertAndLockProductSettlement(tempOrder, productToAdd);
     const disableMerge = options?.disableMerge === true;
     const incomingFingerprint = disableMerge ? '' : (0, _utils3.buildProductLineFingerprint)((0, _utils.getProductSkuOptions)(productToAdd), productToAdd.product_bundle);
-    const normalizedIncoming = (0, _utils.mergeOrderProductDisplayFields)(productToAdd, (0, _utils3.normalizeOrderProduct)(productToAdd));
+    const normalizedIncoming = this.normalizeVirtualSettlementProductIfEnabled((0, _utils.mergeOrderProductDisplayFields)(productToAdd, (0, _utils3.normalizeOrderProduct)(productToAdd)));
     if (disableMerge) {
       normalizedIncoming.metadata = {
         ...(normalizedIncoming.metadata || {}),
@@ -3084,13 +3201,13 @@ class OrderModule extends _BaseModule.BaseModule {
       } else {
         const targetProduct = matchedProduct;
         const targetUid = targetProduct.metadata?.unique_identification_number;
-        const normalizedProduct = (0, _utils.mergeOrderProductDisplayFields)(targetProduct, (0, _utils3.normalizeOrderProduct)({
+        const normalizedProduct = this.normalizeVirtualSettlementProductIfEnabled((0, _utils.mergeOrderProductDisplayFields)(targetProduct, (0, _utils3.normalizeOrderProduct)({
           ...productToAdd,
           metadata: {
             ...(productToAdd.metadata || {}),
             unique_identification_number: targetUid
           }
-        }));
+        })));
         normalizedProduct.discount_list = (0, _utils.normalizeOrderProductDiscountList)(normalizedProduct.discount_list);
         const nextNum = (0, _utils3.getSafeProductNum)(targetProduct.num + normalizedProduct.num);
         tempOrder.products[matchedIndex] = {
@@ -3498,7 +3615,7 @@ class OrderModule extends _BaseModule.BaseModule {
     }
     // normalizeOrderProduct 幂等：v2 metadata 存在 → 保留 main_product_* 折扣重算 composite；
     // 否则 → 把顶层 selling_price 视作 source，派生 main_product_* 并写 price_schema_version: 2。
-    let normalizedProduct = (0, _utils.mergeOrderProductDisplayFields)(nextProduct, (0, _utils3.normalizeOrderProduct)(nextProduct));
+    let normalizedProduct = this.normalizeVirtualSettlementProductIfEnabled((0, _utils.mergeOrderProductDisplayFields)(nextProduct, (0, _utils3.normalizeOrderProduct)(nextProduct)));
     normalizedProduct.discount_list = (0, _utils.normalizeOrderProductDiscountList)(normalizedProduct.discount_list);
     const preservedBookingUid = nextProduct.booking_uid || nextProduct.metadata?.booking_uid || targetProduct.booking_uid || targetProduct.metadata?.booking_uid;
     if (!booking && preservedBookingUid) {
@@ -3615,18 +3732,38 @@ class OrderModule extends _BaseModule.BaseModule {
       throw new Error('[Order] 目标商品不存在，无法更新数量');
     }
     const targetProduct = tempOrder.products[productIndex];
-    const normalizedProduct = (0, _utils3.normalizeOrderProduct)({
+    const normalizedProduct = this.normalizeVirtualSettlementProductIfEnabled((0, _utils3.normalizeOrderProduct)({
       ...targetProduct,
       num: (0, _utils3.getSafeProductNum)(num),
       metadata: {
         ...(targetProduct.metadata || {}),
         unique_identification_number: targetProduct.metadata?.unique_identification_number || unique_identification_number
       }
-    });
+    }));
     normalizedProduct.discount_list = (0, _utils.normalizeOrderProductDiscountList)(normalizedProduct.discount_list);
+    const settlementSnapshot = (0, _virtualSettlement.getSelectedSettlementSnapshot)(normalizedProduct);
+    if (this.isMultiCurrencySettlementEnabled() && settlementSnapshot?.settlement_type === 'virtual_currency' && tempOrder.customer_id && Number(tempOrder.customer_id) !== 1) {
+      const currencyProductId = Number(settlementSnapshot.currency_product_id);
+      const asset = (this.store.virtualCurrencyList || []).find(item => Number(item?.product_id) === currencyProductId);
+      if (!asset) {
+        throw new _virtualSettlement.VirtualCurrencyAssetNotFoundError(currencyProductId);
+      }
+      const requiredAmount = tempOrder.products.reduce((sum, item, index) => {
+        const current = index === productIndex ? normalizedProduct : item;
+        const currentSnapshot = (0, _virtualSettlement.getSelectedSettlementSnapshot)(current);
+        return sum.plus(new _decimal.default(currentSnapshot?.price || current.selling_price || 0).times(current.num || 1));
+      }, new _decimal.default(0));
+      const balance = new _decimal.default(asset.balance || 0);
+      if (balance.lt(requiredAmount)) {
+        throw new _virtualSettlement.VirtualCurrencyBalanceError(balance.toFixed(2), requiredAmount.toFixed(2));
+      }
+    }
     tempOrder.products[productIndex] = normalizedProduct;
-    await this.applyPromotion();
-    this.applyDiscount();
+    this.prepareVirtualSettlementTempOrder(tempOrder);
+    if (!this.isActiveVirtualSettlementOrder(tempOrder)) {
+      await this.applyPromotion();
+      this.applyDiscount();
+    }
     this.sanitizeTempOrderProducts(tempOrder);
     await this.recalculateSummary({
       createIfMissing: true
@@ -3780,6 +3917,7 @@ class OrderModule extends _BaseModule.BaseModule {
     this.ensureSalesNotesLoadedForMutation(tempOrder);
     tempOrder.products = [];
     tempOrder.bookings = [];
+    (0, _virtualSettlement.releaseTempOrderSettlementState)(tempOrder);
     this.removeSalesNotesForMissingProductLines(tempOrder);
     this.syncTempOrderHolderFromBookings(tempOrder);
     if (tempOrder._extend && typeof tempOrder._extend === 'object') {
@@ -3799,6 +3937,41 @@ class OrderModule extends _BaseModule.BaseModule {
     return tempOrder;
   }
 
+  /**
+   * 切换购物车结算单位时清理所有会影响新币种的订单状态，但保留当前客户。
+   */
+  async clearOrderForSettlementSwitch() {
+    const tempOrder = this.ensureTempOrder();
+    this.ensureSalesNotesLoadedForMutation(tempOrder);
+    tempOrder.products = [];
+    tempOrder.bookings = [];
+    this.removeSalesNotesForMissingProductLines(tempOrder);
+    tempOrder.discount_list = [];
+    tempOrder.payments = [];
+    tempOrder.refunds = [];
+    tempOrder.shop_discount = '0.00';
+    tempOrder.surcharges = [];
+    (0, _virtualSettlement.releaseTempOrderSettlementState)(tempOrder);
+    this.syncTempOrderHolderFromBookings(tempOrder);
+    if (tempOrder._extend && typeof tempOrder._extend === 'object') {
+      tempOrder._extend = {
+        ...tempOrder._extend,
+        productsByUid: {}
+      };
+    }
+    await this.store.discount?.setDiscountList([]);
+    await this.store.discount?.setOriginalDiscountList([]);
+    this.hasActiveCustomerBoundDiscount = false;
+    this.lastUnfulfilledPromotions = [];
+    this.lastGiftActions = null;
+    await this.recalculateSummary({
+      createIfMissing: true
+    });
+    this.persistTempOrder();
+    this.logInfo('clearOrderForSettlementSwitch success', {});
+    return tempOrder;
+  }
+
   // ─── TempOrder: 提交 ───
 
   buildCurrentSubmitPayloadForLocalPrint(params) {
@@ -3888,9 +4061,14 @@ class OrderModule extends _BaseModule.BaseModule {
   }
   async runSubmitTempOrder(params) {
     const tempOrder = this.ensureTempOrder();
+    this.prepareVirtualSettlementTempOrder(tempOrder);
+    const isOnlineStorePlatform = this.isOnlineStorePlatform();
     const shouldConfirmPendingVoucherPayments = params?.confirmPendingVoucherPayments !== false;
     const hasPaymentOverride = params?.payments !== undefined;
-    const preparedPaymentOverride = hasPaymentOverride ? this.prepareVoucherPaymentsForSubmit(params?.payments || [], shouldConfirmPendingVoucherPayments) : undefined;
+    let preparedPaymentOverride;
+    if (hasPaymentOverride) {
+      preparedPaymentOverride = isOnlineStorePlatform ? params?.payments || [] : this.prepareVoucherPaymentsForSubmit(params?.payments || [], shouldConfirmPendingVoucherPayments);
+    }
     if (!hasPaymentOverride) {
       if (shouldConfirmPendingVoucherPayments) {
         this.confirmPendingVoucherPayments({
@@ -3910,6 +4088,7 @@ class OrderModule extends _BaseModule.BaseModule {
     })) || this.store.summary || (0, _utils.createEmptySummary)();
     const effectiveCacheId = params?.cacheId ?? this.cacheId;
     const hasPaymentStatusOverride = params?.paymentStatus !== undefined;
+    const shouldOverridePaymentStatus = hasPaymentStatusOverride && !isOnlineStorePlatform && !shouldConfirmPendingVoucherPayments;
     const hasSmallTicketDataFlagOverride = params?.smallTicketDataFlag !== undefined;
     const enhancePayload = hasPaymentOverride || hasPaymentStatusOverride || hasSmallTicketDataFlagOverride || params?.enhancePayload ? (payload, ctx) => {
       const nextPayload = {
@@ -3917,7 +4096,7 @@ class OrderModule extends _BaseModule.BaseModule {
         ...(hasPaymentOverride ? {
           payments: preparedPaymentOverride || []
         } : {}),
-        ...(hasPaymentStatusOverride && !shouldConfirmPendingVoucherPayments ? {
+        ...(shouldOverridePaymentStatus ? {
           payment_status: params?.paymentStatus
         } : {}),
         ...(hasSmallTicketDataFlagOverride ? {
@@ -3937,6 +4116,7 @@ class OrderModule extends _BaseModule.BaseModule {
       type: submitSnapshot.type ?? params?.type,
       summary: latestSummary,
       request_unique_idempotency_token: params?.request_unique_idempotency_token,
+      includePaymentStatus: !isOnlineStorePlatform,
       enhance: enhancePayload
     });
     if (params?.syncMode) {
@@ -4868,7 +5048,7 @@ class OrderModule extends _BaseModule.BaseModule {
     };
     if (result.metadata) delete result.metadata.price_schema_version;
     const restored = (0, _bundleDiscountHydration.restoreHydratedBundleDiscounts)(result, _utils.normalizeOrderProductDiscountList);
-    return this.sanitizeOrderProductForTempOrder(restored);
+    return this.sanitizeOrderProductForTempOrder(this.normalizeVirtualSettlementProductIfEnabled(restored));
   }
   getLastOrderInfo() {
     return this.store?.lastOrderInfo;

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

@@ -1,7 +1,7 @@
 import { CartItem } from '../Cart/types';
 import type { DiscountModule } from '../Discount';
 import type { RulesModule } from '../Rules';
-import type { Discount } from '../Discount/types';
+import type { Discount, VirtualCurrencyAsset } from '../Discount/types';
 import type { UnavailableReason } from '../Rules/types';
 import type { SubmitPayloadEnhancer } from './utils';
 import type { PaymentItem } from '../Payment/types';
@@ -205,6 +205,7 @@ export interface OrderProduct extends OrderProductIdentity {
     gift_card?: number;
     selling_price: string;
     original_price: string;
+    payment_price?: string;
     tax_fee: string;
     is_charge_tax: number;
     discount_list: OrderProductDiscountItem[];
@@ -353,6 +354,7 @@ export interface OrderTempOrder {
     notes: SalesNote[];
     bookings: any[];
     payments: any[];
+    refunds?: any[];
     surcharges: any[];
     discount_list?: any[];
     relation_forms: any[];
@@ -372,8 +374,9 @@ export interface OrderSubmitProduct extends Omit<OrderProduct, 'unique_identific
     payment_price: string;
     product_sku: OrderProductSku;
 }
-export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'products' | 'notes' | '_extend' | 'customer' | 'discount_list' | 'created_at'> {
+export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'products' | 'notes' | '_extend' | 'customer' | 'discount_list' | 'created_at' | 'payment_status'> {
     platform: string;
+    payment_status?: string;
     created_at?: string | undefined;
     request_unique_idempotency_token?: string;
     form_record_ids?: Array<{
@@ -392,6 +395,7 @@ export interface OrderState {
     syncState?: OrderSyncState;
     discountList: any[];
     availableWalletIds?: number[];
+    virtualCurrencyList?: VirtualCurrencyAsset[];
     discount: DiscountModule | null;
     rules: RulesModule | null;
 }
@@ -530,7 +534,7 @@ export interface SubmitSalesOrderParams {
         sales_channel: string;
         order_sales_channel: string;
         status: string;
-        payment_status: string;
+        payment_status?: string;
         shipping_status: string;
         customer_id: number | null;
         customer_name: string;
@@ -794,6 +798,8 @@ export interface OrderModuleAPI {
     addNewOrder: () => Promise<OrderTempOrder>;
     restoreOrder: () => OrderTempOrder;
     getOrderProducts: () => OrderProduct[];
+    getVirtualCurrencyList: () => VirtualCurrencyAsset[];
+    clearOrderForSettlementSwitch: () => Promise<OrderTempOrder>;
     getOrderSummary: () => Promise<OrderSummary>;
     recalculateSummary: (options?: {
         createIfMissing?: boolean;
@@ -864,6 +870,8 @@ export interface OrderModuleAPI {
     isTempOrderPersistEnabled: () => boolean;
     /** 提交 tempOrder 变更并触发 `{moduleName}:changed` 事件 */
     notifyTempOrderChanged: () => void;
+    /** PC/H5 为在线店铺；其它或缺失平台统一按 POS 处理。 */
+    isOnlineStorePlatform: () => boolean;
     submitTempOrder: <T = any>(params?: {
         cacheId?: string;
         platform?: string;

package/lib/modules/Order/utils/virtualSettlement.d.ts

@@ -0,0 +1,63 @@
+import type { OrderProduct, OrderTempOrder } from '../types';
+export interface SelectedSettlementSnapshot extends Record<string, any> {
+    settlement_type: 'legal_currency' | 'virtual_currency';
+    currency_product_id?: number;
+    price: string | number;
+    unit_label?: any;
+    symbol?: any;
+    amount_format?: string;
+}
+export interface LegalCurrencySnapshot {
+    currency_code: string;
+    currency_symbol: string;
+    currency_format: string;
+}
+export interface CurrencyDisplaySnapshot {
+    amount_format: string;
+    symbol: unknown;
+    unit_label: unknown;
+}
+export declare function buildCurrencyDisplaySnapshot(snapshot: Pick<SelectedSettlementSnapshot, 'amount_format' | 'symbol' | 'unit_label'>): CurrencyDisplaySnapshot;
+export declare function resolveSettlementDisplayValue(value: unknown): string;
+export declare class OrderSettlementConflictError extends Error {
+    readonly currentSettlementKey: string;
+    readonly incomingSettlementKey: string;
+    readonly code = "ORDER_SETTLEMENT_CONFLICT";
+    constructor(currentSettlementKey: string, incomingSettlementKey: string);
+}
+export declare class VirtualCurrencyAssetNotFoundError extends Error {
+    readonly currencyProductId: number;
+    readonly code = "VIRTUAL_CURRENCY_ASSET_NOT_FOUND";
+    constructor(currencyProductId: number);
+}
+export declare class VirtualCurrencyBalanceError extends Error {
+    readonly balance: string;
+    readonly requiredAmount: string;
+    readonly code = "VIRTUAL_CURRENCY_BALANCE_INSUFFICIENT";
+    constructor(balance: string, requiredAmount: string);
+}
+export declare function getSelectedSettlementSnapshot(product: Partial<OrderProduct> | null | undefined): SelectedSettlementSnapshot | null;
+export declare function getTempOrderSettlementSnapshot(tempOrder: OrderTempOrder | null | undefined): SelectedSettlementSnapshot | null;
+export declare function isVirtualSettlementProduct(product: Partial<OrderProduct> | null | undefined): boolean;
+export declare function getSettlementKey(snapshot: SelectedSettlementSnapshot | null | undefined): string | null;
+export declare function getTempOrderSettlementKey(tempOrder: OrderTempOrder | null | undefined): string | null;
+export declare function isVirtualSettlementOrder(tempOrder: OrderTempOrder | null | undefined): boolean;
+/**
+ * 详情展示识别同时支持已提交订单的 currency_settlement_config。
+ * cart_settlement_* 是交易过程内部状态，服务端详情不保证返回。
+ */
+export declare function isVirtualSettlementDisplayOrder(tempOrder: OrderTempOrder | null | undefined): boolean;
+/**
+ * 将购物车锁定的结算单位提升为订单级状态。
+ * 商品行快照同时负责价格归一化和生成订单级多语言展示快照；
+ * 交易中的即时展示仍统一读取 tempOrder.currency_*。
+ */
+export declare function applyTempOrderSettlementState(tempOrder: OrderTempOrder, snapshot: SelectedSettlementSnapshot): void;
+/** 清空购物车结算锁，并恢复进入虚拟币结算前的店铺法币。 */
+export declare function releaseTempOrderSettlementState(tempOrder: OrderTempOrder): void;
+/**
+ * 将已选择虚拟币的订单商品行固化为最终价语义。
+ * 函数幂等，可安全用于加车、合并、hydrate 和提交前兜底。
+ */
+export declare function normalizeVirtualSettlementOrderProduct<T extends Partial<OrderProduct>>(product: T): T;
+export declare function normalizeVirtualSettlementProducts<T extends Partial<OrderProduct>>(products: T[]): T[];