Payment Status Recovery & Resilience

支付状态恢复与韧性设计 — 2026-02-12

1. 问题背景

当前端支付等待 UI（PaymentProgressModal）被意外关闭，或者用户导航离开支付页面时，会丢失以下关键状态：

同时，已有的 queryPaymentStatus 函数和后端 POST /api/payment/query-status 端点从未被调用过，是现成但闲置的基础设施。

2. 解决方案概览

flowchart TD
    A["用户发起支付 (initiatePayment)"] --> B["写入 sessionStorage"]
    B --> C{"支付进行中 (progress)"}
    C --> D["WebSocket 实时监听"]
    C --> E["轮询安全网 (5s)"]
    C --> F["beforeunload 拦截"]

    D --> G{"终态?"}
    E --> G
    G -- "completed" --> H["显示成功 + 清除 storage"]
    G -- "failed/cancelled/timeout" --> I["清除 storage + 重置"]
    G -- "仍在处理" --> C

    J["用户刷新/重开页面"] --> K["组件挂载"]
    K --> L{"sessionStorage 有待恢复数据?"}
    L -- "无" --> M["正常 idle"]
    L -- "有（未过期）" --> N["queryPaymentStatus 查后端"]
    N -- "仍在处理" --> O["恢复上下文 + 进入 progress"]
    N -- "已完成" --> P["toast 通知 + 清除"]
    N -- "已失败/过期" --> Q["清除 storage"]
    O --> C

五层防护机制：

3. 技术实现细节

3.1 sessionStorage 持久化

核心文件：frontend/web_app/src/components/Payment/PaymentCheckoutFlow.tsx

存储结构

Key:   payment_pending_{appointment.id}
Value: {
  paymentRequestId: string,   // CodePay 支付请求 ID
  orderId: string,            // 订单号
  transactionId: string,      // 交易记录 ID
  totalAmount: number,        // 支付金额
  storeId: string,            // 门店 ID
  terminalId: string,         // POS 终端 ID
  createdAt: number           // 写入时间戳 (Date.now())
}

为什么选择 sessionStorage 而非 localStorage？

生命周期

sequenceDiagram
    participant User
    participant UI as PaymentCheckoutFlow
    participant SS as sessionStorage
    participant Backend

    User->>UI: 选择终端，点击发送
    UI->>Backend: POST /api/payment/initiate
    Backend-->>UI: { request_id: "xyz" }
    UI->>SS: setItem("payment_pending_apt123", {...})
    Note over UI: stage = 'progress'

    alt 正常完成
        Backend-->>UI: WebSocket completed
        UI->>SS: removeItem("payment_pending_apt123")
    else 用户刷新页面
        User->>UI: 页面重新加载
        UI->>SS: getItem("payment_pending_apt123")
        SS-->>UI: { paymentRequestId: "xyz", ... }
        UI->>Backend: POST /api/payment/query-status
        Backend-->>UI: { status: "processing" }
        Note over UI: 恢复 → stage = 'progress'
    else 超过 10 分钟
        UI->>SS: getItem → createdAt 过期
        UI->>SS: removeItem (清除)
    end

3.2 轮询回退机制

防重复执行设计

轮询回调通过 paymentStatusRef（React ref）检查当前状态。如果已经是终态，跳过 API 调用。这避免了以下问题：

• WebSocket 已经触发了 completed → 1.5s 后 stage 变为 success → 在这 1.5s 内轮询可能也读到 completed → 如果不守卫，会触发重复的 setTimeout 和 toast
• 使用 ref 而非 state 作为守卫，避免将 paymentStatus 加入 useEffect 依赖数组（否则每次状态变化都会重置定时器）

3.3 自动恢复逻辑

flowchart TD
    A["组件挂载"] --> B{"recoveryAttemptedRef === appointment.id?"}
    B -- "是 (已尝试过)" --> Z["跳过"]
    B -- "否" --> C{"stage === 'idle'?"}
    C -- "否 (已在流程中)" --> Z
    C -- "是" --> D["标记为已尝试"]
    D --> E["loadPaymentContext(appointment.id)"]
    E --> F{"有数据?"}
    F -- "无" --> Z
    F -- "有" --> G{"已过期 (>10min)?"}
    G -- "是" --> H["清除 sessionStorage"]
    G -- "否" --> I["queryPaymentStatus(paymentRequestId)"]
    I --> J{"后端返回状态"}
    J -- "pending/acknowledged/processing" --> K["恢复全部上下文, stage='progress'"]
    J -- "completed" --> L["toast 成功通知, 清除"]
    J -- "failed/cancelled/timeout" --> M["静默清除"]
    J -- "网络错误" --> M

关键设计决策

• recoveryAttemptedRef：用 useRef<string> 记录已尝试恢复的 appointment ID，而非简单的 boolean。当切换到不同预约时，允许对新预约重新尝试恢复。
• 恢复时构造的 OrderDetails：只填充 UI 实际需要的字段（order_id, totalAmount），税额等设为 0。因为 PaymentProgressModal 只显示 orderId 和 totalAmount。
• 10 分钟过期时间：CodePay 默认支付超时 300 秒（5 分钟），10 分钟留余量覆盖网络延迟和重试场景。

3.4 beforeunload 防误操作

// 当 stage === 'progress' 时注册
window.addEventListener('beforeunload', (e) => {
  e.preventDefault();
  e.returnValue = '';  // 触发浏览器原生提示
});
// stage 变化或组件卸载时自动移除

3.5 WebSocket 生命周期解耦

4. applyPaymentStatus：统一状态转换

原来 WebSocket 事件处理和轮询结果各自维护一套 switch-case，容易不一致。重构后提取为 applyPaymentStatus(status, message?)，作为两个通道的 Single Source of Truth。

// WebSocket 事件 → applyPaymentStatus
function handlePaymentEvent(event: PaymentEvent) {
  if (event.requestId !== paymentRequestId) return;
  applyPaymentStatus(event.type || '', event.data?.message);
}

// 轮询结果 → applyPaymentStatus
const result = await queryPaymentStatus(paymentRequestId);
if (result.success && result.data?.status) {
  applyPaymentStatus(result.data.status, result.data.message);
}

applyPaymentStatus 内部负责：

1. 终态时清除 sessionStorage（clearPaymentContext）
2. 更新 paymentStatus 和 statusMessage
3. completed → 延迟 1.5s 跳转成功页
4. cancelled → 延迟 1.5s 重置流程

5. 优点

6. 局限性

7. CodePay Void 不可知问题深入分析

这是最重要的局限，值得单独展开：

问题根源

sequenceDiagram
    participant Merchant as 商家 (CodePay 后台)
    participant CodePay as CodePay 网关
    participant Our as 我们的后端
    participant DB as 我们的数据库

    Note over Merchant,DB: 场景1: 通过我们的 API 操作 (可追踪)
    Our->>CodePay: POST /api/entry/orderquery
    CodePay-->>Our: { status: "completed" }
    Our->>DB: UPDATE transactions SET status = 'completed'

    Note over Merchant,DB: 场景2: 商家直接在 CodePay 操作 (不可追踪)
    Merchant->>CodePay: 在 CodePay 后台直接 void
    CodePay->>CodePay: 交易已作废
    Note over Our,DB: 我们完全不知道这件事发生了!
    Note over DB: DB 仍然显示 status = 'completed'

为什么 webhook 也不行？

• CodePay 的 callback/webhook 只在通过其 Cloud API 发起的交易生命周期内推送状态更新
• 商家在 CodePay 管理后台直接操作 void，不一定会触发我们注册的 callback URL
• 即使 CodePay 未来支持 void 事件推送，需要我们主动注册和处理新的 webhook 类型

可能的解决路径（未实施）

8. 相关文件

9. 验证清单