@pisell/pisellos

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; /** 云端已存在的支付项（可选，用于处理订单在其他设备或云端生成的场景） */ existPayment?: PaymentItem[]; } /** * 本地订单数据结构 (基于 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, orderUuid?: string): 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; }; }