Checkout 价格计算链路

单一数据源 (Single Source of Truth) 设计 — 解决支付页面多处金额不一致的 Penny Rounding 问题

1. 问题背景

Checkout 页面有四处显示"总金额"，来自三个不同组件：

2. 税率与基础概念

逐项加税 vs 总额加税 (Penny Rounding 问题)

3. 数据流全景

flowchart TD
    subgraph API["后端 API"]
        DB["sub_appointments\nprice = 税前价格"]
    end

    subgraph LOAD["loadInvoice()"]
        PARSE["parseFloat(sub.price)"]
        ITAX["逐项加税\nroundToTwo(price × 1.08875)"]
        ITEM["item.subtotal = 含税单价"]
    end

    subgraph HOOK["useCheckoutState"]
        SUM["state.subtotal\n= Σ item.subtotal\n(含税总额)"]
        DISC["state.totalDiscountAmount\n= Σ discount.amount\n(税前折扣)"]
        DUE["state.amountDue\n= subtotal − discount×(1+TAX) − paid"]
    end

    subgraph ODS["OrderDetailsSection"]
        BT["subtotalBeforeTax\n= Σ roundToTwo(item / 1.08875)\n逐项反推"]
        TAD["totalAfterDiscount\n= subtotal − discount×(1+TAX)\n同 useCheckoutState 公式"]
        ADPT["afterDiscountPreTax\n= subtotalBeforeTax − discount"]
        TAX["taxAmount\n= totalAfterDiscount − afterDiscountPreTax\n反推保证加法恒等"]
        PAID["totalPaid = Σ transactions"]
        AMD["actualAmountDue\n= totalAfterDiscount − totalPaid"]
    end

    subgraph DISPLAY["页面显示"]
        D1["Subtotal: subtotalBeforeTax"]
        D2["Discount: −discount.amount"]
        D3["After Discount: afterDiscountPreTax"]
        D4["Tax: taxAmount"]
        D5["Total: totalAfterDiscount"]
        D6["Amount Due: actualAmountDue"]
        D7["Payment Amount: state.amountDue"]
        D8["Confirm Amount: effectivePaymentAmount"]
    end

    DB --> PARSE --> ITAX --> ITEM
    ITEM --> SUM
    SUM --> DUE
    DISC --> DUE

    ITEM -->|"items prop"| BT
    SUM -->|"subtotal prop"| TAD
    TAD --> ADPT --> TAX
    TAD --> AMD

    BT --> D1
    DISC -->|"discounts prop"| D2
    ADPT --> D3
    TAX --> D4
    TAD --> D5
    AMD --> D6
    DUE --> D7
    DUE -->|"splitAmount ?? amountDue"| D8

    style DUE fill:#1a365d,stroke:#3b82f6,stroke-width:2px
    style TAD fill:#1a365d,stroke:#3b82f6,stroke-width:2px
    style D5 fill:#064e3b,stroke:#22c55e
    style D6 fill:#064e3b,stroke:#22c55e
    style D7 fill:#064e3b,stroke:#22c55e
    style D8 fill:#064e3b,stroke:#22c55e

4. 核心公式（权威计算链）

所有金额从以下 6 步依次派生，不允许独立重算：

TAX_RATE = 0.08875
roundToTwo = (v) => Math.round(v * 100) / 100

// ① 税前小计：逐项反推再求和（不是总额反除！）
subtotalBeforeTax = roundToTwo(
  Σ roundToTwo(item.subtotal / (1 + TAX_RATE))
)

// ② Total（含税、折后）：权威公式，与 useCheckoutState 完全一致
totalAfterDiscount = roundToTwo(
  subtotal − totalDiscountAmount × (1 + TAX_RATE)
)

// ③ 折后税前
afterDiscountPreTax = roundToTwo(subtotalBeforeTax − totalDiscountAmount)

// ④ 税额：反推（确保 afterDiscountPreTax + tax = total 恒等）
taxAmount = roundToTwo(totalAfterDiscount − afterDiscountPreTax)

// ⑤ 已支付
totalPaid = Σ (tx.total_amount − tx.tip_amount − tx.refunded_amount)

// ⑥ 应付
actualAmountDue = roundToTwo(max(0, totalAfterDiscount − totalPaid))

为什么 Tax 必须反推而不能直接算？

5. 完整数值示例

场景：两项服务 + $15 折扣

场景：无折扣

注意：$11.99 ≠ $135 × 8.875% = $11.98，这 1 分钱差异来自逐项计税的四舍五入，是正确的行为。

6. 组件引用关系

flowchart LR
    subgraph NCF["NewCheckoutFlow (父组件)"]
        STATE["useCheckoutState()"]
        EPA["effectivePaymentAmount\n= splitAmount ?? state.amountDue"]
    end

    subgraph ODS["OrderDetailsSection"]
        direction TB
        O1["Subtotal"]
        O2["Discount"]
        O3["After Discount"]
        O4["Tax"]
        O5["Total"]
        O6["Amount Due"]
    end

    subgraph SPS["SplitPaymentSelector"]
        S1["Payment Amount"]
    end

    subgraph CONFIRM["Confirm Payment"]
        C1["Amount Due"]
    end

    STATE -->|"items, subtotal,\ndiscounts, amountDue"| ODS
    STATE -->|"amountDue, subtotal,\nitems, discounts"| SPS
    STATE --> EPA --> CONFIRM

    style STATE fill:#1a365d,stroke:#3b82f6,stroke-width:2px
    style O5 fill:#064e3b,stroke:#22c55e
    style O6 fill:#064e3b,stroke:#22c55e
    style S1 fill:#064e3b,stroke:#22c55e
    style C1 fill:#064e3b,stroke:#22c55e

7. 涉及文件清单

8. 设计原则总结

更新于 2026-02-21 · Celoria Checkout Price Calculation Reference