@pisell/pisellos 3.0.75 → 3.0.76

package/dist/solution/Checkout/types.d.ts

@@ -0,0 +1,727 @@
+import { Module } from '../../types';
+import { OrderModule } from '../../modules/Order';
+import { PaymentModuleAPI, PaymentOrder, PaymentMethod, PaymentStatus, PaymentItem, PaymentItemInput } from '../../modules/Payment';
+import { CartItem } from '../../modules/Cart/types';
+/**
+ * 结账错误类型
+ */
+export declare enum CheckoutErrorType {
+    /** 订单创建失败 */
+    OrderCreationFailed = "order_creation_failed",
+    /** 支付失败 */
+    PaymentFailed = "payment_failed",
+    /** 验证失败 */
+    ValidationFailed = "validation_failed",
+    /** 网络错误 */
+    NetworkError = "network_error",
+    /** 未知错误 */
+    UnknownError = "unknown_error"
+}
+/**
+ * 结账错误信息
+ */
+export interface CheckoutError {
+    /** 错误类型 */
+    type: CheckoutErrorType;
+    /** 错误消息 */
+    message: string;
+    /** 错误详情 */
+    details?: any;
+    /** 错误时间戳 */
+    timestamp: number;
+}
+/**
+ * 结账初始化参数
+ */
+export interface CheckoutInitParams {
+    /** 购物车商品 */
+    cartItems: CartItem[];
+    /** 订单类型 */
+    orderType?: 'virtual' | 'appointment_booking';
+    /** 平台类型 */
+    platform?: 'pc' | 'h5';
+    /** 自动进入支付 */
+    autoPayment?: boolean;
+}
+/**
+ * 购物车小计项
+ */
+export interface CartSummaryItem {
+    /** 项目键名 */
+    key: string;
+    /** 项目值 */
+    value: number;
+    /** 是否隐藏显示 */
+    hidden?: boolean;
+    /** 显示标签 */
+    label?: string;
+    /** 税费详情 (当 key 为 tax 时) */
+    tax?: Record<string, any>;
+}
+/**
+ * 从购物车小计提取的金额信息
+ */
+export interface ExtractedAmountInfo {
+    /** 总金额 (expect_amount) */
+    totalAmount: string;
+    /** 小计 (sub_total) */
+    subTotal: string;
+    /** 税费 (tax) */
+    taxAmount: string;
+    /** 折扣 (discount) */
+    discountAmount: string;
+    /** 商店折扣 (shop_discount) */
+    shopDiscountAmount: string;
+    /** 四舍五入金额 (custom_roundingAmount) */
+    roundingAmount: string;
+    /** 定金金额 (如果是定金订单) */
+    depositAmount?: string;
+    /** 税费详情 */
+    taxDetails?: Record<string, any>;
+}
+/**
+ * 本地订单创建参数
+ */
+export interface CreateLocalOrderParams {
+    /** 订单数据 (来自购物车的完整订单参数) */
+    orderData: LocalOrderData;
+    /** 购物车小计数据 */
+    cartSummary: CartSummaryItem[];
+    /** 是否自动进入支付流程 */
+    autoPayment?: boolean;
+    totalInfo: any;
+}
+/**
+ * 本地订单更新参数
+ */
+export interface UpdateLocalOrderParams {
+    /** 要更新的后端订单ID（已同步过后端的订单） */
+    orderId: string;
+    /** 更新后的订单数据（结构与创建时一致，允许部分字段变化） */
+    orderData: LocalOrderData;
+    /** 更新后的购物车小计数据 */
+    cartSummary: CartSummaryItem[];
+    /** total 信息（用于拆解金额） */
+    totalInfo: any;
+}
+/**
+ * 本地订单数据结构 (基于 appointmentDemo.json)
+ */
+export interface LocalOrderData {
+    /** 订单类型 */
+    type: 'appointment_booking' | 'virtual';
+    /** 平台 */
+    platform: 'PC' | 'H5';
+    /** 销售渠道 */
+    sales_channel: string;
+    /** 订单销售渠道 */
+    order_sales_channel: string;
+    /** 预订信息 */
+    bookings: LocalBookingItem[];
+    /** 商店备注 */
+    shop_note: string;
+    /** 预约日期 */
+    schedule_date: string;
+    /** 是否定金 */
+    is_deposit: number;
+    /** 关联商品 */
+    relation_products: any[];
+    /** 关联表单 */
+    relation_forms: any[];
+    /** 客户ID */
+    customer_id?: string;
+    /** 客户姓名 */
+    customer_name?: string;
+    /** 创建时间 (YYYY-MM-DD hh:mm:ss) */
+    created_at?: string;
+    /** 附加费用 */
+    surcharge_fee?: number;
+    /** 附加费列表 */
+    surcharges?: any[];
+    /** 商店折扣金额 */
+    shop_discount?: number;
+    /** 税费金额 */
+    tax_fee?: number;
+}
+/**
+ * 本地预订项
+ */
+export interface LocalBookingItem {
+    /** ID */
+    id: number;
+    /** 数量 */
+    number: number;
+    /** 注册类型 */
+    registration_type: string;
+    /** 关联商品 */
+    relation_products: any[];
+    /** 是否全部 */
+    is_all: boolean;
+    /** 商品信息 */
+    product: LocalProductInfo;
+    /** 子类型 */
+    sub_type: string;
+    /** 时长 */
+    duration: number;
+    /** 喜好状态 */
+    like_status: string;
+    /** 资源列表 */
+    resources: LocalResourceItem[];
+    /** 预约ID */
+    schedule_id: number;
+    /** 开始日期 */
+    start_date: string;
+    /** 开始时间 */
+    start_time: string;
+    /** 选择日期 */
+    select_date: string;
+    /** 结束时间 */
+    end_time: string;
+    /** 结束日期 */
+    end_date: string;
+    /** 元数据 */
+    metadata: {
+        account?: {
+            id: number;
+            username: string;
+        };
+        capacity?: Array<{
+            id: number;
+            value: number;
+            name: string;
+        }>;
+    };
+    /** 持有者 */
+    holder: any;
+    /** 关联表单 */
+    relation_forms: any[];
+}
+/**
+ * 本地商品信息
+ */
+export interface LocalProductInfo {
+    /** 数量 */
+    num: number;
+    /** 商品ID */
+    product_id: number;
+    /** 商品变体ID */
+    product_variant_id: number;
+    /** 商品套装 */
+    product_bundle: any[];
+    /** 商品选项 */
+    product_option_item: any[];
+    /** 折扣列表 */
+    discount_list: LocalDiscountItem[];
+}
+/**
+ * 本地折扣项
+ */
+export interface LocalDiscountItem {
+    /** 金额 */
+    amount: number;
+    /** 类型 */
+    type: string;
+    /** 折扣详情 */
+    discount: {
+        resource_id: number;
+        title: {
+            auto: string;
+            original: string;
+            en?: string;
+            'zh-CN'?: string;
+            'zh-HK'?: string;
+        };
+        original_amount: number;
+        product_id: number;
+        percent: string;
+    };
+}
+/**
+ * 本地资源项
+ */
+export interface LocalResourceItem {
+    /** 关联类型 */
+    relation_type: string;
+    /** 喜好状态 */
+    like_status: string;
+    /** 表单ID */
+    form_id: number;
+    /** 关联ID */
+    relation_id: number;
+    /** 容量 */
+    capacity: number;
+    /** 元数据 */
+    metadata: {
+        combined_resource?: {
+            status: number;
+            resource_ids: number[];
+        } | null;
+        form_name: string;
+        resource_name: string;
+    };
+    /** 子资源 */
+    children?: LocalResourceItem[];
+    /** ID (可选) */
+    id?: number;
+    /** 主字段 (可选) */
+    main_field?: string;
+    /** 资源类型 (可选) */
+    resourceType?: string;
+}
+/**
+ * 结账事件钩子
+ */
+export declare enum CheckoutHooks {
+    /** 结账初始化完成 */
+    OnCheckoutInitialized = "checkout:onInitialized",
+    /** 订单创建成功 */
+    OnOrderCreated = "checkout:onOrderCreated",
+    /** 订单创建失败 */
+    OnOrderCreationFailed = "checkout:onOrderCreationFailed",
+    /** 支付开始 */
+    OnPaymentStarted = "checkout:onPaymentStarted",
+    /** 支付成功 */
+    OnPaymentSuccess = "checkout:onPaymentSuccess",
+    /** 支付失败 */
+    OnPaymentFailed = "checkout:onPaymentFailed",
+    /** 结账完成 */
+    OnCheckoutCompleted = "checkout:onCompleted",
+    /** 结账取消 */
+    OnCheckoutCancelled = "checkout:onCancelled",
+    /** 错误发生 */
+    OnError = "checkout:onError",
+    /** 自定义支付金额变更 */
+    OnStateAmountChanged = "checkout:onStateAmountChanged",
+    /** 系统计算的待付金额变更 */
+    OnBalanceDueAmountChanged = "checkout:onBalanceDueAmountChanged",
+    /** 订单支付完成（待付款金额 ≤ 0） */
+    OnOrderPaymentCompleted = "checkout:onOrderPaymentCompleted",
+    /** 订单同步到后端完成 */
+    OnOrderSynced = "checkout:onOrderSynced",
+    /** 订单同步到后端失败 */
+    OnOrderSyncFailed = "checkout:onOrderSyncFailed",
+    /** 订单备注变更 */
+    OnOrderNoteChanged = "checkout:onOrderNoteChanged",
+    /** 商店折扣变更 */
+    OnShopDiscountChanged = "checkout:onShopDiscountChanged",
+    /** 订单取消 */
+    OnOrderCancelled = "checkout:onOrderCancelled",
+    /** 订单状态已清理 */
+    OnOrderCleared = "checkout:onOrderCleared",
+    /** 下单接口请求开始 */
+    OnOrderSubmitStart = "checkout:onOrderSubmitStart",
+    /** 下单接口请求完成 */
+    OnOrderSubmitEnd = "checkout:onOrderSubmitEnd",
+    /** 钱包数据初始化完成 */
+    OnWalletDataInitialized = "checkout:onWalletDataInitialized",
+    /** 支付项添加成功 */
+    OnPaymentItemAdded = "checkout:onPaymentItemAdded"
+}
+/**
+ * 结账状态数据
+ */
+export interface CheckoutState {
+    /** 当前订单 */
+    currentOrder?: PaymentOrder;
+    /** 购物车商品 */
+    cartItems: CartItem[];
+    /** 本地订单数据 */
+    localOrderData?: LocalOrderData;
+    /** 购物车小计数据 */
+    cartSummary?: CartSummaryItem[];
+    /** 可用支付方式 */
+    paymentMethods: PaymentMethod[];
+    /** 错误信息 */
+    lastError?: CheckoutError;
+    /** UI 自定义支付金额 */
+    stateAmount: string;
+    /** 系统计算的待付金额（只读，由系统内部计算） */
+    balanceDueAmount: string;
+    /** 订单是否已同步到后端 */
+    isOrderSynced: boolean;
+    /** 当前客户信息 */
+    currentCustomer?: {
+        customer_id?: string;
+        customer_name?: string;
+    };
+}
+/**
+ * 当前订单基础信息
+ */
+export interface CurrentOrderInfo {
+    /** 订单UUID */
+    uuid?: string;
+    /** 订单ID */
+    orderId?: string;
+    /** 订单总金额 */
+    totalAmount?: string;
+    /** 待付金额 */
+    remainingAmount?: string;
+    /** 支付状态 */
+    paymentStatus?: PaymentStatus;
+    /** 是否为定金订单 */
+    isDeposit?: boolean;
+    /** 定金金额 */
+    depositAmount?: string;
+    /** 订单类型 */
+    orderType?: 'virtual' | 'appointment_booking';
+    /** 平台类型 */
+    platform?: 'pc' | 'h5';
+    /** 创建时间 */
+    createdAt?: string;
+    /** 商品数量 */
+    itemCount?: number;
+    /** 是否有本地订单数据 */
+    hasLocalOrderData?: boolean;
+}
+/**
+ * 结账解决方案 API 接口
+ */
+export interface CheckoutModuleAPI extends Module {
+    /**
+     * 初始化结账流程
+     */
+    initializeCheckoutAsync(params: CheckoutInitParams): Promise<void>;
+    /**
+     * 创建本地订单 (前端模拟下单流程)
+     */
+    createLocalOrderAsync(params: CreateLocalOrderParams): Promise<PaymentOrder>;
+    /**
+     * 更新本地订单（基于已同步后的真实 orderId）并设置为当前订单
+     */
+    updateLocalOrderAsync(params: UpdateLocalOrderParams): Promise<PaymentOrder>;
+    /**
+     * 完成结账
+     */
+    completeCheckoutAsync(): Promise<{
+        success: boolean;
+        orderId?: string;
+    }>;
+    /**
+     * 获取当前订单基础信息
+     */
+    getCurrentOrderInfo(): CurrentOrderInfo | null;
+    /**
+     * 获取当前订单的支付项
+     */
+    getCurrentOrderPaymentItemsAsync(): Promise<PaymentItem[]>;
+    /**
+     * 获取订单模块
+     */
+    getOrderModule(): OrderModule;
+    /**
+     * 获取支付模块
+     */
+    getPaymentModule(): PaymentModuleAPI;
+    /**
+     * 替换本地订单ID为真实订单ID
+     */
+    replaceLocalOrderIdAsync(newOrderId: string): Promise<PaymentOrder | null>;
+    /**
+     * 设置自定义支付金额
+     */
+    setStateAmountAsync(amount: string): Promise<void>;
+    /**
+     * 获取当前自定义支付金额
+     */
+    getStateAmount(): string;
+    /**
+     * 获取系统计算的待付金额（只读）
+     *
+     * @returns 当前系统计算的待付金额
+     */
+    getBalanceDueAmount(): string;
+    /**
+     * 获取购物车小计数据
+     */
+    getCartSummary(): CartSummaryItem[] | null;
+    /**
+     * 获取支付方式列表（直接调用 Payment 模块）
+     */
+    getPaymentMethodsAsync(): Promise<PaymentMethod[]>;
+    /**
+     * 为当前订单添加支付项
+     */
+    addPaymentItemAsync(paymentItem: PaymentItemInput): Promise<void>;
+    /**
+     * 删除当前订单的支付项
+     */
+    deletePaymentItemAsync(paymentUuid: string): Promise<void>;
+    /**
+     * 批量更新当前订单的代金券支付项（覆盖更新）
+     */
+    updateVoucherPaymentItemsAsync(voucherPaymentItems: PaymentItemInput[]): Promise<void>;
+    /**
+     * 修改当前订单的定金状态
+     */
+    updateOrderDepositStatusAsync(isDeposit: number): Promise<void>;
+    /**
+     * 手动设置当前订单的定金金额
+     *
+     * @param depositAmount 定金金额，必须是有效的数字字符串，且不能超过订单总额
+     */
+    setDepositAmountAsync(depositAmount: string): Promise<void>;
+    /**
+     * 手动同步订单到后端
+     *
+     * 用于强制同步订单到后端，特别适用于纯代金券支付完成的订单
+     */
+    manualSyncOrderAsync(): Promise<{
+        success: boolean;
+        message?: string;
+        orderId?: string;
+        orderUuid?: string;
+        response?: any;
+    }>;
+    /**
+     * 更新订单备注
+     *
+     * @param note 订单备注内容
+     */
+    updateOrderNoteAsync(note: string): Promise<void>;
+    /**
+     * 获取当前订单备注
+     *
+     * @returns 当前订单的备注内容，如果没有则返回空字符串
+     */
+    getOrderNote(): string;
+    /**
+     * 获取当前订单ID
+     *
+     * @returns 当前订单的ID，如果没有订单则返回null
+     */
+    getCurrentOrderId(): string | null;
+    /**
+     * 获取当前订单是否已同步到后端
+     *
+     * @returns 当前订单是否已同步状态，如果没有订单则返回false
+     */
+    isCurrentOrderSynced(): boolean;
+    /**
+     * 取消当前本地订单
+     *
+     * 只能取消未同步到后端的本地订单，如果订单已同步则不能取消
+     *
+     * @param cancelReason 取消原因（可选）
+     * @returns 取消结果
+     */
+    cancelCurrentOrderAsync(cancelReason?: string): Promise<{
+        success: boolean;
+        message?: string;
+        orderId?: string;
+    }>;
+    /**
+     * 保存订单并稍后支付
+     *
+     * 将当前订单保存到后端，但排除代金券类支付项(voucher_id)，
+     * 适用于用户想要保存订单但稍后完成支付的场景
+     *
+     * @returns 保存结果，包含订单ID和状态
+     */
+    saveForLaterPaymentAsync(): Promise<{
+        success: boolean;
+        message?: string;
+        orderId?: string;
+        orderUuid?: string;
+        response?: any;
+    }>;
+    /**
+     * 通过订单ID编辑订单备注
+     *
+     * 用于修改已同步到后端的订单备注，通常在支付成功后的弹窗中使用
+     *
+     * @param orderId 后端订单ID
+     * @param note 新的订单备注
+     * @returns 修改结果
+     */
+    editOrderNoteByOrderIdAsync(orderId: string | number, note: string): Promise<{
+        success: boolean;
+        message?: string;
+        orderId?: string | number;
+    }>;
+    /**
+     * 发送客户支付链接邮件
+     *
+     * 向指定邮箱发送订单支付提醒邮件
+     *
+     * @param params 发送参数
+     * @returns 发送结果
+     */
+    sendCustomerPayLinkAsync(params: SendCustomerPayLinkParams): Promise<{
+        success: boolean;
+        message?: string;
+    }>;
+    /**
+     * 金额舍入
+     *
+     * 根据系统配置的舍入设置对金额进行舍入处理
+     *
+     * @param amount 原始金额
+     * @returns 舍入结果详情，包含原始金额、舍入后金额和舍入差额
+     */
+    roundAmountAsync(amount: number): Promise<{
+        originalAmount: string;
+        roundedAmount: string;
+        roundingDifference: string;
+    }>;
+}
+/**
+ * 发送客户支付链接参数
+ */
+export interface SendCustomerPayLinkParams {
+    /** 订单ID列表 */
+    order_ids: string[];
+    /** 通知动作，固定为订单支付提醒 */
+    notify_action?: string;
+    /** 邮箱地址列表 */
+    emails: string[];
+}
+/**
+ * 结账事件数据类型
+ */
+export interface CheckoutEventData {
+    /** 订单创建事件 */
+    orderCreated: {
+        order: PaymentOrder;
+        timestamp: number;
+    };
+    /** 支付事件 */
+    paymentEvent: {
+        orderUuid: string;
+        paymentMethodCode: string;
+        amount: string;
+        timestamp: number;
+    };
+    /** 错误事件 */
+    error: {
+        error: CheckoutError;
+        context?: any;
+        timestamp: number;
+    };
+    /** 自定义支付金额变更事件 */
+    stateAmountChanged: {
+        oldAmount: string;
+        newAmount: string;
+        timestamp: number;
+    };
+    /** 系统计算的待付金额变更事件 */
+    balanceDueAmountChanged: {
+        oldAmount: string;
+        newAmount: string;
+        timestamp: number;
+    };
+    /** 订单支付完成事件 */
+    orderPaymentCompleted: {
+        orderUuid: string;
+        orderId: string;
+        totalAmount: string;
+        paidAmount: string;
+        remainingAmount: string;
+        timestamp: number;
+    };
+    /** 订单同步到后端完成事件 */
+    orderSynced: {
+        orderUuid: string;
+        realOrderId: string;
+        virtualOrderId: string;
+        timestamp: number;
+        /** 是否为手动同步 */
+        isManual?: boolean;
+        /** 后端响应数据 */
+        response?: any;
+    };
+    /** 订单同步到后端失败事件 */
+    orderSyncFailed: {
+        orderUuid: string;
+        /** 操作类型 */
+        operation: 'create' | 'update';
+        /** 是否为手动同步 */
+        isManual: boolean;
+        /** 错误信息 */
+        error: string;
+        /** 错误类型 */
+        errorType: 'network_error' | 'api_error' | 'response_invalid' | 'unknown';
+        /** 后端响应数据（如果有） */
+        response?: any;
+        /** 耗时（毫秒） */
+        duration?: number;
+        timestamp: number;
+    };
+    /** 订单备注变更事件 */
+    orderNoteChanged: {
+        orderUuid?: string;
+        oldNote: string;
+        newNote: string;
+        timestamp: number;
+    };
+    /** 商店折扣变更事件 */
+    shopDiscountChanged: {
+        orderUuid?: string;
+        oldDiscount: number;
+        newDiscount: number;
+        timestamp: number;
+    };
+    /** 订单取消事件 */
+    orderCancelled: {
+        orderUuid?: string;
+        orderId?: string;
+        cancelReason?: string;
+        wasSynced: boolean;
+        timestamp: number;
+    };
+    /** 订单状态清理事件 */
+    orderCleared: {
+        previousOrder?: {
+            uuid: string;
+            orderId: string;
+        } | null;
+        timestamp: number;
+    };
+    /** 下单接口请求开始事件 */
+    orderSubmitStart: {
+        /** 订单UUID */
+        orderUuid: string;
+        /** 操作类型 */
+        operation: 'create' | 'update';
+        /** 是否手动同步 */
+        isManual: boolean;
+        /** 支付项数量 */
+        paymentItemCount: number;
+        timestamp: number;
+    };
+    /** 下单接口请求完成事件 */
+    orderSubmitEnd: {
+        /** 是否成功 */
+        success: boolean;
+        /** 订单UUID */
+        orderUuid: string;
+        /** 操作类型 */
+        operation: 'create' | 'update';
+        /** 是否手动同步 */
+        isManual: boolean;
+        /** 返回的订单ID（成功时） */
+        orderId?: string;
+        /** 错误信息（失败时） */
+        error?: string;
+        /** 耗时（毫秒） */
+        duration?: number;
+        timestamp: number;
+    };
+    /** 钱包数据初始化完成事件 */
+    walletDataInitialized: {
+        /** 订单UUID */
+        orderUuid?: string;
+        /** 客户ID */
+        customerId?: number;
+        /** 钱包业务数据 */
+        walletBusinessData: {
+            customer_id?: number;
+            amountInfo: {
+                totalAmount: string;
+                subTotal: string;
+            };
+            order_wait_pay_amount?: number;
+        };
+        timestamp: number;
+    };
+}