@pisell/pisellos 0.0.229 → 0.0.231

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

@@ -0,0 +1,737 @@
+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 CheckoutStatus {
+    /** 初始化中 */
+    Initializing = "initializing",
+    /** 准备就绪 */
+    Ready = "ready",
+    /** 创建订单中 */
+    CreatingOrder = "creating_order",
+    /** 订单已创建 */
+    OrderCreated = "order_created",
+    /** 处理支付中 */
+    ProcessingPayment = "processing_payment",
+    /** 支付完成 */
+    PaymentCompleted = "payment_completed",
+    /** 结账完成 */
+    Completed = "completed",
+    /** 已取消 */
+    Cancelled = "cancelled",
+    /** 错误状态 */
+    Error = "error"
+}
+/**
+ * 结账步骤枚举
+ */
+export declare enum CheckoutStep {
+    /** 订单确认 */
+    OrderConfirmation = "order_confirmation",
+    /** 支付方式选择 */
+    PaymentMethod = "payment_method",
+    /** 支付处理 */
+    PaymentProcessing = "payment_processing",
+    /** 完成 */
+    Complete = "complete"
+}
+/**
+ * 结账错误类型
+ */
+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 PlaceOrderParams {
+    /** 订单提交的 URL (可选，默认使用 /order/appointment) */
+    url?: string;
+    /** 是否自动替换虚拟订单ID为真实订单ID */
+    autoReplaceOrderId?: boolean;
+}
+/**
+ * 本地订单数据结构 (基于 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;
+    /** 商店折扣金额 */
+    shop_discount?: 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 interface CreateOrderParams {
+    /** 购物车商品 */
+    cartItems: CartItem[];
+    /** 订单类型 */
+    type?: 'virtual' | 'appointment_booking';
+    /** 平台类型 */
+    platform?: 'pc' | 'h5';
+    /** 额外参数 */
+    extra?: Record<string, any>;
+}
+/**
+ * 支付处理参数
+ */
+export interface ProcessPaymentParams {
+    /** 订单UUID */
+    orderUuid: string;
+    /** 支付方式代码 */
+    paymentMethodCode: string;
+    /** 支付金额 */
+    amount: string | number;
+    /** 支付元数据 */
+    metadata?: Record<string, any>;
+}
+/**
+ * 结账状态信息
+ */
+export interface CheckoutStatusInfo {
+    /** 当前状态 */
+    status: CheckoutStatus;
+    /** 当前步骤 */
+    step: CheckoutStep;
+    /** 进度百分比 (0-100) */
+    progress: number;
+    /** 状态消息 */
+    message?: string;
+    /** 错误信息 */
+    error?: CheckoutError;
+}
+/**
+ * 结账摘要信息
+ */
+export interface CheckoutSummary {
+    /** 订单信息 */
+    order?: PaymentOrder;
+    /** 总金额 */
+    totalAmount: string;
+    /** 已支付金额 */
+    paidAmount: string;
+    /** 待支付金额 */
+    remainingAmount: string;
+    /** 支付状态 */
+    paymentStatus: PaymentStatus;
+    /** 可用支付方式 */
+    availablePaymentMethods: PaymentMethod[];
+}
+/**
+ * 结账事件钩子
+ */
+export declare enum CheckoutHooks {
+    /** 结账初始化完成 */
+    OnCheckoutInitialized = "checkout:onInitialized",
+    /** 状态变更 */
+    OnStatusChanged = "checkout:onStatusChanged",
+    /** 步骤变更 */
+    OnStepChanged = "checkout:onStepChanged",
+    /** 订单创建成功 */
+    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",
+    /** 订单支付完成（待付款金额 ≤ 0） */
+    OnOrderPaymentCompleted = "checkout:onOrderPaymentCompleted",
+    /** 订单同步到后端完成 */
+    OnOrderSynced = "checkout:onOrderSynced",
+    /** 订单备注变更 */
+    OnOrderNoteChanged = "checkout:onOrderNoteChanged",
+    /** 商店折扣变更 */
+    OnShopDiscountChanged = "checkout:onShopDiscountChanged"
+}
+/**
+ * 结账状态数据
+ */
+export interface CheckoutState {
+    /** 当前状态 */
+    status: CheckoutStatus;
+    /** 当前步骤 */
+    step: CheckoutStep;
+    /** 当前订单 */
+    currentOrder?: PaymentOrder;
+    /** 购物车商品 */
+    cartItems: CartItem[];
+    /** 本地订单数据 */
+    localOrderData?: LocalOrderData;
+    /** 购物车小计数据 */
+    cartSummary?: CartSummaryItem[];
+    /** 可用支付方式 */
+    paymentMethods: PaymentMethod[];
+    /** 错误信息 */
+    lastError?: CheckoutError;
+    /** UI 自定义支付金额 */
+    stateAmount: string;
+    /** 订单是否已同步到后端 */
+    isOrderSynced: boolean;
+    /** 当前客户信息 */
+    currentCustomer?: {
+        customer_id?: string;
+        customer_name?: string;
+    };
+}
+/**
+ * 当前订单基础信息
+ */
+export interface CurrentOrderInfo {
+    /** 订单UUID */
+    uuid?: string;
+    /** 订单ID */
+    orderId?: string;
+    /** 订单状态 */
+    status?: CheckoutStatus;
+    /** 当前步骤 */
+    step?: CheckoutStep;
+    /** 订单总金额 */
+    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>;
+    /**
+     * 手动下单 (根据虚拟订单生成实际订单)
+     */
+    placeOrderAsync(params?: PlaceOrderParams): Promise<{
+        success: boolean;
+        orderId?: string;
+        error?: string;
+    }>;
+    /**
+     * 创建订单
+     */
+    createOrderAsync(params: CreateOrderParams): Promise<PaymentOrder>;
+    /**
+     * 处理支付
+     */
+    processPaymentAsync(params: ProcessPaymentParams): Promise<void>;
+    /**
+     * 完成结账
+     */
+    completeCheckoutAsync(): Promise<{
+        success: boolean;
+        orderId?: string;
+    }>;
+    /**
+     * 取消结账
+     */
+    cancelCheckoutAsync(): Promise<void>;
+    /**
+     * 获取结账状态
+     */
+    getCheckoutStatus(): CheckoutStatusInfo;
+    /**
+     * 获取结账摘要
+     */
+    getCheckoutSummaryAsync(): Promise<CheckoutSummary>;
+    /**
+     * 获取可用支付方式
+     */
+    getAvailablePaymentMethodsAsync(): Promise<PaymentMethod[]>;
+    /**
+     * 刷新支付方式缓存
+     */
+    refreshPaymentMethodsAsync(): Promise<PaymentMethod[]>;
+    /**
+     * 获取当前订单基础信息
+     */
+    getCurrentOrderInfo(): CurrentOrderInfo | null;
+    /**
+     * 获取当前订单的支付项
+     */
+    getCurrentOrderPaymentItemsAsync(): Promise<PaymentItem[]>;
+    /**
+     * 验证结账前置条件
+     */
+    validateCheckoutAsync(): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+    /**
+     * 重试失败的操作
+     */
+    retryFailedOperationAsync(): Promise<void>;
+    /**
+     * 设置当前步骤
+     */
+    setCurrentStep(step: CheckoutStep): void;
+    /**
+     * 获取订单模块
+     */
+    getOrderModule(): OrderModule;
+    /**
+     * 获取支付模块
+     */
+    getPaymentModule(): PaymentModuleAPI;
+    /**
+     * 替换本地订单ID为真实订单ID
+     */
+    replaceLocalOrderIdAsync(newOrderId: string): Promise<PaymentOrder | null>;
+    /**
+     * 设置自定义支付金额
+     */
+    setStateAmountAsync(amount: string): Promise<void>;
+    /**
+     * 获取当前自定义支付金额
+     */
+    getStateAmount(): string;
+    /**
+     * 刷新 stateAmount 为当前剩余未支付金额
+     */
+    refreshStateAmountAsync(): Promise<void>;
+    /**
+     * 获取购物车小计数据
+     */
+    getCartSummary(): CartSummaryItem[] | null;
+    /**
+     * 获取提取的金额详细信息
+     */
+    getExtractedAmountInfo(): ExtractedAmountInfo | 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>;
+    /**
+     * 更新当前订单的客户信息
+     */
+    updateOrderCustomerAsync(customer: {
+        customer_id?: string;
+        customer_name?: string;
+    }): Promise<void>;
+    /**
+     * 获取当前订单的客户信息
+     */
+    getCurrentCustomer(): {
+        customer_id?: string;
+        customer_name?: string;
+    } | null;
+    /**
+     * 手动同步订单到后端
+     *
+     * 用于强制同步订单到后端，特别适用于纯代金券支付完成的订单
+     */
+    manualSyncOrderAsync(): Promise<{
+        success: boolean;
+        message?: string;
+        orderId?: string;
+        orderUuid?: string;
+    }>;
+    /**
+     * 检查订单是否需要手动同步
+     *
+     * 返回订单是否为纯代金券支付且待付金额<=0但未同步的状态
+     */
+    needsManualSync(): boolean;
+    /**
+     * 更新订单备注
+     *
+     * @param note 订单备注内容
+     */
+    updateOrderNoteAsync(note: string): Promise<void>;
+    /**
+     * 获取当前订单备注
+     *
+     * @returns 当前订单的备注内容，如果没有则返回空字符串
+     */
+    getOrderNote(): string;
+    /**
+     * 获取当前订单ID
+     *
+     * @returns 当前订单的ID，如果没有订单则返回null
+     */
+    getCurrentOrderId(): string | null;
+    /**
+     * 更新订单商店折扣
+     *
+     * 同时更新cartSummary和localOrderData中的shop_discount值
+     *
+     * @param discountAmount 商店折扣金额
+     */
+    updateShopDiscountAsync(discountAmount: number): Promise<void>;
+    /**
+     * 获取当前商店折扣金额
+     *
+     * @returns 当前的商店折扣金额，如果没有则返回0
+     */
+    getShopDiscount(): number;
+    /**
+     * 保存订单并稍后支付
+     *
+     * 将当前订单保存到后端，但排除代金券类支付项(voucher_id)，
+     * 适用于用户想要保存订单但稍后完成支付的场景
+     *
+     * @returns 保存结果，包含订单ID和状态
+     */
+    saveForLaterPaymentAsync(): Promise<{
+        success: boolean;
+        message?: string;
+        orderId?: string;
+        orderUuid?: string;
+    }>;
+}
+/**
+ * 结账事件数据类型
+ */
+export interface CheckoutEventData {
+    /** 状态变更事件 */
+    statusChanged: {
+        oldStatus: CheckoutStatus;
+        newStatus: CheckoutStatus;
+        timestamp: number;
+    };
+    /** 步骤变更事件 */
+    stepChanged: {
+        oldStep: CheckoutStep;
+        newStep: CheckoutStep;
+        timestamp: number;
+    };
+    /** 订单创建事件 */
+    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;
+    };
+    /** 订单支付完成事件 */
+    orderPaymentCompleted: {
+        orderUuid: string;
+        orderId: string;
+        totalAmount: string;
+        paidAmount: string;
+        remainingAmount: string;
+        timestamp: number;
+    };
+    /** 订单同步到后端完成事件 */
+    orderSynced: {
+        orderUuid: string;
+        realOrderId: string;
+        virtualOrderId: string;
+        timestamp: number;
+        /** 是否为手动同步 */
+        isManual?: boolean;
+    };
+    /** 订单备注变更事件 */
+    orderNoteChanged: {
+        orderUuid?: string;
+        oldNote: string;
+        newNote: string;
+        timestamp: number;
+    };
+    /** 商店折扣变更事件 */
+    shopDiscountChanged: {
+        orderUuid?: string;
+        oldDiscount: number;
+        newDiscount: number;
+        timestamp: number;
+    };
+}