@pisell/pisellos 0.10.43 → 0.10.44

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

@@ -0,0 +1,31 @@
+import type { SalesNote, SalesNoteProtocol, SalesNoteTextInput } from './types';
+export interface SalesNotePolicy {
+    note_type: string;
+    importance: string;
+    uniquePerPrimaryTarget: boolean;
+    primary_relation_type: 'about';
+    secondary_order_relation_type: 'related_to';
+}
+export declare function getSalesNotePolicy(note_type: string): SalesNotePolicy | null;
+export declare function buildSalesNoteText(input: SalesNoteTextInput): Record<string, string>;
+export interface SalesNoteValidationOptions {
+    allowUnresolvedOrderTarget?: boolean;
+    expectedOrderTargetUuid?: string;
+    productTargetUuids?: ReadonlySet<string>;
+}
+export type EncodeSalesNotesOptions = SalesNoteValidationOptions;
+export declare function encodeSalesNotes(notes: SalesNote[], options?: EncodeSalesNotesOptions): SalesNoteProtocol[];
+export interface DecodedSalesNotesSnapshot {
+    notes: SalesNote[];
+    complete: boolean;
+}
+export interface DecodeSalesNotesOptions {
+    allowUnresolvedOrderTarget?: boolean;
+}
+export declare function decodeSalesNotesSnapshot(value: unknown, options?: DecodeSalesNotesOptions): DecodedSalesNotesSnapshot;
+export declare function decodeSalesNotes(value: unknown, options?: DecodeSalesNotesOptions): SalesNote[];
+export declare function finalizeSalesNotesForCheckout(params: {
+    notes: unknown;
+    shopOrderNumber: unknown;
+    productTargetUuids: string[];
+}): SalesNoteProtocol[];

package/lib/modules/Order/salesNotes.js

@@ -0,0 +1,382 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.buildSalesNoteText = buildSalesNoteText;
+exports.decodeSalesNotes = decodeSalesNotes;
+exports.decodeSalesNotesSnapshot = decodeSalesNotesSnapshot;
+exports.encodeSalesNotes = encodeSalesNotes;
+exports.finalizeSalesNotesForCheckout = finalizeSalesNotesForCheckout;
+exports.getSalesNotePolicy = getSalesNotePolicy;
+const MAX_UUID_LENGTH = 255;
+const LOCALIZED_NOTE_LOCALES = ['en', 'zh-CN', 'zh-HK', 'ja', 'pt'];
+const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/**
+ * 备注业务规则统一注册在 OS；调用方只传 note_type、目标行和原始文本。
+ * 后续新增备注类型时在这里增加 policy，不把 importance / Relation 规则下放给 UI。
+ */
+const SALES_NOTE_POLICIES = {
+  allergy: {
+    note_type: 'allergy',
+    importance: 'high',
+    uniquePerPrimaryTarget: true,
+    primary_relation_type: 'about',
+    secondary_order_relation_type: 'related_to'
+  }
+};
+function getSalesNotePolicy(note_type) {
+  return SALES_NOTE_POLICIES[note_type] || null;
+}
+function normalizeUuid(value, field, options) {
+  const uuid = String(value ?? '').trim();
+  if (!uuid && !options?.allowEmpty) {
+    throw new Error(`[Order Notes] ${field} 不能为空`);
+  }
+  if (uuid.length > MAX_UUID_LENGTH) {
+    throw new Error(`[Order Notes] ${field} 不能超过 ${MAX_UUID_LENGTH} 个字符`);
+  }
+  return uuid;
+}
+function normalizeEntityUuid(value, field) {
+  const uuid = normalizeUuid(value, field);
+  if (!UUID_V4_PATTERN.test(uuid)) {
+    throw new Error(`[Order Notes] ${field} 必须为 UUID v4`);
+  }
+  return uuid;
+}
+function normalizeTextRecord(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.entries(value).reduce((result, [locale, text]) => {
+    if (typeof text === 'string') result[locale] = text;
+    return result;
+  }, {});
+}
+function normalizeLocalizedLabel(label) {
+  if (typeof label === 'string') {
+    const text = label.trim();
+    return text ? {
+      default: text
+    } : {};
+  }
+  return Object.entries(label || {}).reduce((result, [locale, value]) => {
+    const text = String(value ?? '').trim();
+    if (text) result[locale] = text;
+    return result;
+  }, {});
+}
+function getLocaleCandidates(locale) {
+  const raw = String(locale || '').trim();
+  const normalized = raw.replace(/_/g, '-');
+  const base = normalized.split('-')[0];
+  return Array.from(new Set([raw, normalized, base].filter(Boolean)));
+}
+function normalizeLocaleLookupKey(locale) {
+  return String(locale || '').trim().replace(/_/g, '-').toLowerCase();
+}
+function resolveLocalizedLabel(label, locale) {
+  if (typeof label === 'string') return label.trim();
+  const normalized = normalizeLocalizedLabel(label);
+  const entries = Object.entries(normalized);
+  const lowerCaseLookup = new Map(entries.map(([key, value]) => [normalizeLocaleLookupKey(key), value]));
+  for (const candidate of getLocaleCandidates(locale)) {
+    const matched = lowerCaseLookup.get(normalizeLocaleLookupKey(candidate));
+    if (matched) return matched;
+  }
+  const localeBase = normalizeLocaleLookupKey(locale).split('-')[0];
+  const sameLanguage = entries.find(([key]) => normalizeLocaleLookupKey(key).split('-')[0] === localeBase)?.[1];
+  return sameLanguage || lowerCaseLookup.get('en') || lowerCaseLookup.get('zh-cn') || lowerCaseLookup.get('default') || entries[0]?.[1] || '';
+}
+function joinNoteParts(parts) {
+  return parts.map(part => String(part ?? '')).filter(part => part.trim().length > 0).join(',');
+}
+function buildSalesNoteText(input) {
+  if (input.kind === 'plain') {
+    const text = String(input.input ?? '');
+    if (!text.trim()) throw new Error('[Order Notes] 备注输入不能为空');
+    return {
+      'zh-CN': '',
+      original: text
+    };
+  }
+  if (input.kind === 'resolved') {
+    const text = normalizeTextRecord(input.text);
+    if (!Object.values(text).some(value => value.trim())) {
+      throw new Error('[Order Notes] 备注文本不能为空');
+    }
+    return text;
+  }
+  const inputText = String(input.input ?? '');
+  const seenIds = new Set();
+  const selections = (input.selections || []).filter(selection => {
+    const id = String(selection?.id ?? '').trim();
+    if (!id || seenIds.has(id)) return false;
+    seenIds.add(id);
+    return true;
+  });
+  if (!selections.length && !inputText.trim()) {
+    throw new Error('[Order Notes] 过敏选项和补充说明不能同时为空');
+  }
+  const result = {};
+  for (const locale of LOCALIZED_NOTE_LOCALES) {
+    result[locale] = joinNoteParts([...selections.map(selection => resolveLocalizedLabel(selection.label, locale)), inputText]);
+  }
+  result.original = joinNoteParts([...selections.map(selection => resolveLocalizedLabel(selection.label, input.locale)), inputText]);
+  return result;
+}
+function validateSalesNote(note, options = {}) {
+  normalizeEntityUuid(note.uuid, 'Note uuid');
+  const note_type = String(note.note_type || '').trim();
+  const policy = getSalesNotePolicy(note_type);
+  if (!policy) {
+    throw new Error(`[Order Notes] 当前未注册备注类型: ${note_type || '(empty)'}`);
+  }
+  if (note.importance !== policy.importance) {
+    throw new Error(`[Order Notes] ${note_type} importance 必须为 ${policy.importance}`);
+  }
+  const text = note.content?.text;
+  if (!text || typeof text !== 'object' || Array.isArray(text) || Object.values(text).some(value => typeof value !== 'string') || !Object.values(text).some(value => value.trim())) {
+    throw new Error('[Order Notes] content.text 不能为空');
+  }
+  if (!Array.isArray(note.note_relations) || note.note_relations.length === 0) {
+    throw new Error('[Order Notes] note_relations 不能为空');
+  }
+  const relationUuids = new Set();
+  let primaryCount = 0;
+  let orderRelationCount = 0;
+  for (const relation of note.note_relations) {
+    const relationUuid = normalizeEntityUuid(relation.uuid, 'Relation uuid');
+    if (relationUuids.has(relationUuid)) {
+      throw new Error('[Order Notes] 同一 Note 内 Relation uuid 不能重复');
+    }
+    relationUuids.add(relationUuid);
+    if (relation.is_primary !== 0 && relation.is_primary !== 1) {
+      throw new Error('[Order Notes] is_primary 只允许整数 0 或 1');
+    }
+    if (relation.relation_type !== 'about' && relation.relation_type !== 'related_to') {
+      throw new Error('[Order Notes] relation_type 不合法');
+    }
+    if (relation.target_type !== 'order' && relation.target_type !== 'order_detail') {
+      throw new Error('[Order Notes] target_type 不合法');
+    }
+    if (relation.is_primary === 1) {
+      primaryCount += 1;
+      if (relation.relation_type !== policy.primary_relation_type || relation.target_type !== 'order_detail') {
+        throw new Error('[Order Notes] 主关系必须使用 about + order_detail');
+      }
+      const targetUuid = normalizeUuid(relation.target_uuid, 'Relation target_uuid');
+      if (options.productTargetUuids && !options.productTargetUuids.has(targetUuid)) {
+        throw new Error('[Order Notes] 商品 Relation target_uuid 不属于当前订单');
+      }
+      continue;
+    }
+    if (relation.target_type === 'order' && relation.relation_type === policy.secondary_order_relation_type) {
+      orderRelationCount += 1;
+      const targetUuid = normalizeUuid(relation.target_uuid, 'Relation target_uuid', {
+        allowEmpty: options.allowUnresolvedOrderTarget === true
+      });
+      if (options.expectedOrderTargetUuid !== undefined && targetUuid !== options.expectedOrderTargetUuid) {
+        throw new Error('[Order Notes] 订单 Relation target_uuid 与 shop_order_number 不一致');
+      }
+      continue;
+    }
+    throw new Error('[Order Notes] 非主体关系必须使用 related_to + order');
+  }
+  if (primaryCount !== 1) {
+    throw new Error('[Order Notes] 每条 Note 必须且只能有一个主关系');
+  }
+  if (orderRelationCount !== 1) {
+    throw new Error('[Order Notes] 每条商品 Note 必须且只能有一个订单冗余关系');
+  }
+}
+function encodeSalesNotes(notes, options = {}) {
+  const entityUuids = new Set();
+  const uniquePolicyTargets = new Set();
+  return (notes || []).map(note => {
+    validateSalesNote(note, options);
+    const noteUuid = normalizeEntityUuid(note.uuid, 'Note uuid');
+    if (entityUuids.has(noteUuid)) {
+      throw new Error('[Order Notes] Note/Relation uuid 不能重复');
+    }
+    entityUuids.add(noteUuid);
+    const note_type = String(note.note_type).trim();
+    const noteRelations = note.note_relations.map(relation => {
+      const relationUuid = normalizeEntityUuid(relation.uuid, 'Relation uuid');
+      if (entityUuids.has(relationUuid)) {
+        throw new Error('[Order Notes] Note/Relation uuid 不能重复');
+      }
+      entityUuids.add(relationUuid);
+      const allowEmptyTarget = options.allowUnresolvedOrderTarget === true && relation.is_primary === 0 && relation.relation_type === 'related_to' && relation.target_type === 'order';
+      return {
+        uuid: relationUuid,
+        relation_type: relation.relation_type,
+        target_type: relation.target_type,
+        target_uuid: normalizeUuid(relation.target_uuid, 'Relation target_uuid', {
+          allowEmpty: allowEmptyTarget
+        }),
+        is_primary: relation.is_primary
+      };
+    });
+    const primaryRelation = noteRelations.find(relation => relation.is_primary === 1);
+    const policy = getSalesNotePolicy(note_type);
+    if (policy.uniquePerPrimaryTarget) {
+      const policyTargetKey = [note_type, primaryRelation.target_type, primaryRelation.target_uuid].join(':');
+      if (uniquePolicyTargets.has(policyTargetKey)) {
+        throw new Error('[Order Notes] 同一商品行不能重复提交同类型 Note');
+      }
+      uniquePolicyTargets.add(policyTargetKey);
+    }
+    return {
+      uuid: noteUuid,
+      note_type,
+      content: {
+        text: {
+          ...(note.content?.text || {})
+        }
+      },
+      importance: note.importance,
+      note_relations: noteRelations
+    };
+  });
+}
+function decodeRelation(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  const raw = value;
+  const uuid = String(raw.uuid ?? '').trim();
+  const target_uuid = String(raw.target_uuid ?? '').trim();
+  const relation_type = raw.relation_type;
+  const target_type = raw.target_type;
+  const is_primary = raw.is_primary;
+  if (!uuid || relation_type !== 'about' && relation_type !== 'related_to' || target_type !== 'order' && target_type !== 'order_detail' || is_primary !== 0 && is_primary !== 1) {
+    return null;
+  }
+  return {
+    uuid,
+    relation_type,
+    target_type,
+    target_uuid,
+    is_primary
+  };
+}
+function decodeSalesNotesSnapshot(value, options = {}) {
+  if (!Array.isArray(value)) return {
+    notes: [],
+    complete: false
+  };
+  const notes = [];
+  const entityUuids = new Set();
+  const uniquePolicyTargets = new Set();
+  let complete = true;
+  for (const item of value) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      complete = false;
+      continue;
+    }
+    const raw = item;
+    const uuid = String(raw.uuid ?? '').trim();
+    const note_type = String(raw.note_type ?? '').trim();
+    const importance = String(raw.importance ?? '').trim();
+    const rawText = raw.content?.text;
+    const text = normalizeTextRecord(rawText);
+    if (!rawText || typeof rawText !== 'object' || Array.isArray(rawText) || Object.keys(text).length !== Object.keys(rawText).length) {
+      complete = false;
+      continue;
+    }
+    const rawNoteRelations = Array.isArray(raw.note_relations) ? raw.note_relations : null;
+    const noteRelations = rawNoteRelations ? rawNoteRelations.map(relation => decodeRelation(relation)).filter(relation => relation !== null) : [];
+    if (!rawNoteRelations || noteRelations.length !== rawNoteRelations.length) {
+      complete = false;
+      continue;
+    }
+    const note = {
+      uuid,
+      note_type,
+      content: {
+        text
+      },
+      importance,
+      note_relations: noteRelations
+    };
+    try {
+      validateSalesNote(note, {
+        allowUnresolvedOrderTarget: options.allowUnresolvedOrderTarget
+      });
+      if (entityUuids.has(note.uuid)) {
+        complete = false;
+        continue;
+      }
+      entityUuids.add(note.uuid);
+      let hasDuplicateRelationUuid = false;
+      for (const relation of note.note_relations) {
+        if (entityUuids.has(relation.uuid)) {
+          hasDuplicateRelationUuid = true;
+          break;
+        }
+      }
+      if (hasDuplicateRelationUuid) {
+        complete = false;
+        continue;
+      }
+      note.note_relations.forEach(relation => entityUuids.add(relation.uuid));
+      const policy = getSalesNotePolicy(note.note_type);
+      const primaryRelation = note.note_relations.find(relation => relation.is_primary === 1);
+      if (policy?.uniquePerPrimaryTarget && primaryRelation) {
+        const policyTargetKey = [note.note_type, primaryRelation.target_type, primaryRelation.target_uuid].join(':');
+        if (uniquePolicyTargets.has(policyTargetKey)) {
+          complete = false;
+          continue;
+        }
+        uniquePolicyTargets.add(policyTargetKey);
+      }
+      notes.push(note);
+    } catch {
+      complete = false;
+    }
+  }
+  return {
+    notes,
+    complete
+  };
+}
+function decodeSalesNotes(value, options = {}) {
+  return decodeSalesNotesSnapshot(value, options).notes;
+}
+function finalizeSalesNotesForCheckout(params) {
+  if (!Array.isArray(params.notes)) {
+    throw new Error('[Order Notes] checkout notes 必须为数组');
+  }
+  if (params.notes.length === 0) return [];
+  const shopOrderNumber = normalizeUuid(params.shopOrderNumber, 'shop_order_number');
+  const productTargetUuids = new Set();
+  for (const rawTargetUuid of params.productTargetUuids || []) {
+    const targetUuid = normalizeUuid(rawTargetUuid, '商品 target_uuid');
+    if (productTargetUuids.has(targetUuid)) {
+      throw new Error('[Order Notes] 商品行业务标识不能重复');
+    }
+    productTargetUuids.add(targetUuid);
+  }
+  const decoded = decodeSalesNotesSnapshot(params.notes, {
+    allowUnresolvedOrderTarget: true
+  });
+  if (!decoded.complete || decoded.notes.length !== params.notes.length) {
+    throw new Error('[Order Notes] checkout Notes 快照不完整');
+  }
+  const finalizedNotes = decoded.notes.map(note => ({
+    ...note,
+    content: {
+      text: {
+        ...note.content.text
+      }
+    },
+    note_relations: note.note_relations.map(relation => ({
+      ...relation,
+      ...(relation.is_primary === 0 && relation.relation_type === 'related_to' && relation.target_type === 'order' ? {
+        target_uuid: shopOrderNumber
+      } : {})
+    }))
+  }));
+  return encodeSalesNotes(finalizedNotes, {
+    expectedOrderTargetUuid: shopOrderNumber,
+    productTargetUuids
+  });
+}

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

@@ -8,6 +8,13 @@ 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[];
 }
 /**
@@ -196,8 +203,18 @@ export interface PointCardSnapshotItem {
     par_value: string;
     used_par_value: string;
 }
+export interface VirtualCurrencySnapshotItem {
+    id: number | string;
+    tag: 'virtual_currency';
+    product_id?: number | string;
+    product_name: string;
+    par_value: string;
+    used_par_value: string;
+    name: Record<string, string>;
+}
 export interface OrderMetaList {
     point_cards_snapshot?: PointCardSnapshotItem[];
+    virtual_currency_snapshot?: VirtualCurrencySnapshotItem[];
 }
 export interface OrderProduct extends OrderProductIdentity {
     order_detail_id: number | null;
@@ -250,6 +267,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;
@@ -289,6 +372,7 @@ export interface OrderTempOrder {
     created_at: string | undefined;
     request_unique_idempotency_token?: string;
     products: OrderProduct[];
+    notes: SalesNote[];
     bookings: any[];
     payments: any[];
     refunds?: any[];
@@ -303,6 +387,7 @@ export interface OrderTempOrder {
     summary?: OrderSummary;
     _extend?: {
         productsByUid?: Record<string, Record<string, any>>;
+        salesNotesState?: SalesNotesRuntimeState;
         [key: string]: any;
     };
 }
@@ -311,7 +396,7 @@ 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' | 'payment_status'> {
+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;
@@ -321,6 +406,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;
 }
@@ -350,6 +436,8 @@ export interface AddProductToOrderOptions {
     insertAfterProductUid?: string;
     /** 跳过同商品/规格匹配，始终新增购物车行。 */
     disableMerge?: boolean;
+    /** 商品行 UID 落定后，由 OrderModule 原子绑定到该行的 Sales Notes 草稿。 */
+    salesNotes?: SalesNoteDraftInput[];
 }
 /**
  * 删除商品后的可选位置保持策略。
@@ -768,9 +856,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[]>;
@@ -878,6 +974,7 @@ export interface OrderModuleAPI {
     }) => Promise<Discount[]>;
     getDiscountList: () => Discount[];
     getAvailableWalletIds: () => number[];
+    getCustomerWalletPrepareConfigEpoch: () => number;
     applyDiscount: () => void;
     /**
      * 注入促销评估器。
@@ -906,7 +1003,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 等写路径末尾触发，业务一般无需手动调用。
@@ -920,10 +1017,10 @@ export interface OrderModuleAPI {
     /** 读取上次 applyPromotion 产出的赠品操作 diff（toAdd / toReduce / toRemove） */
     getLastGiftActions: () => OrderLastGiftActions | null;
     /**
-   * 取消订单
-   * @param params 取消订单参数
-   * @returns 后端返回结果
-   */
+     * 取消订单
+     * @param params 取消订单参数
+     * @returns 后端返回结果
+     */
     cancelOrder: (params: CancelOrderParams) => Promise<any>;
     /**
      * 变更预约状态

package/lib/modules/Order/types.js

@@ -40,7 +40,7 @@ let OrderHooks = exports.OrderHooks = /*#__PURE__*/function (OrderHooks) {
  */
 /** 未满足的促销策略（购物车底部 alert 渲染源） */
 /** 上一次 applyPromotion 计算出的赠品操作（仅供调试/读取使用） */
-/** onPromotionApplied 事件 payload */
+/** onPromotionApplied 稳定态事件 payload（促销、折扣与 summary 均已完成）。 */
 /**
  * tempOrder 上的下单客户协议字段视图。
  * 这些字段会随订单提交到后端。
@@ -59,6 +59,10 @@ let OrderHooks = exports.OrderHooks = /*#__PURE__*/function (OrderHooks) {
  * - `source`：缺省表示真实业务变更；`detailHydrate` 仅表示打开详情时快照已就绪
  * 清空时整个 payload 为 null。
  */
+/**
+ * Sales Notes 乐观写入前的可恢复快照。
+ * 该对象应视为 opaque token，只用于原样传回 restoreSalesNotesMutationSnapshot。
+ */
 /**
  * 添加商品行时的顺序控制。
  * 默认追加到 products 尾部；预约数量同步可插入到既有预约组的最新行之后，

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

@@ -1,6 +1,6 @@
 import Decimal from 'decimal.js';
 import type { CartItem } from '../Cart';
-import type { OrderProductDiscountItem, OrderMetaList, OrderProduct, OrderSubmitPayload, OrderSubmitProduct, OrderSummary, OrderTempOrder, PointCardSnapshotItem } from './types';
+import type { OrderProductDiscountItem, OrderMetaList, OrderProduct, OrderSubmitPayload, OrderSubmitProduct, OrderSummary, OrderTempOrder, PointCardSnapshotItem, VirtualCurrencySnapshotItem } from './types';
 import type { RulesParamsHooks } from '../Rules/types';
 import type { MapOrderPaymentsOptions, OrderPaymentData, OrderPaymentSource } from './types';
 import { createUuidV4 } from './utils/orderCollectionIdentity';
@@ -18,6 +18,8 @@ export interface OrderProductsDepositSummary {
 import type { WindowPlugin } from '../../plugins';
 export declare function normalizePointCardSnapshotItem(value: unknown): PointCardSnapshotItem | null;
 export declare function buildPointCardSnapshotFromWalletPassList(value: unknown): PointCardSnapshotItem[];
+export declare function normalizeVirtualCurrencySnapshotItem(value: unknown): VirtualCurrencySnapshotItem | null;
+export declare function buildVirtualCurrencySnapshotFromList(value: unknown): VirtualCurrencySnapshotItem[];
 export declare function normalizeOrderMetaList(value: unknown): OrderMetaList | undefined;
 /**
  * 把"含 option 的主商品单价"与 bundle 合成"单行 composite 单价"。