@pisell/pisellos
Version:
一个可扩展的前端模块化SDK框架，支持插件系统
437 lines (436 loc) • 14.7 kB
TypeScript
import { Module, PisellCore, ModuleOptions } from '../../types';
import { BaseModule } from '../../modules/BaseModule';
import { OrderModule } from '../../modules/Order';
import { PaymentModule } from '../../modules/Payment';
import { CheckoutModuleAPI, CheckoutInitParams, CreateLocalOrderParams, UpdateLocalOrderParams, CurrentOrderInfo, CartSummaryItem, SendCustomerPayLinkParams } from './types';
import { PaymentOrder, PaymentMethod, PaymentItem, PaymentItemInput } from '../../modules/Payment/types';
export * from './types';
/**
* 结账解决方案实现
*
* 整合订单处理和支付功能，提供完整的结账流程管理。
* 支持多种支付方式，提供实时状态跟踪和错误处理。
*/
export declare class CheckoutImpl extends BaseModule implements Module, CheckoutModuleAPI {
protected defaultName: string;
protected defaultVersion: string;
isSolution: boolean;
private request;
private store;
private otherParams;
private logger;
private calculationCache;
private syncOrderToBackendInFlightByOrderKey;
order: OrderModule;
payment: PaymentModule;
constructor(name?: string, version?: string);
initialize(core: PisellCore, options: ModuleOptions): Promise<void>;
/**
* 记录信息日志
*/
private logInfo;
/**
* 记录警告日志
*/
private logWarning;
/**
* 记录错误日志
*/
private logError;
/**
* 初始化子模块
*/
private initializeSubModules;
/**
* 设置支付模块事件监听
*/
private setupPaymentEventListeners;
/**
* 初始化结账流程
*/
initializeCheckoutAsync(params: CheckoutInitParams): Promise<void>;
getHolderIdFromBooking(obj: any): number | undefined;
getProductListByOrder(): {
product_id: number;
product_variant_id: string;
quantity: number;
selling_price: number;
holder_id?: number;
}[];
initWalletData(params?: {
order_wait_pay_amount: number;
}): Promise<void>;
checkIsNeedDepositAsync(bookings: any[], relationProducts: any[]): {
total: number;
protocols: {
id: number;
title: string;
}[];
hasDeposit: boolean;
};
/**
* 创建本地订单 (前端模拟下单流程)
*
* 此方法用于在前端模拟整个下单流程，创建一个本地的虚拟订单。
* 用户在购物车点击下单时，会把购物车参数传递给此方法，
* 方法会记录参数并创建本地虚拟订单，然后用 Payment 模块管理支付流程。
*/
createLocalOrderAsync(params: CreateLocalOrderParams): Promise<PaymentOrder>;
/**
* 更新本地订单（已同步后端的订单）并设置为当前订单
*
* 通过传入真实的 orderId，对已缓存的订单数据进行更新，
* 会覆盖 order_info 与金额等字段，并重新计算待付金额，最后设置为 currentOrder。
*/
updateLocalOrderAsync(params: UpdateLocalOrderParams): Promise<PaymentOrder>;
/**
* 完成结账
*/
completeCheckoutAsync(): Promise<{
success: boolean;
orderId?: string;
}>;
/**
* 获取订单原始数据
*/
getOrderOriginalData(): any;
/**
* 获取当前订单基础信息
*
* 返回当前订单的基础信息，包括订单状态、金额、支付状态等
*/
getCurrentOrderInfo(): CurrentOrderInfo | null;
/**
* 获取当前订单的支付项
*
* 返回当前订单的所有支付项，包括活跃和已撤销的支付项
*/
getCurrentOrderPaymentItemsAsync(): Promise<PaymentItem[]>;
/**
* 获取订单模块
*/
getOrderModule(): OrderModule;
/**
* 获取支付模块
*/
getPaymentModule(): PaymentModule;
/**
* 替换本地订单ID为真实订单ID
*
* 当后端订单创建完成后，调用此方法将本地虚拟订单ID替换为真实订单ID
*
* @param newOrderId 后端返回的真实订单ID
* @returns 更新后的订单对象，如果当前没有订单则返回null
*/
replaceLocalOrderIdAsync(newOrderId: string): Promise<PaymentOrder | null>;
/**
* 设置自定义支付金额
*
* 允许UI自定义本次支付的金额，通常用于部分支付或调整支付金额场景
*
* @param amount 自定义支付金额，必须是有效的数字字符串
*/
setStateAmountAsync(amount: string): Promise<void>;
/**
* 获取当前自定义支付金额
*
* @returns 当前设置的自定义支付金额
*/
getStateAmount(): string;
/**
* 获取系统计算的待付金额（只读）
*
* 此方法返回系统内部计算的实际待付金额，不允许外部修改
*
* @returns 当前系统计算的待付金额
*/
getBalanceDueAmount(): string;
/**
* 获取购物车小计数据
*
* 返回当前结账流程中的购物车小计项数据，包含各种费用明细
*
* @returns 购物车小计数据数组，如果没有则返回 null
*/
getCartSummary(): CartSummaryItem[] | null;
/**
* 获取支付方式列表
*
* 优先使用 store 中的缓存数据，避免重复接口调用。
* 如果 store 中没有数据，则调用 Payment 模块的方法获取。
*
* @returns 支付方式列表
*/
getPaymentMethodsAsync(): Promise<PaymentMethod[]>;
/**
* 为当前订单添加支付项
*
* 向当前活跃订单添加一个支付项，支付项包含支付方式信息和金额
*
* @param paymentItem 支付项数据
* @throws 当前没有活跃订单时抛出错误
*/
addPaymentItemAsync(paymentItem: PaymentItemInput, orderUuid?: string): Promise<void>;
/**
* 删除当前订单的支付项
*
* 从当前活跃订单中删除指定的支付项，支付项将被标记为已撤销状态
*
* @param paymentUuid 要删除的支付项UUID
* @throws 当前没有活跃订单时抛出错误
* @throws 支付项不存在时抛出错误
*/
deletePaymentItemAsync(paymentUuid: string): Promise<void>;
/**
* 批量更新当前订单的代金券支付项（覆盖更新）
*
* 删除所有现有的代金券支付项，然后添加新的代金券支付项。
* 这是一个覆盖式更新操作，确保代金券支付项的一致性。
*
* @param voucherPaymentItems 新的代金券支付项列表，每个都必须包含 voucher_id
* @throws 当前没有活跃订单时抛出错误
* @throws 支付项缺少 voucher_id 时抛出错误
*/
updateVoucherPaymentItemsAsync(voucherPaymentItems: PaymentItemInput[]): Promise<void>;
/**
* 修改当前订单的定金状态
*
* 更新当前订单的 is_deposit 字段，用于标识订单是否为定金订单
*
* @param isDeposit 定金状态 (1: 定金订单, 0: 全款订单)
* @throws 当前没有活跃订单时抛出错误
*/
updateOrderDepositStatusAsync(isDeposit: number): Promise<void>;
/**
* 手动设置当前订单的定金金额
*
* 允许手动设置订单的定金金额，通常用于用户自定义定金支付场景
*
* @param depositAmount 定金金额，必须是有效的数字字符串，且不能超过订单总额
* @throws 当前没有活跃订单时抛出错误
* @throws 定金金额格式无效或超过订单总额时抛出错误
*/
setDepositAmountAsync(depositAmount: string): Promise<void>;
/**
* 手动同步订单到后端
*
* 用于强制同步订单到后端，特别适用于纯代金券支付完成的订单
*/
manualSyncOrderAsync(): Promise<{
success: boolean;
message?: string;
orderId?: string;
orderUuid?: string;
response?: any;
}>;
/**
* 获取当前订单备注
*
* @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)，
* 适用于用户想要保存订单但稍后完成支付的场景
*/
saveForLaterPaymentAsync(): Promise<{
success: boolean;
message?: string;
orderId?: string;
orderUuid?: string;
response?: any;
}>;
/**
* 更新订单备注
*
* @param note 订单备注内容
*/
updateOrderNoteAsync(note: string): Promise<void>;
/**
* 处理错误
*/
private handleError;
/**
* 处理支付成功
*/
private handlePaymentSuccess;
/**
* 处理支付错误
*/
private handlePaymentError;
/**
* 验证结账参数
*/
private validateCheckoutParams;
/**
* 处理现金支付项的找零逻辑
*
* @param paymentItem 原始支付项
* @returns 处理后的支付项（包含找零信息）
*/
private processCashPaymentItem;
/**
* 预加载支付方式（在初始化时调用）
*/
private preloadPaymentMethods;
/**
* 清理过期的已同步订单数据
*
* 删除本地 IndexDB 中超过指定天数且已同步到后端的订单数据
*/
private cleanupExpiredOrdersAsync;
/**
* 清除计算缓存
*/
private clearCalculationCache;
/**
* 批量获取订单数据（用于性能优化）
* 一次性获取所有需要的数据，避免重复查询
*/
private fetchOrderDataBatch;
/**
* 从支付项数组计算已支付金额（纯计算，不查询数据库）
*/
private calculatePaidAmountFromItems;
/**
* 计算已支付金额（从 Payment 模块获取最新数据）
*
* 注意：此方法保持独立性，可以单独调用。
* 在 updateStateAmountToRemaining 等批量操作中会使用缓存优化。
*/
private calculatePaidAmountAsync;
/**
* 从订单和支付项计算剩余金额（纯计算，不查询数据库）
*/
private calculateRemainingAmountFromData;
/**
* 从订单和支付项计算剩余总金额（纯计算，排除定金）
*/
private calculateRemainingTotalAmountFromData;
/**
* 计算剩余未支付金额（从 Payment 模块获取最新数据）
*
* 注意：此方法保持独立性，可以单独调用。
* 在 updateStateAmountToRemaining 等批量操作中会使用缓存优化。
*/
private calculateRemainingAmountAsync;
/**
* 计算剩余未支付金额（排除定金计算，始终使用订单总金额）
*
* 注意：此方法保持独立性，可以单独调用。
* 在 updateStateAmountToRemaining 等批量操作中会使用缓存优化。
*/
private calculateRemainingTotalAmountAsync;
/**
* 更新 balanceDueAmount 为当前剩余未支付金额（系统内部计算）
*/
private updateBalanceDueAmount;
/**
* 更新 stateAmount 为当前剩余未支付金额
*
* 优化版本：批量获取数据，避免重复查询数据库
*/
private updateStateAmountToRemaining;
/**
* 检查订单支付是否完成（优化版，复用已获取的数据）
*
* @param paymentItems 已获取的支付项数据
* @param remainingAmount 已计算的剩余金额
*/
private checkOrderPaymentCompletionOptimized;
/**
* 检查订单支付是否完成
*
* 当剩余待付款金额 <= 0 时，触发订单支付完成事件
*
* 注意：此方法保持独立性，可以单独调用。
* 在 updateStateAmountToRemaining 中会使用优化版本。
*/
private checkOrderPaymentCompletion;
private repairEftposPaymentFromIndexDbAsync;
private syncOrderToBackendFromIndexDbAsync;
/**
* 同步订单到后端并返回真实订单ID
*
* @param isManual 是否为手动同步，默认为 false
* @param customPaymentItems 自定义支付项列表，如果提供则使用此列表而不是从数据库获取
* @returns 包含订单ID、UUID和完整后端响应的对象
*/
private syncOrderToBackendWithReturn;
setOtherParams(params: Record<string, any>, { cover }?: {
cover?: boolean;
}): Promise<void>;
/**
* 通过订单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;
}>;
destroy(): Promise<void>;
/**
* 重置 store 状态
*
* 在创建新订单前调用，确保状态完全干净
*
* 🚀 性能优化：改为同步方法，事件发射不阻塞主流程
*/
private resetStoreState;
}