@pisell/pisellos 0.0.568 → 0.0.569

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

@@ -1,73 +1,208 @@
 import { CartItem } from '../Cart/types';
-import type { ScanOrderTempOrder, ScanOrderOrderProduct, ScanOrderOrderProductIdentity, ScanOrderSummary } from '../../solution/ScanOrder/types';
 import type { DiscountModule } from '../Discount';
 import type { RulesModule } from '../Rules';
 import type { Discount } 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 declare enum OrderHooks {
     OnOrderCreate = "order:onOrderCreate",
     OnOrderUpdate = "order:onOrderUpdate",
     OnOrderCancel = "order:onOrderCancel",
-    OnOrderStatusChange = "order:onOrderStatusChange"
+    OnOrderStatusChange = "order:onOrderStatusChange",
+    OnOrderCustomerChange = "order:onOrderCustomerChange",
+    OnPromotionApplied = "order:onPromotionApplied"
 }
-export interface OrderState {
-    tempOrder: ScanOrderTempOrder | null;
-    discountList: any[];
-    discount: DiscountModule | null;
-    rules: RulesModule | null;
-    availableWalletIds?: number[];
+/**
+ * 促销评估器协议（OS 与 PromotionEvaluator 之间的桥接接口）。
+ *
+ * 与 `pisell_os/src/model/strategy/adapter/promotion/evaluator.ts` 中的
+ * `PromotionEvaluator` 实例结构保持兼容。SalesSdkProvider 会从 `appHelper.utils.promotionEvaluator`
+ * 读取实例并通过 `setPromotionEvaluator` 注入到 OrderModule。
+ *
+ * 这里只声明 OrderModule 需要调用的子集，避免反向依赖具体 evaluator 实现。
+ */
+export interface OrderPromotionEvaluator {
+    evaluateCartWithPricing(input: {
+        products: any[];
+        channel?: string;
+    }): any;
+    getProductsApplicableStrategies(input: {
+        products: any[];
+        channel?: string;
+    }, matchVariant?: boolean): any[];
+    getStrategyConfigs?: () => unknown[];
 }
-/** 更新购物车行：仅传 SKU 时命中同 SKU 第一行；多行同 SKU 须传 identity_key / 选项指纹等 */
-export interface UpdateProductInOrderParams {
-    product_id: number | null;
-    product_variant_id: number;
-    updates: Partial<ScanOrderOrderProduct>;
-    identity_key?: string;
-    product_option_item?: any[];
-    product_bundle?: any[];
+/** 赠品解析回调 context（OS → SDK 的请求体） */
+export interface OrderGiftSelectContext {
+    strategyId: string;
+    strategyName: string | Record<string, string>;
+    giftCount: number;
+    giftOptions: Array<{
+        product_id: number;
+        product_variant_id: number;
+    }>;
+    /** 触发此赠品的主商品 metadata.unique_identification_number 列表 */
+    sourceProductIds: string[];
 }
 /**
- * 订单信息
+ * 赠品 resolver 返回值。
+ *
+ * @example
+ * return { products: [giftProduct], bookings: [giftBooking] };
  */
-export interface CommitOrderParams {
-    url?: string;
-    query: {
-        cartItems: CartItem[];
-        type: 'virtual' | 'appointment_booking';
-        platform?: 'pc' | 'h5';
-        extraData?: Record<string, any>;
-        business_code?: string;
+export interface OrderGiftSelectResult {
+    /** 完整赠品购物车行，必须带 metadata._giftInfo。 */
+    products: Partial<OrderProduct>[];
+    /** 预约赠品对应的 booking，按 products 下标一一关联。 */
+    bookings?: AddProductBookingInput[];
+}
+/**
+ * 赠品解析回调签名（SDK → OS 的返回值）。
+ *
+ * - 单选项：SDK 内部自动构造商品，不弹窗
+ * - 多选项：SDK 弹窗等用户确认后构造
+ * - 用户取消：抛错或返回空数组（OS 视为放弃本次添加）
+ *
+ * 返回数组时沿用旧协议，只写 tempOrder.products；返回对象时可同时写入预约 bookings。
+ */
+export type OrderGiftSelectResolver = (ctx: OrderGiftSelectContext) => Promise<Partial<OrderProduct>[] | OrderGiftSelectResult | null>;
+/** 未满足的促销策略（购物车底部 alert 渲染源） */
+export interface OrderUnfulfilledPromotion {
+    strategyId: string;
+    strategyName: string | Record<string, string>;
+    actionType: string;
+    needQuantity: number;
+    currentQuantity: number;
+    requiredQuantity: number;
+    eligibleProducts: Array<{
+        product_id: number;
+        product_variant_id: number;
+    }>;
+    strategyMetadata?: any;
+    display?: {
+        text: string | Record<string, string>;
+        type: string;
     };
 }
-export interface SubmitScanOrderProduct {
-    order_detail_id: number | null;
+/** 上一次 applyPromotion 计算出的赠品操作（仅供调试/读取使用） */
+export interface OrderLastGiftActions {
+    toAdd: Array<{
+        strategyId: string;
+        strategyName: string | Record<string, string>;
+        giftCount: number;
+        giftOptions: Array<{
+            product_id: number;
+            product_variant_id: number;
+        }>;
+        sourceProductIds: string[];
+    }>;
+    toReduce: Array<{
+        strategyId: string;
+        items: Array<{
+            uid: string;
+            currentQuantity: number;
+            newQuantity: number;
+        }>;
+    }>;
+    toRemove: string[];
+}
+/** onPromotionApplied 事件 payload */
+export interface OrderPromotionAppliedPayload {
+    unfulfilledPromotions: OrderUnfulfilledPromotion[];
+    giftActions: OrderLastGiftActions;
+    /** evaluator 返回的赠品摘要 */
+    gifts: Array<{
+        strategyId: string;
+        strategyName: string | Record<string, string>;
+        giftCount: number;
+        giftOptions: Array<{
+            product_id: number;
+            product_variant_id: number;
+        }>;
+    }>;
+    /** 处理后的商品列表 */
+    products: OrderProduct[];
+}
+/**
+ * tempOrder 上的下单客户协议字段视图。
+ * 这些字段会随订单提交到后端。
+ *
+ * customer_id 与 OrderTempOrder.customer_id 保持一致（number | null），
+ * 调用方若持有 string id（如 ICustomer.id 联合类型），需自行 Number() 转型。
+ */
+export interface OrderCustomerView {
+    customer_id: number | null;
+    customer_name: string;
+    phone: string;
+    email: string;
+    country_calling_code: string;
+}
+/**
+ * 写入下单客户的协议字段输入。
+ * `customer_id` 必传（null 表示无客户）；其余字段缺省视为「清空」（全量覆盖语义）。
+ */
+export interface OrderCustomerPatch {
+    customer_id: number | null;
+    id?: number | null;
+    customer_name?: string;
+    phone?: string;
+    email?: string;
+    country_calling_code?: string;
+}
+/**
+ * 下单客户变更事件 payload。
+ * - `patch`：tempOrder 上的协议字段视图（会随订单提交）
+ * - `snapshot`：UI 富字段快照（仅本地，不随订单提交）
+ * 清空时整个 payload 为 null。
+ */
+export interface OrderCustomerChangePayload {
+    patch: OrderCustomerView;
+    snapshot: ICustomer | null;
+}
+export interface OrderScanCodeResult {
+    isAvailable: boolean;
+    discountList: Discount[];
+    scannedDiscountList: Discount[];
+    type: 'server' | 'clientCalc';
+    unavailableReason?: UnavailableReason;
+}
+export interface OrderProductIdentity {
     product_id: number | null;
-    num: number;
     product_variant_id: number;
-    product_option_item: any[];
-    /**
-     * 行 composite 券后单价。
-     * 公式：`metadata.main_product_selling_price` + Σ(bundle_selling_price × num)。
-     * 主商品（含 option、含主商品折扣）的单价存在 `metadata.main_product_selling_price`。
-     */
+    unique_identification_number?: string;
+    product_sku?: OrderProductSku;
+    product_bundle?: any[];
+}
+export interface OrderProductSku {
+    option: any[];
+    [key: string]: any;
+}
+export interface OrderLocalizedText {
+    [locale: string]: string | null;
+}
+export interface OrderProduct extends OrderProductIdentity {
+    order_detail_id: number | null;
+    num: number;
+    bundle_edit?: number;
+    product_sku: OrderProductSku;
+    gift_card?: number;
     selling_price: string;
-    /**
-     * 行 composite 券前单价。
-     * 公式：`metadata.main_product_original_price` + Σ(bundle 原价 × num)。
-     * 主商品（含 option、不含折扣）的单价存在 `metadata.main_product_original_price`。
-     */
     original_price: string;
-    /** 出站兼容字段，直接由 `selling_price` 派生，语义同 composite。 */
-    payment_price: string;
     tax_fee: string;
     is_charge_tax: number;
-    discount_list: any[];
+    discount_list: OrderProductDiscountItem[];
     product_bundle: any[];
+    booking_uid?: string;
+    product_title?: OrderLocalizedText;
+    product_cover?: string;
     metadata: Record<string, any>;
-    /** 商品行备注 */
     note?: string;
 }
-export interface SubmitScanOrderSummary {
+export interface OrderSummary {
     product_quantity: number;
     product_original_amount: string;
     product_amount: string;
@@ -77,15 +212,192 @@ export interface SubmitScanOrderSummary {
     shipping_tax_fee: string;
     tax_fee: string;
     surcharge_fee: string;
+    surcharges: any[];
     discount_amount: string;
     deposit_amount: string;
+    deposit?: {
+        total: string;
+        deposit_policy_ids: number[];
+        deposit_policy_data?: any[];
+        hasDeposit: boolean;
+    };
     expect_amount: string;
     total_amount: string;
+    total_refund_amount: string;
+    customer_paid_amount: string;
+    order_paid_amount: string;
     amount_gap: string;
     rounding_amount: string;
     pay_service_charge_amount: string;
+    tax_title?: string;
+    tax_rate?: number;
+}
+export interface OrderTempOrder {
+    order_id: number | null;
+    external_sale_number: string;
+    order_number: string | null;
+    shop_order_number: string | null;
+    shop_full_order_number: string | null;
+    type: string;
+    business_code?: string;
+    platform: string;
+    sales_channel: string;
+    order_sales_channel: string;
+    vouchers: any[];
+    status: string;
+    payment_status: string;
+    shipping_status: string;
+    customer_id: number | null;
+    customer_name: string;
+    country_calling_code: string;
+    phone: string;
+    email: string;
+    customer?: Record<string, any> | null;
+    is_price_include_tax: number;
+    tax_title: string;
+    tax_country_code: string;
+    currency_code: string;
+    currency_symbol: string;
+    currency_format: string;
+    is_deposit: number;
+    deposit_amount: string;
+    shop_discount: string;
+    surcharge_fee: string;
+    note: string;
+    buzzer?: string;
+    delivery_type?: string;
+    table_number?: Record<string, any>;
+    schedule_date: string;
+    created_at: string | undefined;
+    request_unique_idempotency_token?: string;
+    products: OrderProduct[];
+    bookings: any[];
+    payments: any[];
+    surcharges: any[];
+    discount_list?: any[];
+    relation_forms: any[];
+    contacts: any[];
+    contacts_info: Record<string, any> | null;
+    holder: Record<string, any> | null;
+    metadata: Record<string, any>;
+    summary?: OrderSummary;
+    _extend?: {
+        productsByUid?: Record<string, Record<string, any>>;
+        [key: string]: any;
+    };
+}
+export interface OrderSubmitProduct extends Omit<OrderProduct, 'unique_identification_number' | 'num'> {
+    product_quantity: number;
+    payment_price: string;
+    product_sku: OrderProductSku;
+}
+export interface OrderSubmitPayload extends Omit<OrderTempOrder, 'platform' | 'products' | '_extend' | 'customer' | 'discount_list' | 'created_at'> {
+    platform: string;
+    created_at?: string | undefined;
+    request_unique_idempotency_token?: string;
+    form_record_ids?: Array<{
+        form_id: number | string;
+        form_record_id: number | string;
+    }>;
+    products: OrderSubmitProduct[];
+    summary?: OrderSummary;
+    small_ticket_data_flag?: number;
+}
+export interface OrderState {
+    tempOrder: OrderTempOrder | null;
+    summary?: OrderSummary;
+    lastOrderInfo?: Record<string, any>;
+    syncState?: OrderSyncState;
+    discountList: any[];
+    availableWalletIds?: number[];
+    discount: DiscountModule | null;
+    rules: RulesModule | null;
+}
+export interface ReplaceTempOrderOptions {
+    recalculateSummary?: boolean;
+    persist?: boolean;
+    saveDraft?: boolean;
+}
+export type AddProductBookingInput = Record<string, any>;
+/** 更新购物车行：仅传 SKU 时命中同 SKU 第一行；多行同 SKU 须传 unique_identification_number / 选项指纹等 */
+export interface UpdateOrderProductParams {
+    product_id: number | null;
+    product_variant_id: number;
+    updates: Partial<OrderProduct>;
+    unique_identification_number?: string;
+    identity_key?: string;
+    product_sku?: OrderProductSku;
+    product_bundle?: any[];
+    booking?: AddProductBookingInput;
+    /**
+     * 预约时间 / 时长变更后允许使用本次报价覆盖已落库订单行历史价。
+     *
+     * @example
+     * await order.updateOrderProduct({
+     *   product_id: 1,
+     *   product_variant_id: 0,
+     *   updates: { selling_price: '6.00', metadata: { source_product_price: '6.00' } },
+     *   booking: { duration: 2 },
+     *   allow_booking_reprice: true,
+     * });
+     */
+    allow_booking_reprice?: boolean;
+    /**
+     * Change time 重报价后，允许当前预约商品行重新应用已选编辑态折扣卡。
+     *
+     * @example
+     * await order.updateOrderProduct({
+     *   product_id: 1,
+     *   product_variant_id: 0,
+     *   updates: { discount_list: [] },
+     *   booking: { duration: 2 },
+     *   allow_booking_discount_reapply: true,
+     * });
+     */
+    allow_booking_discount_reapply?: boolean;
+}
+/** 仅更新购物车行数量；行定位语义与 updateOrderProduct / removeProductFromOrder 保持一致 */
+export interface UpdateOrderProductQuantityParams extends OrderProductIdentity {
+    num: number;
+    identity_key?: string;
 }
-export interface SubmitScanOrderBooking {
+export interface UpdateOrderBookingParams {
+    unique_identification_number: string;
+    updates: AddProductBookingInput;
+}
+export interface OrderProductMergeDecisionContext {
+    incomingProduct: Partial<OrderProduct> & OrderProductIdentity;
+    normalizedIncoming: OrderProduct;
+    matchedProduct: OrderProduct;
+    matchedIndex: number;
+    incomingFingerprint: string;
+    existedFingerprint: string;
+    tempOrder: OrderTempOrder;
+    booking?: AddProductBookingInput;
+    defaultShouldMerge: boolean;
+}
+export type OrderProductMergeDecisionResult = boolean | {
+    shouldMerge: boolean;
+    reason?: string;
+    [key: string]: any;
+};
+export interface OrderHooksConfig {
+    onBeforeMergeProductToOrder?: (context: OrderProductMergeDecisionContext) => OrderProductMergeDecisionResult | Promise<OrderProductMergeDecisionResult>;
+}
+/**
+ * 订单信息
+ */
+export interface CommitOrderParams {
+    url?: string;
+    query: {
+        cartItems: CartItem[];
+        type: 'virtual' | 'appointment_booking';
+        platform?: string;
+        extraData?: Record<string, any>;
+        business_code?: string;
+    };
+}
+export interface OrderSubmitBooking {
     relation_id?: string;
     form_id?: string;
     collect_pax?: number;
@@ -95,22 +407,21 @@ export interface SubmitScanOrderBooking {
     resources?: Array<Record<string, any>>;
     product_uid?: string;
 }
-export interface SubmitScanOrderFormRecord {
+export interface OrderSubmitFormRecord {
     form_id: number | string;
     form_record_id: number | string;
 }
-export interface SubmitScanOrderParams {
+export interface SubmitSalesOrderParams {
     url?: string;
     query: {
         order_id: number | null;
-        relation_id?: string;
-        table_form_id?: string;
-        resource_id?: string;
-        order_number: string;
-        shop_order_number: string;
+        external_sale_number: string;
+        order_number: string | null;
+        shop_order_number: string | null;
+        shop_full_order_number: string | null;
         type: string;
-        business_code: string;
-        platform: 'H5' | 'PC';
+        business_code?: string;
+        platform: string;
         request_unique_idempotency_token?: string;
         sales_channel: string;
         order_sales_channel: string;
@@ -136,27 +447,20 @@ export interface SubmitScanOrderParams {
         delivery_type?: string;
         table_number?: Record<string, any>;
         schedule_date: string;
-        created_at?: string;
-        products: SubmitScanOrderProduct[];
-        bookings: SubmitScanOrderBooking[];
+        created_at?: string | undefined;
+        products: OrderSubmitProduct[];
+        bookings: OrderSubmitBooking[];
         payments: any[];
+        vouchers: any[];
         surcharges?: any[];
-        discount_list: any[];
         relation_forms: any[];
-        form_record_ids?: SubmitScanOrderFormRecord[];
+        form_record_ids?: OrderSubmitFormRecord[];
         contacts: any[];
-        contacts_info: any[];
+        contacts_info: Record<string, any> | null;
         holder: Record<string, any> | null;
-        summary?: SubmitScanOrderSummary;
         metadata: Record<string, any>;
-    };
-}
-export interface ScanOrderMoreParams {
-    url?: string;
-    query: {
-        order_id: number | string;
-        products: SubmitScanOrderProduct[];
-        request_unique_idempotency_token?: string;
+        summary?: OrderSummary;
+        small_ticket_data_flag?: number;
     };
 }
 /**
@@ -169,15 +473,138 @@ export interface PaymentItemData {
     amount: string;
     /** 支付类型代码 */
     code: string;
-    /** 支付类型id */
-    id: number;
+    /** @deprecated use custom_payment_id */
+    id?: number;
+    /** 支付方式 ID */
+    custom_payment_id?: number;
     /** 支付类型名称 */
     name: string;
     /** 支付类型 */
     type: string;
-    /** 是否已同步到后端 */
+    /** 支付时间 (格式: YYYY-MM-DD HH:mm:ss) */
+    payment_time?: string;
+    /** 支付项创建时间 (格式: YYYY-MM-DD HH:mm:ss) */
+    created_at?: string;
+    /** @deprecated BaseSales/Sales 协议不提交该字段；旧 Checkout/Payment 内部仍可能使用 */
     isSynced?: boolean;
 }
+export interface OrderPaymentMetadata {
+    rounding_rule?: Record<string, any>;
+    unique_payment_number?: string;
+    shop_wallet_pass_id?: number | string;
+    actual_paid_amount?: number | string;
+    change_given_amount?: number | string;
+    [key: string]: any;
+}
+export interface OrderPaymentData {
+    order_payment_id?: number | string;
+    amount: string;
+    code: string;
+    custom_payment_id: number;
+    custom_payment_type?: string;
+    name: string;
+    type: string;
+    voucher_id?: string | number;
+    origin_amount?: string;
+    service_fee?: string;
+    status?: 'active' | 'paid' | 'voided' | 'payment_pending' | string;
+    /** 支付时间 (格式: YYYY-MM-DD HH:mm:ss) */
+    payment_time?: string;
+    wallet_pass_usage_unit?: unknown;
+    wallet_pass_use_value?: string | number | null;
+    fund_record?: Record<string, any>;
+    metadata: OrderPaymentMetadata;
+    rounding_amount?: string;
+    service_charge?: {
+        percentage?: string;
+        amount?: string;
+    };
+    order_payment_type?: 'normal' | 'deposit';
+    /** 支付项创建时间 (格式: YYYY-MM-DD HH:mm:ss) */
+    created_at?: string;
+    updated_at?: string;
+}
+export type OrderPaymentSource = PaymentItem | OrderPaymentData | Record<string, any>;
+export interface MapOrderPaymentsOptions {
+    includeVoided?: boolean;
+}
+export type OrderSyncState = 'local' | 'submitting' | 'submitted' | 'failed' | 'remoteLoaded';
+export interface LoadSalesDetailParams {
+    orderId?: number | string;
+    orderNumber?: string;
+    externalSaleNumber?: string;
+    external_sale_number?: string;
+    /**
+     * 已由调用方查询到的销售详情记录。
+     * 存在时 loadSalesDetail 会跳过远端 lookup，直接复用 hydrate 后半段逻辑。
+     */
+    preloadedSalesDetail?: Record<string, any>;
+    forceRemote?: boolean;
+    merge?: boolean;
+}
+export interface SalesOrderLookupParams {
+    lookup: number | string;
+    forceRemote?: boolean;
+}
+export interface SyncPaymentsToOrderParams {
+    payments: OrderPaymentSource[];
+    paymentStatus?: SubmitSalesOrderParams['query']['payment_status'];
+    submitWhenPaid?: boolean;
+    /**
+     * Whether the checkout should be queued as the local `sync_sales` task.
+     * Defaults to true to preserve the WebPOS retry path. Set to false when
+     * the caller must wait for the cloud checkout response before proceeding.
+     */
+    checkoutSyncTaskEnabled?: boolean;
+    smallTicketDataFlag?: number;
+    businessCode?: string;
+    channel?: string;
+    confirmPendingVoucherPayments?: boolean;
+}
+export interface SyncPaymentsToOrderResult<T = any> {
+    isFullyPaid: boolean;
+    isOrderFullyPaid: boolean;
+    isDepositFullyPaid: boolean;
+    paymentStage: 'deposit' | 'normal';
+    depositAmount: string;
+    orderExpectedAmount: string;
+    submitResult?: T;
+}
+export interface OrderIdentitySnapshot {
+    localId?: string;
+    orderId?: number | string | null;
+    externalSaleNumber?: string;
+    orderNumber?: string;
+    shopOrderNumber?: string;
+    shopFullOrderNumber?: string;
+    isSubmitted: boolean;
+}
+export interface OrderAmountSnapshot {
+    isDeposit: boolean;
+    depositAmount: string;
+    expectAmount: string;
+    totalAmount: string;
+    amountGap: string;
+    summary: OrderSummary;
+}
+export interface OrderSnapshot {
+    identity: OrderIdentitySnapshot;
+    syncState: OrderSyncState;
+    amount: OrderAmountSnapshot;
+    status: string;
+    paymentStatus: string;
+    shippingStatus: string;
+    note: string;
+    customer: {
+        customerId: number | null;
+        customerName: string;
+        phone: string;
+        email: string;
+    };
+    productCount: number;
+    lastOrderInfo?: Record<string, any>;
+    tempOrder: OrderTempOrder;
+}
 /**
  * Checkout 专用订单创建参数
  */
@@ -198,6 +625,19 @@ export interface CheckoutOrderParams {
     small_ticket_data_flag?: number;
     [key: string]: any;
 }
+/**
+ * 取消订单参数
+ */
+export interface CancelOrderParams {
+    order_ids: Array<number | string>;
+}
+/**
+ * 变更预约状态参数
+ */
+export interface ChangeBookingStatusParams {
+    booking_id: number | string;
+    appointment_status: string;
+}
 /**
  * 订单模块 API
  */
@@ -214,28 +654,62 @@ export interface OrderModuleAPI {
      * @returns 后端返回的订单数据
      */
     createOrderByCheckout: (params: CheckoutOrderParams) => Promise<any>;
-    submitScanOrder: <T = any>(params: SubmitScanOrderParams) => Promise<T>;
-    scanOrderMore: <T = any>(params: ScanOrderMoreParams) => Promise<T>;
+    submitSalesOrder: <T = any>(params: SubmitSalesOrderParams) => Promise<T>;
     initTempOrder: (params: {
         cacheId?: string;
         salesSummaryModuleName?: string;
     }) => void;
-    getTempOrder: () => ScanOrderTempOrder | null;
-    ensureTempOrder: () => ScanOrderTempOrder;
-    addNewOrder: () => Promise<ScanOrderTempOrder>;
-    restoreOrder: () => ScanOrderTempOrder;
-    getOrderProducts: () => ScanOrderOrderProduct[];
-    getScanOrderSummary: () => Promise<ScanOrderSummary>;
+    getTempOrder: () => OrderTempOrder | null;
+    ensureTempOrder: () => OrderTempOrder;
+    replaceTempOrder: (tempOrder: OrderTempOrder, options?: ReplaceTempOrderOptions) => Promise<OrderTempOrder>;
+    addNewOrder: () => Promise<OrderTempOrder>;
+    restoreOrder: () => OrderTempOrder;
+    getOrderProducts: () => OrderProduct[];
+    getOrderSummary: () => Promise<OrderSummary>;
     recalculateSummary: (options?: {
         createIfMissing?: boolean;
-    }) => Promise<ScanOrderSummary | null>;
-    updateTempOrderNote: (note: string) => string;
+    }) => Promise<OrderSummary | null>;
+    getOrderIdentity: () => OrderIdentitySnapshot | null;
+    getOrderSnapshot: () => OrderSnapshot | null;
+    getOrderSyncState: () => OrderSyncState;
+    getOrderAmountSnapshot: () => OrderAmountSnapshot | null;
+    buildCurrentSubmitPayloadForLocalPrint: (params?: {
+        cacheId?: string;
+        platform?: string;
+        businessCode?: string;
+        channel?: string;
+        type?: string;
+    }) => OrderSubmitPayload;
+    applyLocalPrintOrderNumbers: (order?: Record<string, any> | null) => Promise<OrderTempOrder>;
+    getTempOrderNote: () => string;
+    updateTempOrderNote: {
+        (note: string): string;
+        (note: string, sync: true): Promise<string>;
+        (note: string, sync: boolean): string | Promise<string>;
+    };
+    updateTempOrderShopDiscount: (amount: string | number) => string;
+    updateTempOrderDepositAmount: (amount: string | number) => OrderSummary;
+    updateTempOrderCustomer: (customer: UpdateTempOrderCustomerInput) => OrderSnapshot['customer'];
     updateTempOrderBuzzer: (buzzer: string) => string;
-    updateTempOrderContactsInfo: (contactsInfo: any[]) => any[];
-    addProductToOrder: (product: Partial<ScanOrderOrderProduct> & ScanOrderOrderProductIdentity) => Promise<ScanOrderOrderProduct[]>;
-    updateProductInOrder: (params: UpdateProductInOrderParams) => Promise<ScanOrderOrderProduct[]>;
-    removeProductFromOrder: (identity: ScanOrderOrderProductIdentity) => Promise<ScanOrderOrderProduct[]>;
+    updateTempOrderContactsInfo: (contactsInfo: Record<string, any> | null) => Record<string, any> | null;
+    addProductToOrder: (product: Partial<OrderProduct> & OrderProductIdentity, booking?: AddProductBookingInput) => Promise<OrderProduct[]>;
+    updateOrderProduct: (params: UpdateOrderProductParams) => Promise<OrderProduct[]>;
+    /** 批量更新购物车行，末尾仅触发一次促销重算与 summary 刷新 */
+    updateOrderProducts: (paramsList: UpdateOrderProductParams[]) => Promise<OrderProduct[]>;
+    updateOrderProductQuantity: (params: UpdateOrderProductQuantityParams) => Promise<OrderProduct[]>;
+    updateOrderBooking: (params: UpdateOrderBookingParams) => any[];
+    removeProductFromOrder: (identity: OrderProductIdentity) => Promise<OrderProduct[]>;
+    /** 批量删除购物车行，末尾仅触发一次促销重算与 summary 刷新 */
+    removeProductsFromOrder: (identities: OrderProductIdentity[]) => Promise<OrderProduct[]>;
+    /** @deprecated no-op；OrderModule 不再负责 tempOrder localStorage 持久化。 */
     persistTempOrder: () => void;
+    /**
+     * 控制 IndexedDB 草稿（saveDraft）开关；localStorage tempOrder 持久化已废弃。
+     * BigSale 弹窗等场景传 false 可跳过 saveDraft。
+     */
+    setEnableTempOrderPersist: (enabled: boolean) => void;
+    /** 是否允许 saveDraft 写入 IndexedDB 草稿。 */
+    isTempOrderPersistEnabled: () => boolean;
     /** 提交 tempOrder 变更并触发 `{moduleName}:changed` 事件 */
     notifyTempOrderChanged: () => void;
     submitTempOrder: <T = any>(params?: {
@@ -244,13 +718,144 @@ export interface OrderModuleAPI {
         businessCode?: string;
         channel?: string;
         type?: string;
+        payments?: OrderPaymentSource[];
+        paymentStatus?: SubmitSalesOrderParams['query']['payment_status'];
+        smallTicketDataFlag?: number;
+        confirmPendingVoucherPayments?: boolean;
         enhancePayload?: SubmitPayloadEnhancer;
     }) => Promise<T>;
+    submitTempOrderAsync: <T = any>(params?: {
+        cacheId?: string;
+        platform?: string;
+        businessCode?: string;
+        channel?: string;
+        type?: string;
+        payments?: OrderPaymentSource[];
+        paymentStatus?: SubmitSalesOrderParams['query']['payment_status'];
+        smallTicketDataFlag?: number;
+        confirmPendingVoucherPayments?: boolean;
+        enhancePayload?: SubmitPayloadEnhancer;
+    }) => Promise<T>;
+    getOrderPayments: () => OrderPaymentData[];
+    setOrderPayments: (payments: OrderPaymentSource[]) => OrderPaymentData[];
+    addOrderPayment: (payment: OrderPaymentSource) => OrderPaymentData[];
+    updateOrderPayment: (paymentIdentity: string | number, updates: Partial<OrderPaymentData> & Record<string, any>) => OrderPaymentData[];
+    deleteOrderPayment: (paymentIdentity: string | number) => OrderPaymentData[];
+    updateVoucherOrderPayments: (payments: OrderPaymentSource[], options?: {
+        status?: 'paid' | 'payment_pending';
+    }) => OrderPaymentData[];
+    confirmPendingVoucherPayments: (options?: {
+        persist?: boolean;
+        recalculateSummary?: boolean;
+    }) => OrderPaymentData[];
+    discardPendingVoucherPayments: (options?: {
+        persist?: boolean;
+        recalculateSummary?: boolean;
+    }) => OrderPaymentData[];
+    sendCustomerPayLink: <T = any>(params: SendCustomerPayLinkParams) => Promise<T>;
+    saveDraft: () => Promise<void>;
+    hydrateTempOrderFromRecord: (record: Record<string, any>, options?: {
+        recalcOnHydrate?: boolean;
+    }) => Promise<OrderTempOrder>;
+    syncPaymentsToOrder: <T = any>(params: SyncPaymentsToOrderParams) => Promise<SyncPaymentsToOrderResult<T>>;
+    getSalesOrderByLookup: (params: SalesOrderLookupParams) => Promise<any>;
+    getLastOrderInfo: () => Record<string, any> | undefined;
+    getOrderInfo: (order_id: number) => Promise<any>;
+    /**
+     * 写入当前下单客户。
+     *
+     * 语义为「全量覆盖」：`patch` 中未提供的协议字段会被清空（写为 ''）。
+     * snapshot 用于保存 UI 富字段（wallet/会员/地址等），不会随订单提交。
+     *
+     * @param patch    tempOrder 协议字段；传 null 等价于 clearOrderCustomer。
+     * @param snapshot UI 富字段快照。undefined 表示不动既有 snapshot；
+     *                 null 表示显式清空 snapshot；ICustomer 写入并 cloneDeep。
+     */
+    setOrderCustomer: (patch: OrderCustomerPatch | null, snapshot?: ICustomer | null) => void;
+    /** 读取 tempOrder 的客户协议字段；customer_id 缺失时返回 null。 */
+    getOrderCustomer: () => OrderCustomerView | null;
+    /** 读取 _extend.customerSnapshot；不存在时返回 null。 */
+    getOrderCustomerSnapshot: () => ICustomer | null;
+    /** 清空 tempOrder 协议字段 + _extend.customerSnapshot，并 emit 变更事件 payload=null。 */
+    clearOrderCustomer: () => void;
     loadDiscountConfig: (params: {
         customerId: number;
-        action?: 'create';
-    }) => Promise<void>;
+        action?: 'create' | 'edit';
+        orderId?: number;
+        apply?: boolean;
+    }) => Promise<Discount[]>;
     getDiscountList: () => Discount[];
     getAvailableWalletIds: () => number[];
     applyDiscount: () => void;
+    /**
+     * 注入促销评估器。
+     *
+     * SalesSdkProvider 在初始化 bookingTicket 后会自动从 `appHelper.utils.promotionEvaluator`
+     * 读取实例并调用本方法注入。host 透明，业务 UI 不感知。
+     *
+     * @example
+     * order.setPromotionEvaluator(appHelper.utils.promotionEvaluator);
+     */
+    setPromotionEvaluator: (evaluator: OrderPromotionEvaluator | null) => void;
+    /**
+     * 注入赠品选择 resolver。OS 在 applyPromotion 内部当需要新增赠品时会 await 调用 resolver。
+     *
+     * 缺省时 OS 会 `console.warn` 并跳过新增（既有赠品的 reduce/remove 仍会执行）。
+     *
+     * @example
+     * order.setGiftSelectResolver((ctx) => giftSelectBridge.request(ctx));
+     */
+    setGiftSelectResolver: (resolver: OrderGiftSelectResolver | null) => void;
+    /**
+     * 为商品目录追加促销标签。
+     *
+     * @example
+     * const taggedProducts = order.appendPromotionTags(products);
+     */
+    appendPromotionTags: <T extends Record<string, any>>(products: T[]) => T[];
+    /**
+     * 应用购物车促销（评估 → 差异化赠品 → 写回 tempOrder.products → emit onPromotionApplied）。
+     *
+     * 自动在 addProductToOrder / updateOrderProductQuantity / removeProductFromOrder /
+     * clearOrderCartLines / setOrderCustomer 等写路径末尾触发，业务一般无需手动调用。
+     *
+     * 多选项赠品依赖 giftSelectResolver；如未注入则跳过且 console.warn。
+     * 内部以 `_isApplyingPromotion` flag 防递归。
+     */
+    applyPromotion: () => Promise<void>;
+    /** 读取上次 applyPromotion 产出的未满足促销提示 */
+    getUnfulfilledPromotions: () => OrderUnfulfilledPromotion[];
+    /** 读取上次 applyPromotion 产出的赠品操作 diff（toAdd / toReduce / toRemove） */
+    getLastGiftActions: () => OrderLastGiftActions | null;
+    /**
+   * 取消订单
+   * @param params 取消订单参数
+   * @returns 后端返回结果
+   */
+    cancelOrder: (params: CancelOrderParams) => Promise<any>;
+    /**
+     * 变更预约状态
+     * @param params 预约状态参数
+     * @returns 后端返回结果
+     */
+    changeBookingStatus: (params: ChangeBookingStatusParams) => Promise<any>;
+}
+export interface UpdateTempOrderCustomerInput {
+    customer_id?: number | string | null;
+    customerId?: number | string | null;
+    id?: number | string | null;
+    customer_name?: string;
+    customerName?: string;
+    display_name?: string;
+    name?: string;
+    country_calling_code?: string;
+    countryCallingCode?: string;
+    phone?: string;
+    email?: string;
+}
+export interface SendCustomerPayLinkParams {
+    emails: string[];
+    orderIds?: Array<number | string>;
+    order_ids?: Array<number | string>;
+    notify_action?: string;
 }