@pisell/pisellos 2.1.3 → 2.1.5

package/dist/solution/Checkout/appointmentDemo.json

@@ -0,0 +1 @@
+{"type":"appointment_booking","platform":"PC","sales_channel":"my_pisel","order_sales_channel":"online_store","bookings":[{"id":0,"number":1,"registration_type":"all","relation_products":[],"is_all":false,"product":{"num":1,"product_id":61170,"product_variant_id":0,"product_bundle":[],"product_option_item":[],"discount_list":[{"amount":100,"type":"good_pass","discount":{"resource_id":64523,"title":{"auto":"玄-商品券","original":"玄-商品券","en":null,"zh-CN":null,"zh-HK":null},"original_amount":100,"product_id":61170,"percent":"1.00"}}]},"sub_type":"minutes","duration":480,"like_status":"common","resources":[{"relation_type":"form","like_status":"common","form_id":35,"relation_id":40357,"capacity":1,"metadata":{"combined_resource":{"status":1,"resource_ids":[40262,40263]},"form_name":"桌台","resource_name":"组合资源测试table-0422-01"},"children":[{"relation_type":"form","like_status":"common","id":40262,"main_field":"A01（组合资源-小桌-4 人）","resourceType":"single","form_id":35,"relation_id":40262,"capacity":1,"metadata":{"combined_resource":null,"form_name":"桌台","resource_name":"A01（组合资源-小桌-4 人）"}},{"relation_type":"form","like_status":"common","id":40263,"main_field":"A02（组合资源-小桌-4 人）","resourceType":"single","form_id":35,"relation_id":40263,"capacity":0,"metadata":{"combined_resource":null,"form_name":"桌台","resource_name":"A02（组合资源-小桌-4 人）"}}]},{"relation_type":"form","like_status":"common","form_id":214,"relation_id":38350,"capacity":1,"metadata":{"combined_resource":null,"form_name":"校区2","resource_name":"West Campus"}}],"schedule_id":0,"start_date":"2025-08-22","start_time":"09:00","select_date":"2025-08-22","end_time":"17:00","end_date":"2025-08-22","metadata":{"account":{"id":13433,"username":"a a"},"capacity":[{"id":0,"value":1,"name":""}]},"holder":null,"relation_forms":[]}],"shop_note":"","schedule_date":"2025-08-22 09:00:00","is_deposit":0,"relation_products":[],"relation_forms":[]}

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

@@ -0,0 +1,509 @@
+import { Module, PisellCore, ModuleOptions } from '../../types';
+import { BaseModule } from '../../modules/BaseModule';
+import { OrderModule } from '../../modules/Order';
+import { PaymentModule } from '../../modules/Payment';
+import { CheckoutModuleAPI, CheckoutStep, CheckoutInitParams, CreateLocalOrderParams, PlaceOrderParams, CreateOrderParams, ProcessPaymentParams, CheckoutStatusInfo, CheckoutSummary, CurrentOrderInfo, CartSummaryItem, ExtractedAmountInfo, 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;
+    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>;
+    getProductListByOrder(): {
+        product_id: number;
+        product_variant_id: string;
+        quantity: number;
+        selling_price: number;
+    }[];
+    initWalletData(params?: {
+        order_wait_pay_amount: number;
+    }): Promise<void>;
+    /**
+     * 创建本地订单 (前端模拟下单流程)
+     *
+     * 此方法用于在前端模拟整个下单流程，创建一个本地的虚拟订单。
+     * 用户在购物车点击下单时，会把购物车参数传递给此方法，
+     * 方法会记录参数并创建本地虚拟订单，然后用 Payment 模块管理支付流程。
+     */
+    createLocalOrderAsync(params: CreateLocalOrderParams): Promise<PaymentOrder>;
+    /**
+     * 手动下单 (根据虚拟订单生成实际订单)
+     *
+     * 使用当前存储的本地订单数据调用 Order 模块创建真实订单
+     */
+    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[]>;
+    /**
+     * 获取订单原始数据
+     */
+    getOrderOriginalData(): any;
+    /**
+     * 获取当前订单基础信息
+     *
+     * 返回当前订单的基础信息，包括订单状态、金额、支付状态等
+     */
+    getCurrentOrderInfo(): CurrentOrderInfo | null;
+    /**
+     * 获取当前订单的支付项
+     *
+     * 返回当前订单的所有支付项，包括活跃和已撤销的支付项
+     */
+    getCurrentOrderPaymentItemsAsync(): Promise<PaymentItem[]>;
+    /**
+     * 验证结账前置条件
+     */
+    validateCheckoutAsync(): Promise<{
+        valid: boolean;
+        errors: string[];
+    }>;
+    /**
+     * 重试失败的操作
+     */
+    retryFailedOperationAsync(): Promise<void>;
+    /**
+     * 设置当前步骤
+     */
+    setCurrentStep(step: CheckoutStep): void;
+    /**
+     * 获取订单模块
+     */
+    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;
+    /**
+     * 刷新 stateAmount 为当前剩余未支付金额
+     *
+     * UI 可以调用此方法来主动刷新支付金额状态
+     */
+    refreshStateAmountAsync(): Promise<void>;
+    /**
+     * 获取购物车小计数据
+     *
+     * 返回当前结账流程中的购物车小计项数据，包含各种费用明细
+     *
+     * @returns 购物车小计数据数组，如果没有则返回 null
+     */
+    getCartSummary(): CartSummaryItem[] | null;
+    /**
+     * 获取提取的金额详细信息
+     *
+     * 从当前的购物车小计数据中提取结构化的金额信息
+     *
+     * @returns 提取的金额信息对象，如果没有小计数据则返回 null
+     */
+    getExtractedAmountInfo(): ExtractedAmountInfo | null;
+    /**
+     * 获取支付方式列表
+     *
+     * 优先使用 store 中的缓存数据，避免重复接口调用。
+     * 如果 store 中没有数据，则调用 Payment 模块的方法获取。
+     *
+     * @returns 支付方式列表
+     */
+    getPaymentMethodsAsync(): Promise<PaymentMethod[]>;
+    /**
+     * 为当前订单添加支付项
+     *
+     * 向当前活跃订单添加一个支付项，支付项包含支付方式信息和金额
+     *
+     * @param paymentItem 支付项数据
+     * @throws 当前没有活跃订单时抛出错误
+     */
+    addPaymentItemAsync(paymentItem: PaymentItemInput): 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 customer 客户信息 (customer_id 和/或 customer_name)
+     * @throws 当前没有活跃订单时抛出错误
+     */
+    updateOrderCustomerAsync(customer: {
+        customer_id?: string;
+        customer_name?: string;
+    }): Promise<void>;
+    /**
+     * 获取当前订单的客户信息
+     *
+     * @returns 当前客户信息，如果没有则返回 null
+     */
+    getCurrentCustomer(): {
+        customer_id?: string;
+        customer_name?: string;
+    } | null;
+    /**
+     * 检查订单是否需要手动同步（异步版本）
+     *
+     * 返回订单是否为纯代金券支付且待付金额<=0但未同步的状态
+     * 从 Payment 模块获取最新的支付项数据
+     */
+    needsManualSyncAsync(): Promise<boolean>;
+    /**
+     * 手动同步订单到后端
+     *
+     * 用于强制同步订单到后端，特别适用于纯代金券支付完成的订单
+     */
+    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;
+    }>;
+    /**
+     * 获取当前商店折扣金额
+     *
+     * @returns 当前的商店折扣金额，如果没有则返回0
+     */
+    getShopDiscount(): number;
+    /**
+     * 更新订单商店折扣
+     *
+     * 同时更新cartSummary和localOrderData中的shop_discount值
+     *
+     * @param discountAmount 商店折扣金额
+     */
+    updateShopDiscountAsync(discountAmount: number): Promise<void>;
+    /**
+     * 更新订单备注
+     *
+     * @param note 订单备注内容
+     */
+    updateOrderNoteAsync(note: string): Promise<void>;
+    /**
+     * 设置状态
+     */
+    private setStatus;
+    /**
+     * 设置步骤
+     */
+    private setStep;
+    /**
+     * 处理错误
+     */
+    private handleError;
+    /**
+     * 处理支付成功
+     */
+    private handlePaymentSuccess;
+    /**
+     * 处理支付错误
+     */
+    private handlePaymentError;
+    /**
+     * 验证结账参数
+     */
+    private validateCheckoutParams;
+    /**
+     * 处理现金支付项的找零逻辑
+     *
+     * @param paymentItem 原始支付项
+     * @returns 处理后的支付项（包含找零信息）
+     */
+    private processCashPaymentItem;
+    /**
+     * 判断是否为现金支付
+     *
+     * @param paymentCode 支付代码
+     * @param paymentType 支付类型
+     * @returns 是否为现金支付
+     */
+    private isCashPayment;
+    /**
+     * 预加载支付方式（在初始化时调用）
+     */
+    private preloadPaymentMethods;
+    /**
+     * 清理过期的已同步订单数据
+     *
+     * 删除本地 IndexDB 中超过指定天数且已同步到后端的订单数据
+     */
+    private cleanupExpiredOrdersAsync;
+    /**
+     * 计算已支付金额（从 Payment 模块获取最新数据）
+     */
+    private calculatePaidAmountAsync;
+    /**
+     * 计算剩余未支付金额（从 Payment 模块获取最新数据）
+     */
+    private calculateRemainingAmountAsync;
+    /**
+     * 更新 balanceDueAmount 为当前剩余未支付金额（系统内部计算）
+     */
+    private updateBalanceDueAmount;
+    /**
+     * 更新 stateAmount 为当前剩余未支付金额
+     */
+    private updateStateAmountToRemaining;
+    /**
+     * 检查订单支付是否完成
+     *
+     * 当剩余待付款金额 <= 0 时，触发订单支付完成事件
+     */
+    private checkOrderPaymentCompletion;
+    /**
+     * 同步订单到后端
+     *
+     * 调用后端 /order/checkout 接口创建真实订单
+     */
+    /**
+     * 同步订单到后端并返回真实订单ID
+     *
+     * @param isManual 是否为手动同步，默认为 false
+     * @param customPaymentItems 自定义支付项列表，如果提供则使用此列表而不是从数据库获取
+     * @returns 包含订单ID、UUID和完整后端响应的对象
+     */
+    private syncOrderToBackendWithReturn;
+    private syncOrderToBackend;
+    /**
+     * 获取状态消息
+     */
+    private getStatusMessage;
+    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 resetStoreStateAsync;
+    /**
+     * 手动清理已完成的订单状态（公开方法）
+     *
+     * 供UI层调用的公开方法，用于手动清理订单状态
+     *
+     * @returns 清理结果
+     */
+    clearCompletedOrderAsync(): Promise<{
+        success: boolean;
+        message?: string;
+        clearedOrder?: {
+            uuid: string;
+            orderId: string;
+        } | null;
+    }>;
+}