@pisell/pisellos 2.2.301 → 2.2.303

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

@@ -1,13 +1,20 @@
 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';
 import type { ICustomer } from '../AccountList/types';
 import type { OrderProductDiscountItem } from '../../server/modules/order/types';
 export type { OrderProductDiscountItem } from '../../server/modules/order/types';
+export type PickupReferenceMode = 'counter_pickup' | 'table_service';
+export type ShopServiceType = 'dine_in' | 'takeaway';
+export interface ShopServiceData {
+    pickup_reference_mode?: PickupReferenceMode;
+    service_type?: ShopServiceType | '';
+    [key: string]: any;
+}
 export declare enum OrderHooks {
     OnOrderCreate = "order:onOrderCreate",
     OnOrderUpdate = "order:onOrderUpdate",
@@ -110,7 +117,7 @@ export interface OrderLastGiftActions {
     }>;
     toRemove: string[];
 }
-/** onPromotionApplied 事件 payload */
+/** onPromotionApplied 稳定态事件 payload（促销、折扣与 summary 均已完成）。 */
 export interface OrderPromotionAppliedPayload {
     unfulfilledPromotions: OrderUnfulfilledPromotion[];
     giftActions: OrderLastGiftActions;
@@ -124,7 +131,7 @@ export interface OrderPromotionAppliedPayload {
             product_variant_id: number;
         }>;
     }>;
-    /** 处理后的商品列表 */
+    /** 折扣重算后的最终商品列表 */
     products: OrderProduct[];
 }
 /**
@@ -188,6 +195,17 @@ export interface OrderProductSku {
 export interface OrderLocalizedText {
     [locale: string]: string | null;
 }
+export interface PointCardSnapshotItem {
+    id: number | string;
+    tag: 'point_card';
+    product_id?: number | string;
+    product_name: string;
+    par_value: string;
+    used_par_value: string;
+}
+export interface OrderMetaList {
+    point_cards_snapshot?: PointCardSnapshotItem[];
+}
 export interface OrderProduct extends OrderProductIdentity {
     order_detail_id: number | null;
     num: number;
@@ -198,6 +216,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[];
@@ -238,6 +257,72 @@ export interface OrderSummary {
     tax_title?: string;
     tax_rate?: number;
 }
+export type SalesNoteRelationType = 'about' | 'related_to';
+export type SalesNoteTargetType = 'order' | 'order_detail';
+export type SalesNoteLocalizedText = string | Record<string, string>;
+export interface SalesNoteLocalizedSelection {
+    id: string;
+    label: SalesNoteLocalizedText;
+}
+export type SalesNoteTextInput = {
+    kind: 'localizedSelections';
+    selections: SalesNoteLocalizedSelection[];
+    locale: string;
+    input?: string;
+} | {
+    kind: 'plain';
+    input: string;
+} | {
+    kind: 'resolved';
+    text: Record<string, string>;
+};
+export interface SalesNoteRelation {
+    uuid: string;
+    relation_type: SalesNoteRelationType;
+    target_type: SalesNoteTargetType;
+    target_uuid: string;
+    is_primary: 0 | 1;
+}
+export interface SalesNote {
+    uuid: string;
+    note_type: string;
+    content: {
+        text: Record<string, string>;
+    };
+    importance: string;
+    note_relations: SalesNoteRelation[];
+}
+export interface SalesNoteTarget {
+    target_type: 'order_detail';
+    target_uuid: string;
+}
+export interface SetSalesNoteInput {
+    note_type: string;
+    target: SalesNoteTarget;
+    text: SalesNoteTextInput;
+}
+export interface SalesNoteDraftInput {
+    note_type: string;
+    text: SalesNoteTextInput;
+}
+export interface SalesNotesRuntimeState {
+    loaded: boolean;
+    dirty: boolean;
+}
+/**
+ * Sales Notes 乐观写入前的可恢复快照。
+ * 该对象应视为 opaque token，只用于原样传回 restoreSalesNotesMutationSnapshot。
+ */
+export interface SalesNotesMutationSnapshot {
+    orderIdentity: {
+        orderId: number | string | null;
+        externalSaleNumber: string;
+    };
+    notes: SalesNote[];
+    state: SalesNotesRuntimeState;
+}
+export type SalesNoteProtocolRelation = SalesNoteRelation;
+export type SalesNoteProtocol = SalesNote;
 export interface OrderTempOrder {
     order_id: number | null;
     external_sale_number: string;
@@ -277,18 +362,22 @@ export interface OrderTempOrder {
     created_at: string | undefined;
     request_unique_idempotency_token?: string;
     products: OrderProduct[];
+    notes: SalesNote[];
     bookings: any[];
     payments: any[];
+    refunds?: any[];
     surcharges: any[];
     discount_list?: any[];
     relation_forms: any[];
     contacts: any[];
     contacts_info: Record<string, any> | null;
     holder: Record<string, any> | null;
+    order_meta_list?: OrderMetaList;
     metadata: Record<string, any>;
     summary?: OrderSummary;
     _extend?: {
         productsByUid?: Record<string, Record<string, any>>;
+        salesNotesState?: SalesNotesRuntimeState;
         [key: string]: any;
     };
 }
@@ -297,8 +386,9 @@ export interface OrderSubmitProduct extends Omit<OrderProduct, 'unique_identific
     payment_price: string;
     product_sku: OrderProductSku;
 }
-export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'products' | '_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<{
@@ -306,6 +396,7 @@ export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'p
         form_record_id: number | string;
     }>;
     products: OrderSubmitProduct[];
+    notes?: SalesNoteProtocol[];
     summary?: OrderSummary;
     small_ticket_data_flag?: number;
 }
@@ -316,6 +407,7 @@ export interface OrderState {
     syncState?: OrderSyncState;
     discountList: any[];
     availableWalletIds?: number[];
+    virtualCurrencyList?: VirtualCurrencyAsset[];
     discount: DiscountModule | null;
     rules: RulesModule | null;
 }
@@ -334,6 +426,8 @@ export interface AddProductToOrderOptions {
     insertAfterProductUid?: string;
     /** 跳过同商品/规格匹配，始终新增购物车行。 */
     disableMerge?: boolean;
+    /** 商品行 UID 落定后，由 OrderModule 原子绑定到该行的 Sales Notes 草稿。 */
+    salesNotes?: SalesNoteDraftInput[];
 }
 /**
  * 删除商品后的可选位置保持策略。
@@ -452,7 +546,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;
@@ -484,6 +578,7 @@ export interface SubmitSalesOrderParams {
         contacts: any[];
         contacts_info: Record<string, any> | null;
         holder: Record<string, any> | null;
+        order_meta_list?: OrderMetaList;
         metadata: Record<string, any>;
         summary?: OrderSummary;
         small_ticket_data_flag?: number;
@@ -716,6 +811,8 @@ export interface OrderModuleAPI {
     addNewOrder: () => Promise<OrderTempOrder>;
     restoreOrder: () => OrderTempOrder;
     getOrderProducts: () => OrderProduct[];
+    getVirtualCurrencyList: () => VirtualCurrencyAsset[];
+    clearOrderForSettlementSwitch: () => Promise<OrderTempOrder>;
     getOrderSummary: () => Promise<OrderSummary>;
     recalculateSummary: (options?: {
         createIfMissing?: boolean;
@@ -749,9 +846,17 @@ export interface OrderModuleAPI {
     updateTempOrderShopDiscount: (amount: string | number) => string;
     updateTempOrderDepositAmount: (amount: string | number) => OrderSummary;
     updateTempOrderCustomer: (customer: UpdateTempOrderCustomerInput) => OrderSnapshot['customer'];
+    updateTempOrderPickupReferenceMode: (mode: PickupReferenceMode) => ShopServiceData;
+    updateTempOrderServiceType: (serviceType: ShopServiceType) => ShopServiceData;
     updateTempOrderBuzzer: (buzzer: string) => string;
     updateTempOrderContactsInfo: (contactsInfo: Record<string, any> | null) => Record<string, any> | null;
     addProductToOrder: (product: Partial<OrderProduct> & OrderProductIdentity, booking?: AddProductBookingInput, options?: AddProductToOrderOptions) => Promise<OrderProduct[]>;
+    getSalesNotes: () => SalesNote[];
+    createSalesNotesMutationSnapshot: () => SalesNotesMutationSnapshot;
+    restoreSalesNotesMutationSnapshot: (snapshot: SalesNotesMutationSnapshot) => void;
+    setSalesNote: (input: SetSalesNoteInput) => Promise<SalesNote>;
+    removeSalesNote: (uuid: string) => Promise<void>;
+    clearSalesNotes: () => Promise<void>;
     updateOrderProduct: (params: UpdateOrderProductParams) => Promise<OrderProduct[]>;
     /** 批量更新购物车行，末尾仅触发一次促销重算与 summary 刷新 */
     updateOrderProducts: (paramsList: UpdateOrderProductParams[]) => Promise<OrderProduct[]>;
@@ -778,6 +883,8 @@ export interface OrderModuleAPI {
     isTempOrderPersistEnabled: () => boolean;
     /** 提交 tempOrder 变更并触发 `{moduleName}:changed` 事件 */
     notifyTempOrderChanged: () => void;
+    /** PC/H5 为在线店铺；其它或缺失平台统一按 POS 处理。 */
+    isOnlineStorePlatform: () => boolean;
     submitTempOrder: <T = any>(params?: {
         cacheId?: string;
         platform?: string;
@@ -885,7 +992,7 @@ export interface OrderModuleAPI {
      */
     appendPromotionTags: <T extends Record<string, any>>(products: T[]) => T[];
     /**
-     * 应用购物车促销（评估 → 差异化赠品 → 写回 tempOrder.products → emit onPromotionApplied）。
+     * 应用购物车促销（评估 → 差异化赠品 → 折扣/summary 重算 → emit onPromotionApplied）。
      *
      * 自动在 addProductToOrder / updateOrderProductQuantity / removeProductFromOrder /
      * clearOrderCartLines / setOrderCustomer 等写路径末尾触发，业务一般无需手动调用。
@@ -899,10 +1006,10 @@ export interface OrderModuleAPI {
     /** 读取上次 applyPromotion 产出的赠品操作 diff（toAdd / toReduce / toRemove） */
     getLastGiftActions: () => OrderLastGiftActions | null;
     /**
-   * 取消订单
-   * @param params 取消订单参数
-   * @returns 后端返回结果
-   */
+     * 取消订单
+     * @param params 取消订单参数
+     * @returns 后端返回结果
+     */
     cancelOrder: (params: CancelOrderParams) => Promise<any>;
     /**
      * 变更预约状态

package/dist/modules/Order/types.js

@@ -41,7 +41,7 @@ export var OrderHooks = /*#__PURE__*/function (OrderHooks) {
 
 /** 上一次 applyPromotion 计算出的赠品操作（仅供调试/读取使用） */
 
-/** onPromotionApplied 事件 payload */
+/** onPromotionApplied 稳定态事件 payload（促销、折扣与 summary 均已完成）。 */
 
 /**
  * tempOrder 上的下单客户协议字段视图。
@@ -64,6 +64,11 @@ export var OrderHooks = /*#__PURE__*/function (OrderHooks) {
  * 清空时整个 payload 为 null。
  */
 
+/**
+ * Sales Notes 乐观写入前的可恢复快照。
+ * 该对象应视为 opaque token，只用于原样传回 restoreSalesNotesMutationSnapshot。
+ */
+
 /**
  * 添加商品行时的顺序控制。
  * 默认追加到 products 尾部；预约数量同步可插入到既有预约组的最新行之后，

package/dist/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[];

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

@@ -0,0 +1,284 @@
+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 _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 _defineProperties(target, props) { for (var i = 0; i < props.length; i++) { var descriptor = props[i]; descriptor.enumerable = descriptor.enumerable || false; descriptor.configurable = true; if ("value" in descriptor) descriptor.writable = true; Object.defineProperty(target, _toPropertyKey(descriptor.key), descriptor); } }
+function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _defineProperties(Constructor.prototype, protoProps); if (staticProps) _defineProperties(Constructor, staticProps); Object.defineProperty(Constructor, "prototype", { writable: false }); return Constructor; }
+function _classCallCheck(instance, Constructor) { if (!(instance instanceof Constructor)) { throw new TypeError("Cannot call a class as a function"); } }
+function _inherits(subClass, superClass) { if (typeof superClass !== "function" && superClass !== null) { throw new TypeError("Super expression must either be null or a function"); } subClass.prototype = Object.create(superClass && superClass.prototype, { constructor: { value: subClass, writable: true, configurable: true } }); Object.defineProperty(subClass, "prototype", { writable: false }); if (superClass) _setPrototypeOf(subClass, superClass); }
+function _createSuper(Derived) { var hasNativeReflectConstruct = _isNativeReflectConstruct(); return function _createSuperInternal() { var Super = _getPrototypeOf(Derived), result; if (hasNativeReflectConstruct) { var NewTarget = _getPrototypeOf(this).constructor; result = Reflect.construct(Super, arguments, NewTarget); } else { result = Super.apply(this, arguments); } return _possibleConstructorReturn(this, result); }; }
+function _possibleConstructorReturn(self, call) { if (call && (_typeof(call) === "object" || typeof call === "function")) { return call; } else if (call !== void 0) { throw new TypeError("Derived constructors may only return object or undefined"); } return _assertThisInitialized(self); }
+function _assertThisInitialized(self) { if (self === void 0) { throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); } return self; }
+function _wrapNativeSuper(Class) { var _cache = typeof Map === "function" ? new Map() : undefined; _wrapNativeSuper = function _wrapNativeSuper(Class) { if (Class === null || !_isNativeFunction(Class)) return Class; if (typeof Class !== "function") { throw new TypeError("Super expression must either be null or a function"); } if (typeof _cache !== "undefined") { if (_cache.has(Class)) return _cache.get(Class); _cache.set(Class, Wrapper); } function Wrapper() { return _construct(Class, arguments, _getPrototypeOf(this).constructor); } Wrapper.prototype = Object.create(Class.prototype, { constructor: { value: Wrapper, enumerable: false, writable: true, configurable: true } }); return _setPrototypeOf(Wrapper, Class); }; return _wrapNativeSuper(Class); }
+function _construct(Parent, args, Class) { if (_isNativeReflectConstruct()) { _construct = Reflect.construct.bind(); } else { _construct = function _construct(Parent, args, Class) { var a = [null]; a.push.apply(a, args); var Constructor = Function.bind.apply(Parent, a); var instance = new Constructor(); if (Class) _setPrototypeOf(instance, Class.prototype); return instance; }; } return _construct.apply(null, arguments); }
+function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Reflect.construct) return false; if (Reflect.construct.sham) return false; if (typeof Proxy === "function") return true; try { Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); return true; } catch (e) { return false; } }
+function _isNativeFunction(fn) { try { return Function.toString.call(fn).indexOf("[native code]") !== -1; } catch (e) { return typeof fn === "function"; } }
+function _setPrototypeOf(o, p) { _setPrototypeOf = Object.setPrototypeOf ? Object.setPrototypeOf.bind() : function _setPrototypeOf(o, p) { o.__proto__ = p; return o; }; return _setPrototypeOf(o, p); }
+function _getPrototypeOf(o) { _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf.bind() : function _getPrototypeOf(o) { return o.__proto__ || Object.getPrototypeOf(o); }; return _getPrototypeOf(o); }
+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';
+import { cloneDeep } from 'lodash-es';
+export function buildCurrencyDisplaySnapshot(snapshot) {
+  var _snapshot$symbol, _snapshot$unit_label;
+  return cloneDeep({
+    amount_format: String(snapshot.amount_format || '').trim(),
+    symbol: (_snapshot$symbol = snapshot.symbol) !== null && _snapshot$symbol !== void 0 ? _snapshot$symbol : {},
+    unit_label: (_snapshot$unit_label = snapshot.unit_label) !== null && _snapshot$unit_label !== void 0 ? _snapshot$unit_label : {}
+  });
+}
+export function resolveSettlementDisplayValue(value) {
+  var _ref, _ref2, _ref3, _ref4, _ref5, _localized$auto;
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string' || typeof value === 'number') {
+    return String(value);
+  }
+  var localized = value;
+  return String((_ref = (_ref2 = (_ref3 = (_ref4 = (_ref5 = (_localized$auto = localized.auto) !== null && _localized$auto !== void 0 ? _localized$auto : localized.default) !== null && _ref5 !== void 0 ? _ref5 : localized.original) !== null && _ref4 !== void 0 ? _ref4 : localized.en) !== null && _ref3 !== void 0 ? _ref3 : localized['zh-CN']) !== null && _ref2 !== void 0 ? _ref2 : localized['zh-HK']) !== null && _ref !== void 0 ? _ref : '');
+}
+export var OrderSettlementConflictError = /*#__PURE__*/function (_Error) {
+  _inherits(OrderSettlementConflictError, _Error);
+  var _super = _createSuper(OrderSettlementConflictError);
+  function OrderSettlementConflictError(currentSettlementKey, incomingSettlementKey) {
+    var _this;
+    _classCallCheck(this, OrderSettlementConflictError);
+    _this = _super.call(this, 'Different currencies and WalletPass units cannot be mixed in one cart.');
+    _defineProperty(_assertThisInitialized(_this), "code", 'ORDER_SETTLEMENT_CONFLICT');
+    _this.currentSettlementKey = currentSettlementKey;
+    _this.incomingSettlementKey = incomingSettlementKey;
+    _this.name = 'OrderSettlementConflictError';
+    return _this;
+  }
+  return _createClass(OrderSettlementConflictError);
+}( /*#__PURE__*/_wrapNativeSuper(Error));
+export var VirtualCurrencyAssetNotFoundError = /*#__PURE__*/function (_Error2) {
+  _inherits(VirtualCurrencyAssetNotFoundError, _Error2);
+  var _super2 = _createSuper(VirtualCurrencyAssetNotFoundError);
+  function VirtualCurrencyAssetNotFoundError(currencyProductId) {
+    var _this2;
+    _classCallCheck(this, VirtualCurrencyAssetNotFoundError);
+    _this2 = _super2.call(this, 'No matching virtual currency card is available.');
+    _defineProperty(_assertThisInitialized(_this2), "code", 'VIRTUAL_CURRENCY_ASSET_NOT_FOUND');
+    _this2.currencyProductId = currencyProductId;
+    _this2.name = 'VirtualCurrencyAssetNotFoundError';
+    return _this2;
+  }
+  return _createClass(VirtualCurrencyAssetNotFoundError);
+}( /*#__PURE__*/_wrapNativeSuper(Error));
+export var VirtualCurrencyBalanceError = /*#__PURE__*/function (_Error3) {
+  _inherits(VirtualCurrencyBalanceError, _Error3);
+  var _super3 = _createSuper(VirtualCurrencyBalanceError);
+  function VirtualCurrencyBalanceError(balance, requiredAmount) {
+    var _this3;
+    _classCallCheck(this, VirtualCurrencyBalanceError);
+    _this3 = _super3.call(this, 'Insufficient virtual currency balance.');
+    _defineProperty(_assertThisInitialized(_this3), "code", 'VIRTUAL_CURRENCY_BALANCE_INSUFFICIENT');
+    _this3.balance = balance;
+    _this3.requiredAmount = requiredAmount;
+    _this3.name = 'VirtualCurrencyBalanceError';
+    return _this3;
+  }
+  return _createClass(VirtualCurrencyBalanceError);
+}( /*#__PURE__*/_wrapNativeSuper(Error));
+export function getSelectedSettlementSnapshot(product) {
+  var _product$metadata;
+  var snapshot = product === null || product === void 0 || (_product$metadata = product.metadata) === null || _product$metadata === void 0 ? void 0 : _product$metadata.selected_settlement_snapshot;
+  if (!snapshot || _typeof(snapshot) !== 'object') return null;
+  if (snapshot.settlement_type !== 'legal_currency' && snapshot.settlement_type !== 'virtual_currency') {
+    return null;
+  }
+  return snapshot;
+}
+export function getTempOrderSettlementSnapshot(tempOrder) {
+  var _tempOrder$metadata, _tempOrder$products;
+  var snapshot = tempOrder === null || tempOrder === void 0 || (_tempOrder$metadata = tempOrder.metadata) === null || _tempOrder$metadata === void 0 ? void 0 : _tempOrder$metadata.cart_settlement_snapshot;
+  if (snapshot && _typeof(snapshot) === 'object' && (snapshot.settlement_type === 'legal_currency' || snapshot.settlement_type === 'virtual_currency')) {
+    return snapshot;
+  }
+  return getSelectedSettlementSnapshot(tempOrder === null || tempOrder === void 0 || (_tempOrder$products = tempOrder.products) === null || _tempOrder$products === void 0 ? void 0 : _tempOrder$products[0]);
+}
+export function isVirtualSettlementProduct(product) {
+  var _getSelectedSettlemen;
+  return ((_getSelectedSettlemen = getSelectedSettlementSnapshot(product)) === null || _getSelectedSettlemen === void 0 ? void 0 : _getSelectedSettlemen.settlement_type) === 'virtual_currency';
+}
+export function getSettlementKey(snapshot) {
+  if (!snapshot) return null;
+  if (snapshot.settlement_type === 'legal_currency') return 'legal_currency';
+  var currencyProductId = Number(snapshot.currency_product_id);
+  return Number.isFinite(currencyProductId) && currencyProductId > 0 ? "virtual_currency:".concat(currencyProductId) : null;
+}
+export function getTempOrderSettlementKey(tempOrder) {
+  var _tempOrder$products2, _tempOrder$metadata2;
+  if (!(tempOrder !== null && tempOrder !== void 0 && (_tempOrder$products2 = tempOrder.products) !== null && _tempOrder$products2 !== void 0 && _tempOrder$products2.length)) return null;
+  var storedKey = (_tempOrder$metadata2 = tempOrder.metadata) === null || _tempOrder$metadata2 === void 0 ? void 0 : _tempOrder$metadata2.cart_settlement_key;
+  if (typeof storedKey === 'string' && storedKey) return storedKey;
+  return getSettlementKey(getTempOrderSettlementSnapshot(tempOrder)) || 'legal_currency';
+}
+export function isVirtualSettlementOrder(tempOrder) {
+  var _getTempOrderSettleme;
+  return ((_getTempOrderSettleme = getTempOrderSettlementKey(tempOrder)) === null || _getTempOrderSettleme === void 0 ? void 0 : _getTempOrderSettleme.startsWith('virtual_currency:')) === true;
+}
+
+/**
+ * 详情展示识别同时支持已提交订单的 currency_settlement_config。
+ * cart_settlement_* 是交易过程内部状态，服务端详情不保证返回。
+ */
+export function isVirtualSettlementDisplayOrder(tempOrder) {
+  var _tempOrder$metadata3;
+  return (tempOrder === null || tempOrder === void 0 || (_tempOrder$metadata3 = tempOrder.metadata) === null || _tempOrder$metadata3 === void 0 || (_tempOrder$metadata3 = _tempOrder$metadata3.currency_settlement_config) === null || _tempOrder$metadata3 === void 0 ? void 0 : _tempOrder$metadata3.settlement_type) === 'virtual_currency' || isVirtualSettlementOrder(tempOrder);
+}
+function getLegalCurrencySnapshot(tempOrder) {
+  var _tempOrder$metadata4;
+  var snapshot = (_tempOrder$metadata4 = tempOrder.metadata) === null || _tempOrder$metadata4 === void 0 ? void 0 : _tempOrder$metadata4.legal_currency_snapshot;
+  if (!snapshot || _typeof(snapshot) !== 'object') return null;
+  return {
+    currency_code: String(snapshot.currency_code || ''),
+    currency_symbol: String(snapshot.currency_symbol || ''),
+    currency_format: String(snapshot.currency_format || 'symbol_first')
+  };
+}
+function captureLegalCurrencySnapshot(tempOrder) {
+  tempOrder.metadata = tempOrder.metadata || {};
+  if (getLegalCurrencySnapshot(tempOrder)) return;
+  tempOrder.metadata.legal_currency_snapshot = {
+    currency_code: String(tempOrder.currency_code || ''),
+    currency_symbol: String(tempOrder.currency_symbol || ''),
+    currency_format: String(tempOrder.currency_format || 'symbol_first')
+  };
+}
+
+/**
+ * 将购物车锁定的结算单位提升为订单级状态。
+ * 商品行快照同时负责价格归一化和生成订单级多语言展示快照；
+ * 交易中的即时展示仍统一读取 tempOrder.currency_*。
+ */
+export function applyTempOrderSettlementState(tempOrder, snapshot) {
+  tempOrder.metadata = tempOrder.metadata || {};
+  var settlementKey = getSettlementKey(snapshot) || 'legal_currency';
+  if (snapshot.settlement_type === 'virtual_currency') {
+    var _tempOrder$metadata$c;
+    captureLegalCurrencySnapshot(tempOrder);
+    var _currencyProductId = Number(snapshot.currency_product_id);
+    var existingDisplaySnapshot = (_tempOrder$metadata$c = tempOrder.metadata.currency_settlement_config) === null || _tempOrder$metadata$c === void 0 ? void 0 : _tempOrder$metadata$c.currency_display_snapshot;
+    tempOrder.metadata.currency_settlement_config = {
+      settlement_type: 'virtual_currency',
+      settlement_ids: Number.isFinite(_currencyProductId) && _currencyProductId > 0 ? [_currencyProductId] : [],
+      currency_display_snapshot: existingDisplaySnapshot ? cloneDeep(existingDisplaySnapshot) : buildCurrencyDisplaySnapshot(snapshot)
+    };
+  } else {
+    delete tempOrder.metadata.currency_settlement_config;
+  }
+  tempOrder.metadata.cart_settlement_key = settlementKey;
+  tempOrder.metadata.cart_settlement_snapshot = _objectSpread({}, snapshot);
+  tempOrder.currency_code = resolveSettlementDisplayValue(snapshot.unit_label) || tempOrder.currency_code;
+  tempOrder.currency_symbol = resolveSettlementDisplayValue(snapshot.symbol) || tempOrder.currency_symbol;
+  tempOrder.currency_format = String(snapshot.amount_format || tempOrder.currency_format || 'symbol_first');
+}
+
+/** 清空购物车结算锁，并恢复进入虚拟币结算前的店铺法币。 */
+export function releaseTempOrderSettlementState(tempOrder) {
+  tempOrder.metadata = tempOrder.metadata || {};
+  var legalCurrency = getLegalCurrencySnapshot(tempOrder);
+  if (legalCurrency) {
+    tempOrder.currency_code = legalCurrency.currency_code;
+    tempOrder.currency_symbol = legalCurrency.currency_symbol;
+    tempOrder.currency_format = legalCurrency.currency_format;
+  }
+  delete tempOrder.metadata.cart_settlement_key;
+  delete tempOrder.metadata.cart_settlement_snapshot;
+  delete tempOrder.metadata.currency_settlement_config;
+}
+function toMoney(value) {
+  try {
+    return new Decimal(String(value !== null && value !== void 0 ? value : 0)).toDecimalPlaces(2).toFixed(2);
+  } catch (_unused) {
+    return '0.00';
+  }
+}
+function zeroOptions(options) {
+  if (!Array.isArray(options)) return [];
+  return options.map(function (option) {
+    return _objectSpread(_objectSpread({}, option), {}, {
+      add_price: 0
+    });
+  });
+}
+function zeroBundles(bundles) {
+  if (!Array.isArray(bundles)) return [];
+  return bundles.map(function (bundle) {
+    return _objectSpread(_objectSpread({}, bundle), {}, {
+      price: 0,
+      custom_price: 0,
+      bundle_selling_price: 0,
+      bundle_payment_price: 0,
+      surcharge_fee: 0,
+      tax_fee: 0,
+      original_tax_fee: 0,
+      is_charge_tax: 0,
+      discount_list: [],
+      relation_surcharge_ids: [],
+      option: zeroOptions(bundle === null || bundle === void 0 ? void 0 : bundle.option),
+      metadata: _objectSpread(_objectSpread({}, (bundle === null || bundle === void 0 ? void 0 : bundle.metadata) || {}), {}, {
+        surcharge_fee: '0.00',
+        relation_surcharge_ids: [],
+        product_discount_difference: '',
+        tax_fee_rounding_remainder: '0.00',
+        surcharge_rounding_remainder: '0.00'
+      })
+    });
+  });
+}
+
+/**
+ * 将已选择虚拟币的订单商品行固化为最终价语义。
+ * 函数幂等，可安全用于加车、合并、hydrate 和提交前兜底。
+ */
+export function normalizeVirtualSettlementOrderProduct(product) {
+  var _product$product_sku;
+  var snapshot = getSelectedSettlementSnapshot(product);
+  if ((snapshot === null || snapshot === void 0 ? void 0 : snapshot.settlement_type) !== 'virtual_currency') return product;
+  var virtualPrice = toMoney(snapshot.price);
+  var metadata = _objectSpread(_objectSpread({}, product.metadata || {}), {}, {
+    source_product_price: virtualPrice,
+    main_product_original_price: virtualPrice,
+    main_product_selling_price: virtualPrice,
+    main_product_attached_bundle_selling_price: virtualPrice,
+    main_product_attached_bundle_payment_price: virtualPrice,
+    main_product_attached_bundle_surcharge_fee: '0.00',
+    main_product_attached_bundle_tax_fee: '0.00',
+    surcharge_rounding_remainder: '0.00',
+    tax_fee_rounding_remainder: '0.00',
+    relation_surcharge_ids: [],
+    average_discount_amount_rate: '1',
+    product_discount_difference: '',
+    discountable_flag: 0,
+    price_schema_version: 2,
+    selected_settlement_snapshot: _objectSpread(_objectSpread({}, snapshot), {}, {
+      price: virtualPrice
+    })
+  });
+  return _objectSpread(_objectSpread({}, product), {}, {
+    selling_price: virtualPrice,
+    original_price: virtualPrice,
+    payment_price: virtualPrice,
+    discount_list: [],
+    is_charge_tax: 0,
+    tax_fee: '0.00',
+    original_tax_fee: 0,
+    tax_fee_rounding_remainder: 0,
+    original_tax_fee_rounding_remainder: 0,
+    surcharge_fee: '0.00',
+    surcharge_rounding_remainder: 0,
+    relation_surcharge_ids: [],
+    product_sku: _objectSpread(_objectSpread({}, product.product_sku || {}), {}, {
+      option: zeroOptions((_product$product_sku = product.product_sku) === null || _product$product_sku === void 0 ? void 0 : _product$product_sku.option)
+    }),
+    product_bundle: zeroBundles(product.product_bundle),
+    metadata: metadata
+  });
+}
+export function normalizeVirtualSettlementProducts(products) {
+  return (products || []).map(function (product) {
+    return normalizeVirtualSettlementOrderProduct(product);
+  });
+}

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

@@ -1,6 +1,6 @@
 import Decimal from 'decimal.js';
 import type { CartItem } from "../Cart";
-import type { OrderProductDiscountItem, OrderProduct, OrderSubmitPayload, OrderSubmitProduct, OrderSummary, OrderTempOrder } from './types';
+import type { OrderProductDiscountItem, OrderMetaList, OrderProduct, OrderSubmitPayload, OrderSubmitProduct, OrderSummary, OrderTempOrder, PointCardSnapshotItem } from './types';
 import type { RulesParamsHooks } from '../Rules/types';
 import type { MapOrderPaymentsOptions, OrderPaymentData, OrderPaymentSource } from './types';
 import { createUuidV4 } from './utils/orderCollectionIdentity';
@@ -16,6 +16,9 @@ export interface OrderProductsDepositSummary {
     hasDeposit: boolean;
 }
 import type { WindowPlugin } from '../../plugins';
+export declare function normalizePointCardSnapshotItem(value: unknown): PointCardSnapshotItem | null;
+export declare function buildPointCardSnapshotFromWalletPassList(value: unknown): PointCardSnapshotItem[];
+export declare function normalizeOrderMetaList(value: unknown): OrderMetaList | undefined;
 /**
  * 把"含 option 的主商品单价"与 bundle 合成"单行 composite 单价"。
  *
@@ -232,6 +235,7 @@ export declare function buildSubmitPayload(params: {
     type?: string;
     summary?: OrderSummary | null;
     request_unique_idempotency_token?: string;
+    includePaymentStatus?: boolean;
     enhance?: SubmitPayloadEnhancer;
 }): OrderSubmitPayload;
 export declare function mapPaymentItemToOrderPayment(paymentItem: OrderPaymentSource): OrderPaymentData;