Web 支付模块 — CUJ 关键用户旅程

Checkout, Payments & Invoices | 更新时间: 2026-02-09

目录

CUJ 总览与优先级矩阵

结账架构概览

核心组件关系

flowchart TD
    PAGE["checkout/[appointmentId]/page.tsx"] --> NCF["NewCheckoutFlow.tsx - 主编排器"]
    NCF --> ODS["OrderDetailsSection - 订单明细"]
    NCF --> DS["DiscountSection - 折扣/优惠券/礼品卡"]
    NCF --> TS["TipSelector - 小费"]
    NCF --> PMS["PaymentMethodSelector - 支付方式"]
    NCF --> SPS["SplitPaymentSelector - 拆分模式"]

    PMS -->|"Cash"| CPF["CashPaymentForm - 现金支付"]
    PMS -->|"Card"| TERM["TerminalSelector - 选择终端"]
    TERM --> PIM["PaymentInitiateModal - 发起刷卡"]
    PIM --> PPM["PaymentProgressModal - WebSocket 等待"]

    CPF --> PSS["PaymentSuccessSummary - 成功"]
    PPM --> PSS

    SPS -->|"按服务"| SSV["ServiceSplitView"]
    SPS -->|"按人"| PSV["PersonSplitView"]
    SPS -->|"手动金额"| MSI["ManualSplitInput"]

    style NCF fill:#2196F3,stroke:#1565C0,color:#fff
    style PSS fill:#4CAF50,stroke:#2E7D32,color:#fff

支付状态生命周期

stateDiagram-v2
    [*] --> pending: 创建订单

    pending --> processing: 发起支付
    processing --> completed: 支付成功
    processing --> failed: 支付失败
    processing --> cancelled: 用户取消

    failed --> processing: 重试
    completed --> refunded: 全额退款
    completed --> partial_refunded: 部分退款

    state "Transaction Status" as ts {
        pending: PENDING
        processing: PROCESSING
        completed: COMPLETED
        failed: FAILED
        cancelled: CANCELLED
        refunded: REFUNDED
        partial_refunded: PARTIAL_REFUNDED
    }

预约支付状态 vs 交易状态

关键业务规则

CUJ-F1: 结账收款 — 现金

P0 核心营收路径 — 现金收款

用户流程

flowchart TD
    A["预约状态: pending_payment"] --> B["点击 Take Payment"]
    B --> C["/checkout/[appointmentId]"]
    C --> NCF["NewCheckoutFlow 加载订单"]
    NCF --> D["OrderDetailsSection 显示服务明细"]
    D --> E["TipSelector 选择小费"]
    E --> F["PaymentMethodSelector 选择 Cash"]
    F --> G["CashPaymentForm"]
    G --> H["输入收到金额"]
    H --> I{"金额 >= 应付?"}
    I -->|"是"| J["显示找零金额"]
    I -->|"否"| K["按钮禁用，提示不足"]
    J --> L["点击确认"]
    L --> M["POST /api/payment/cash"]
    M --> N["PaymentSuccessSummary"]
    N --> O["appointments.status = finished"]

    style C fill:#2196F3,stroke:#1565C0,color:#fff
    style N fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 F1.1: 现金支付 — Happy Path

测试: checkout-flow.spec.ts, full-flow/05-payment-pairwise.spec.ts (部分覆盖)

场景 F1.2: 现金不足

场景 F1.3: 无小费直接支付

CUJ-F2: 结账收款 — 刷卡

P0 核心营收路径 — POS 终端刷卡

用户流程

flowchart TD
    A["PaymentMethodSelector 选择 Card"] --> B["TerminalSelector 选择在线终端"]
    B --> C["PaymentInitiateModal 确认金额"]
    C --> D["POST /api/payment/initiate"]
    D --> E["PaymentProgressModal"]
    E --> F{"WebSocket 事件"}
    F -->|"acknowledged"| G["终端已收到请求"]
    F -->|"processing"| H["客户正在操作"]
    F -->|"completed"| I["PaymentSuccessSummary"]
    F -->|"failed"| J["显示失败原因，可重试"]
    F -->|"timeout"| K["超时，提示检查终端"]
    F -->|"cancelled"| L["用户取消"]

    style E fill:#FF9800,stroke:#E65100,color:#fff
    style I fill:#4CAF50,stroke:#2E7D32,color:#fff
    style J fill:#f44336,stroke:#c62828,color:#fff

BDD 场景

场景 F2.1: 信用卡支付 — Happy Path

测试: payment/processing.spec.ts (部分覆盖)

场景 F2.2: 刷卡失败后重试

场景 F2.3: 无可用终端

场景 F2.4: 支付超时

CUJ-F3: 折扣与礼品卡抵扣

P1 营销转化 — 在结账时应用优惠

用户流程

flowchart TD
    A["OrderDetailsSection 显示原价"] --> B["DiscountSection"]
    B --> C{"折扣类型"}
    C -->|"自动折扣"| D["系统自动应用匹配的折扣"]
    C -->|"优惠券"| E["输入优惠码"]
    C -->|"礼品卡"| F["GiftCardInput 输入卡号"]

    E --> G["POST validate coupon"]
    G --> H{"验证结果"}
    H -->|"有效"| I["应用折扣，更新金额"]
    H -->|"无效/过期"| J["显示错误"]

    F --> K["POST /api/payment/gift-card/validate"]
    K --> L{"验证结果"}
    L -->|"有效"| M["显示余额，应用抵扣"]
    L -->|"无效"| N["显示错误"]

    D --> O["AmountDueDisplay 更新应付金额"]
    I --> O
    M --> O

    style B fill:#FF9800,stroke:#E65100,color:#fff
    style O fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 F3.1: 优惠券码应用

测试: full-flow/02f-discount-crud.spec.ts (部分覆盖)

场景 F3.2: 礼品卡抵扣

测试: full-flow/02g-giftcard-crud.spec.ts (部分覆盖)

场景 F3.3: 礼品卡余额大于应付

场景 F3.4: 无效优惠码

场景 F3.5: 自动折扣

CUJ-F4: 拆分支付

P1 支付灵活性 — 多种支付方式或分次支付

拆分模式

用户流程

flowchart TD
    A["SplitPaymentSelector 选择拆分模式"] --> B{"模式"}
    B -->|"By Service"| C["ServiceSplitView 勾选服务"]
    B -->|"By Person"| D["PersonSplitView 选择客人"]
    B -->|"Manual"| E["ManualSplitInput 输入金额"]

    C --> F["AmountDueDisplay 显示本次应付"]
    D --> F
    E --> F

    F --> G["选择支付方式并完成"]
    G --> H{"全部付清?"}
    H -->|"是"| I["payment_status = paid"]
    H -->|"否"| J["payment_status = partial"]
    J --> K["PaidTransactionsList 显示已付记录"]
    K --> L["继续下一笔支付"]
    L --> A

    style F fill:#FF9800,stroke:#E65100,color:#fff
    style I fill:#4CAF50,stroke:#2E7D32,color:#fff
    style J fill:#FFD54F,stroke:#F9A825,color:#333

BDD 场景

场景 F4.1: 现金+刷卡拆分

测试: full-flow/05-payment-pairwise.spec.ts (部分覆盖)

场景 F4.2: 按服务拆分

CUJ-F5: 团体结账

P1 大额订单 — 多客人预约的结账

结账模式

BDD 场景

场景 F5.1: 团体总付

场景 F5.2: 团体分人付

场景 F5.3: 跳过某位客人的付款

测试: 缺失 — 需新增

CUJ-F6: 退款

P1 纠纷处理 — 全额或部分退款

退款路径

用户流程

flowchart TD
    A["已完成支付的预约"] --> B["打开 RefundModal"]
    B --> C["显示原交易信息"]
    C --> D{"退款类型"}
    D -->|"全额"| E["自动填入全部金额"]
    D -->|"部分"| F["手动输入退款金额"]

    E --> G["选择退款原因"]
    F --> G
    G --> H{"原支付方式"}
    H -->|"Card 当天"| I["VOID 到同一终端"]
    H -->|"Card 非当天"| J["Standard Refund"]
    H -->|"Cash"| K["现金退款（关联钱箱）"]
    H -->|"Gift Card"| L["余额恢复"]

    I --> M{"处理结果"}
    J --> M
    K --> M
    L --> M
    M -->|"成功"| N["更新 transaction.refunded_amount"]
    M -->|"失败"| O["显示错误，可重试"]

    N --> P["更新 appointment.payment_status"]

    style B fill:#f44336,stroke:#c62828,color:#fff
    style N fill:#4CAF50,stroke:#2E7D32,color:#fff

BDD 场景

场景 F6.1: 当天刷卡 VOID

测试: 缺失 — 需新增

场景 F6.2: 部分退款（信用卡）

场景 F6.3: 现金退款

场景 F6.4: 退款失败重试

CUJ-F7: 发票管理

P2 财务记录 — 查看和打印发票

发票数据结构

BDD 场景

场景 F7.1: 查看发票详情

测试: invoices/management.spec.ts, full-flow/09-invoice.spec.ts (部分覆盖)

场景 F7.2: 团体发票 — 多 invoice_items

场景 F7.3: 作废发票

CUJ-F8: 终端管理

P2 硬件设施 — 管理 CodePay POS 终端

BDD 场景

场景 F8.1: 添加新终端

测试: 缺失 — 需新增

场景 F8.2: 查看终端状态