@pisell/pisellos 0.0.568 → 0.10.1

package/dist/solution/BaseSales/index.d.ts

@@ -0,0 +1,378 @@
+import { Module, ModuleOptions, PisellCore } from '../../types';
+import { BaseModule } from '../../modules/BaseModule';
+import { BaseSalesOrderProduct, BaseSalesOrderProductIdentity, BaseSalesPaymentStatus, BaseSalesUpdateOrderProductQuantityParams, BaseSalesCalculateProductBookingPriceParams, BaseSalesPriceRecalculationContextChange, BaseSalesProductBookingPriceResult, BaseSalesQuotationCustomerScopeInfo, BaseSalesScanCodeResult } from './types';
+import { OrderModule } from '../../modules/Order';
+import type { AddProductBookingInput, LoadSalesDetailParams, OrderPaymentData, OrderPaymentSource, SendCustomerPayLinkParams, SyncPaymentsToOrderParams, SyncPaymentsToOrderResult, UpdateTempOrderCustomerInput, UpdateOrderBookingParams, UpdateOrderProductParams, OrderTempOrder, OrderSummary, OrderPromotionEvaluator, OrderGiftSelectResolver, OrderUnfulfilledPromotion, OrderLastGiftActions } from '../../modules/Order/types';
+import type { SubmitPayloadEnhancer } from '../../modules/Order/utils';
+import type { Discount } from '../../modules/Discount/types';
+import { RequestPlugin, WindowPlugin } from '../../plugins';
+export * from './types';
+import { ProductList } from '../../modules/ProductList';
+import { PaymentModule } from '../../modules/Payment';
+import type { PaymentMethod } from '../../modules/Payment/types';
+import type { SalesSummaryModule } from '../../modules/SalesSummary';
+import type { ScheduleModule } from '../../modules/Schedule';
+import { QuotationModule } from '../../modules/Quotation';
+import type { ISalesDetail, ISalesDetailHeader, ISalesBooking, ISalesPayment, ISalesSurcharge } from './utils/parseSalesResponse';
+import { AppPlugin } from '../../plugins/app';
+import { type TransformBaseProductToOrderProductParams } from './utils/transformBaseProductToOrderProduct';
+export interface BaseSalesState {
+    order?: OrderModule;
+    products?: ProductList;
+    payment?: PaymentModule;
+    salesSummary?: SalesSummaryModule;
+    schedule?: ScheduleModule;
+    quotation?: QuotationModule;
+}
+export type BaseSalesPrintLocalOrderReceiptParams = string | number;
+export declare class BaseSalesImpl extends BaseModule implements Module {
+    protected defaultName: string;
+    protected defaultVersion: string;
+    isSolution: boolean;
+    protected initializeOptions: ModuleOptions;
+    protected logger: any;
+    protected appPlugin: AppPlugin;
+    protected store: BaseSalesState;
+    protected otherParams: Record<string, any>;
+    protected cacheId: string | undefined;
+    /**
+     * window / request 暴露为 public：现存外部工具（如 BookingTicket Scan）通过
+     * `solution.window` / `solution.request` 直接访问插件，保持原有契约不破坏。
+     */
+    window: WindowPlugin;
+    request: RequestPlugin;
+    protected currentSalesDetail: ISalesDetail | null;
+    protected discountConfigCacheKey: string | null;
+    protected hasManualDiscountSelection: boolean;
+    private readonly reusedSharedSubModuleNames;
+    private paymentMethodsCache;
+    private queuedAutoPaymentSync;
+    private autoPaymentSyncFlushing;
+    private autoPaymentSyncTimer;
+    private salesDetailLoadInFlightCount;
+    private salesDetailLoadSequence;
+    private salesDetailHydrateQueue;
+    private serverOrderChangeUnsubscribe;
+    private serverOrderChangeHydrateInFlight;
+    private queuedServerOrderChanges;
+    private serverOrderChangeSyncEnabled;
+    constructor(name?: string, version?: string);
+    /**
+     * 子类可覆盖此方法以追加/收敛要注册的子模块。
+     * 默认包含通用销售模块：products / order / salesSummary / schedule / payment / quotation。
+     */
+    protected getRegisteredModuleNames(): readonly string[];
+    private getReusableSharedSubModule;
+    private isScheduleListLoaded;
+    /**
+     * 记录信息日志
+     */
+    private logInfo;
+    /**
+     * 记录警告日志
+     */
+    private logWarning;
+    /**
+     * 记录错误日志
+     */
+    private logError;
+    private isCurrentSalesOrderRecord;
+    setServerOrderChangeSyncEnabled(enabled: boolean): void;
+    private queueLatestServerOrderChange;
+    private drainQueuedServerOrderChanges;
+    private syncCurrentSalesDetailFromServerOrderChange;
+    private registerServerOrderChangeSync;
+    private hydrateLatestLoadedSalesDetail;
+    private hydrateOrderPaymentNames;
+    get payment(): PaymentModule | undefined;
+    private getCurrentOrderCustomerId;
+    private normalizePriceContextCustomerId;
+    private applyQuotationScheduleResolver;
+    private loadQuotationForPriceQuery;
+    private getPriceQueryProductId;
+    private getPriceQuerySchedule;
+    private loadProductsForPriceQuery;
+    private loadProductForPriceQuery;
+    private getAuthoritativeBundleItems;
+    private findAuthoritativeBundleItem;
+    private getAuthoritativeBundleUnitPrice;
+    private mergeProductForPriceQuery;
+    protected getSubmitOrderSalesChannel(): string | undefined;
+    /**
+     * 工厂入口：根据子模块名实例化对应模块。
+     * 默认使用 BookingByStep 公共 `createModule`。子类若需引入额外类型（如 customer），
+     * 可覆盖此方法并把未识别的 name 委托给 `super.createSubModule(name)`。
+     */
+    protected createSubModule(moduleName: string): Module | null;
+    protected getSubModuleHooks(moduleName: string): any;
+    /**
+     * 构造传给 BaseSales 子模块的完整运行态参数，保证初始化和后续同步语义一致。
+     *
+     * @example
+     * const params = this.buildSubModuleOtherParams();
+     * this.core.registerModule(orderModule, { otherParams: params });
+     */
+    protected buildSubModuleOtherParams(): Record<string, any>;
+    /**
+     * 将父级 otherParams 的变更显式同步给已注册的子模块。
+     *
+     * @example
+     * await this.syncOtherParamsToSubModules({ channel: 'pos' });
+     */
+    protected syncOtherParamsToSubModules(changedParams: Record<string, any>, { cover }?: {
+        cover?: boolean;
+    }): Promise<void>;
+    /**
+     * 读取 sessionStorage[this.name][cacheId]，作为子模块 initialState 的来源。
+     * sessionStorage 损坏时静默忽略，按空状态注册。
+     */
+    protected readSessionCacheData(): Record<string, any>;
+    protected getAppData<T>(key: string): T | undefined;
+    private syncAppDataToTempOrder;
+    initialize(core: PisellCore, options?: ModuleOptions): Promise<void>;
+    destroy(): Promise<void>;
+    /**
+     * 加载销售订单到统一 tempOrder 工作区。
+     * 统一通过 OrderModule 的 sales detail lookup 加载订单详情。
+     *
+     * 子类可在 `super.loadSalesDetail` 之后基于返回的 `sales` 做业务侧装配
+     * （比如把 `sales.customer` 写入 CustomerModule、emit 业务 hook 等）。
+     */
+    loadSalesDetail(orderIdOrParams: number | string | LoadSalesDetailParams): Promise<ISalesDetail>;
+    /** 获取当前已加载的销售详情（只读快照）。未加载过则返回 null。 */
+    getSalesOrder(): ISalesDetail | null;
+    /** 获取销售详情顶部业务字段（订单号/状态/金额等通用字段集合）。 */
+    getOrderHeader(): ISalesDetailHeader | null;
+    /** 获取所有 booking（含 root + children），按服务端原始顺序输出。 */
+    getBookings(): ISalesBooking[];
+    /** 获取根 booking（is_next === 0 / is_root === 1），多个时取第一个。 */
+    getRootBooking(): ISalesBooking | null;
+    /** 按 product_uid 反查 booking 列表（用于商品行 ↔ booking 映射）。 */
+    getChildBookingsByProductUid(productUid: string): ISalesBooking[];
+    /** 获取支付列表（已支付/退款等明细）。 */
+    getPayments(): ISalesPayment[];
+    /** 获取附加费用（运费/服务费/税费等）。 */
+    getSurcharges(): ISalesSurcharge[];
+    getTempOrder(): OrderTempOrder | null;
+    replaceTempOrder(tempOrder: OrderTempOrder): Promise<OrderTempOrder>;
+    getOrderIdentity(): import("../../modules/Order/types").OrderIdentitySnapshot | null;
+    getOrderSnapshot(): import("../../modules/Order/types").OrderSnapshot | null;
+    getOrderSyncState(): import("../../modules/Order/types").OrderSyncState;
+    getOrderAmountSnapshot(): import("../../modules/Order/types").OrderAmountSnapshot | null;
+    getTempOrderNote(): string;
+    updateTempOrderNote(note: string): string;
+    updateTempOrderNote(note: string, sync: true): Promise<string>;
+    updateTempOrderNote(note: string, sync: boolean): string | Promise<string>;
+    updateRemoteOrderNote(orderId: number | string, note: string): void;
+    updateTempOrderShopDiscount(amount: string | number): string;
+    updateTempOrderDepositAmount(amount: string | number): OrderSummary;
+    updateTempOrderContactsInfo(contactsInfo: Record<string, any> | null): Record<string, any> | null;
+    /** @deprecated OrderModule 不再负责 tempOrder localStorage 持久化。 */
+    setEnableTempOrderPersist(enabled: boolean): void;
+    /** 是否允许 saveDraft 写入 IndexedDB 草稿。 */
+    isTempOrderPersistEnabled(): boolean;
+    private ensureTempOrder;
+    addNewOrder(): Promise<OrderTempOrder>;
+    saveDraft(): Promise<void>;
+    restoreOrder(): Promise<OrderTempOrder>;
+    /**
+     * 仅清空 tempOrder 购物车行（products / bookings / discount_list）。
+     * 同步清空内存中的 salesDetail 商品/预约视图，避免编辑态仍读到旧 bookings。
+     */
+    clearOrderCartLines(): Promise<OrderTempOrder>;
+    getOrderProducts(): import("../../modules/Order/types").OrderProduct[];
+    getSummary(): Promise<OrderSummary>;
+    private getHistoricalProductDiscountList;
+    private isPersistedOrderProduct;
+    private mergeHistoricalDiscountList;
+    private shouldSkipAutoApplyFetchedDiscountsInEditMode;
+    private mergeCurrentDiscountSelectionState;
+    loadDiscountConfig(params?: {
+        customerId?: number;
+        action?: 'create' | 'edit';
+    }): Promise<{
+        productList: Record<string, any>[];
+        discountList: Discount[];
+        availableWalletIds: number[];
+    }>;
+    getAvailableWalletIds(): number[];
+    bestDiscount(cb?: (result: any) => void): Promise<{
+        productList: Record<string, any>[];
+        discountList: Discount[];
+    }>;
+    getDiscountList(): Discount[];
+    /** 读取 Discount 模块原始券列表（未经过 bookingTime 等过滤）。 */
+    getOriginalDiscountList(): Discount[];
+    /**
+     * 同步写入 Discount 模块的 discountList / originalDiscountList。
+     * 供 Holder 补全等场景在 OS store 层更新 machinecode holder 字段。
+     */
+    replaceDiscountStoreLists(params: {
+        discountList: Discount[];
+        originalDiscountList?: Discount[];
+    }): Promise<void>;
+    scanPromotionCode(code: string, customerId?: number): Promise<BaseSalesScanCodeResult>;
+    setDiscountSelected(params: {
+        discountId: number;
+        isSelected: boolean;
+    }): Promise<void>;
+    applyDiscountCalculationResult(result?: {
+        productList?: Record<string, any>[];
+        discountList?: Discount[];
+    }): Promise<void>;
+    submitScanOrder<T = any>(params?: {
+        payments?: OrderPaymentSource[];
+        paymentStatus?: BaseSalesPaymentStatus;
+        smallTicketDataFlag?: number;
+        confirmPendingVoucherPayments?: boolean;
+        enhancePayload?: SubmitPayloadEnhancer;
+    }): Promise<T>;
+    /**
+     * 提交当前 Sales 订单。
+     *
+     * PaymentModal 场景通过 smallTicketDataFlag=1 请求 B 端小票数据；
+     * payments 会交给 OrderModule 统一映射为 Sales 协议支付项。
+     */
+    submitSalesOrder<T = any>(params?: {
+        payments?: OrderPaymentSource[];
+        paymentStatus?: BaseSalesPaymentStatus;
+        smallTicketDataFlag?: number;
+        confirmPendingVoucherPayments?: boolean;
+        enhancePayload?: SubmitPayloadEnhancer;
+    }): Promise<T>;
+    submitTempOrderAsync<T = any>(params?: {
+        payments?: OrderPaymentSource[];
+        paymentStatus?: BaseSalesPaymentStatus;
+        smallTicketDataFlag?: number;
+        confirmPendingVoucherPayments?: boolean;
+        enhancePayload?: SubmitPayloadEnhancer;
+    }): Promise<T>;
+    /**
+     * 默认保持 WebPOS 的本地待同步订单模式；需要云端确认后才算成功的渠道可覆盖此策略。
+     * otherParams.checkoutSyncTaskEnabled 优先，便于同一 solution 按入口恢复旧行为。
+     */
+    protected shouldUseCheckoutSyncTask(): boolean;
+    /** 可由特定 solution 为真实 checkout 补充默认收据数据请求。 */
+    protected getDefaultCheckoutSmallTicketDataFlag(): number | undefined;
+    printLocalOrderReceipt<T = any>(lookup?: BaseSalesPrintLocalOrderReceiptParams): Promise<T>;
+    private getSubmitPaymentStatus;
+    syncPaymentsToOrder<T = any>(params: SyncPaymentsToOrderParams): Promise<SyncPaymentsToOrderResult<T>>;
+    /** 读取当前 BaseSales 订单上下文中的 Sales 协议支付项。 */
+    getOrderPayments(): OrderPaymentData[];
+    /** 覆盖当前订单支付项，内部由 OrderModule 清洗为 Sales 协议字段。 */
+    setOrderPayments(payments: OrderPaymentSource[]): OrderPaymentData[];
+    private getPaymentStatusForSync;
+    private queueLatestAutoPaymentSync;
+    private scheduleQueuedAutoPaymentSyncFlush;
+    private flushQueuedAutoPaymentSync;
+    /** 追加单个支付项到当前订单。 */
+    addOrderPayment(payment: OrderPaymentSource): OrderPaymentData[];
+    /** 更新当前订单中的指定支付项。 */
+    updateOrderPayment(paymentIdentity: string | number, updates: Partial<OrderPaymentData> & Record<string, any>): OrderPaymentData[];
+    /** 删除当前订单中的指定支付项。 */
+    deleteOrderPayment(paymentIdentity: string | number): OrderPaymentData[];
+    /** 覆盖 wallet pass 支付项，同时保留普通支付项。 */
+    updateVoucherOrderPayments(payments: OrderPaymentSource[], options?: {
+        status?: 'paid' | 'payment_pending';
+    }): OrderPaymentData[];
+    confirmPendingVoucherPayments(): OrderPaymentData[];
+    discardPendingVoucherPayments(): OrderPaymentData[];
+    private getWalletProductList;
+    initWalletData(params?: {
+        order_wait_pay_amount?: number;
+    }): Promise<import("../../modules/Payment").WalletInitializationResult>;
+    /**
+     * 更新当前订单客户字段。
+     *
+     * 这是 PaymentModal 客户切换的订单事实入口；外部客户模块同步应由
+     * 调用方通过 onCustomerChange 回调完成。
+     */
+    updateOrderCustomer(customer: UpdateTempOrderCustomerInput): {
+        customerId: number | null;
+        customerName: string;
+        phone: string;
+        email: string;
+    };
+    /** 获取可用支付方式列表，供 PaymentModal 渲染支付选项。 */
+    getPaymentMethodsAsync(): Promise<PaymentMethod[]>;
+    /** 同步读取初始化时缓存的支付方式列表。 */
+    getPaymentMethods(): PaymentMethod[];
+    /** 轻量舍入能力，供现金支付 UI 计算 rounding_amount。 */
+    roundAmount(params: {
+        amount: string | number;
+        interval?: string | number;
+        rule?: 'standard_rounding' | 'standard_down' | 'always_up' | 'always_down' | string;
+    }): {
+        originalAmount: string;
+        roundedAmount: string;
+        roundingDifference: string;
+    };
+    /**
+     * 发送支付链接。
+     *
+     * 如果没有 orderIds 或显式 submitBeforeSend，会先提交当前本地订单到云端；
+     * 只有成功拿到远端 order_id 后才调用 OrderModule 发送邮件。
+     */
+    sendCustomerPayLink<T = any>(params: Omit<SendCustomerPayLinkParams, 'orderIds' | 'order_ids'> & {
+        orderIds?: Array<number | string>;
+        order_ids?: Array<number | string>;
+        submitBeforeSend?: boolean;
+    }): Promise<T>;
+    transformBaseProductToOrderProduct(params: TransformBaseProductToOrderProductParams): import("./utils/transformBaseProductToOrderProduct").BaseProductOrderProductInput | null;
+    calculateProductBookingPrice(params: BaseSalesCalculateProductBookingPriceParams): Promise<BaseSalesProductBookingPriceResult>;
+    getQuotationCustomerScopeInfo(): BaseSalesQuotationCustomerScopeInfo;
+    shouldRecalculateProductBookingPricesForContextChange(params: BaseSalesPriceRecalculationContextChange): boolean;
+    calculateProductBookingPrices(paramsList: BaseSalesCalculateProductBookingPriceParams[]): Promise<BaseSalesProductBookingPriceResult[]>;
+    addProductToOrder(product: Partial<BaseSalesOrderProduct> & BaseSalesOrderProductIdentity, booking?: AddProductBookingInput): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    updateOrderProduct(params: UpdateOrderProductParams): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    updateOrderProducts(paramsList: UpdateOrderProductParams[]): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    updateOrderProductQuantity(params: BaseSalesUpdateOrderProductQuantityParams): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    updateOrderBooking(params: UpdateOrderBookingParams): any[];
+    /**
+     * 设置单行商品备注（与整单 `updateTempOrderNote` 区分）。
+     * 多行同 SKU 时必须传入与删除/更新一致的 unique_identification_number。
+     */
+    setOrderProductLineNote(identity: BaseSalesOrderProductIdentity, note: string): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    /**
+     * 批量删除购物车行，末尾仅一次促销重算。
+     *
+     * @example
+     * await baseSales.removeProductsFromOrder([identityA, identityB]);
+     */
+    removeProductsFromOrder(identities: BaseSalesOrderProductIdentity[]): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    removeProductFromOrder(identity: BaseSalesOrderProductIdentity): Promise<import("../../modules/Order/types").OrderProduct[]>;
+    /**
+     * 注入促销评估器到底层 OrderModule。
+     *
+     * @example
+     * solution.setPromotionEvaluator(appHelper.utils.promotionEvaluator);
+     */
+    setPromotionEvaluator(evaluator: OrderPromotionEvaluator | null): void;
+    /**
+     * 注入赠品选择 resolver。UI 层（SalesSdk）通过 bridge 提供。
+     *
+     * @example
+     * solution.setGiftSelectResolver(async (ctx) => bridge.request(ctx));
+     */
+    setGiftSelectResolver(resolver: OrderGiftSelectResolver | null): void;
+    /**
+     * 为商品目录追加促销标签，供 SalesSdkProductProvider 等商品列表入口复用。
+     *
+     * @example
+     * const products = solution.appendPromotionTags(catalogProducts);
+     */
+    appendPromotionTags<T extends Record<string, any>>(products: T[]): T[];
+    /**
+     * 主动触发一次促销应用（一般写路径会自动触发，少数场景如客户切换后可手动调）。
+     */
+    applyPromotion(): Promise<void>;
+    /** 最近一次促销计算输出的未满足提示。 */
+    getUnfulfilledPromotions(): OrderUnfulfilledPromotion[];
+    /** 最近一次促销计算输出的赠品操作 diff。 */
+    getLastGiftActions(): OrderLastGiftActions | null;
+    getProductList(): Promise<any>;
+    getOtherParams(): Record<string, any>;
+    setOtherParams(params: Record<string, any>, { cover }?: {
+        cover?: boolean;
+    }): Promise<void>;
+}