POS 支付状态机 & 防护机制

PaymentCubit / VoidCubit / Backend 三端状态流转 + 恢复韧性机制 — 更新于 2026-02-19

1. 整体架构概览

POS 支付系统涉及三个独立运行的状态机，通过 WebSocket + REST API 协调：

graph LR
    subgraph Web["Web 前端"]
        W1["RefundModal / CheckoutFlow"]
    end
    subgraph Backend["Node.js 后端"]
        B1["payment_requests 表"]
        B2["transactions 表"]
        B3["refunds 表"]
    end
    subgraph POS["POS 终端 (Flutter)"]
        P1["PaymentCubit"]
        P2["VoidCubit"]
    end

    W1 -- "POST /pos-request" --> B1
    B1 -- "WebSocket pos:payment_request" --> P1
    P1 -- "POST /pos-confirm" --> B2
    B2 -- "WebSocket payment:completed" --> W1

    W1 -- "POST /refunds/card" --> B3
    B3 -- "WebSocket pos:void_request" --> P2
    P2 -- "POST /pos-void-confirm" --> B3
    B3 -- "WebSocket payment:void_completed" --> W1

1.5 端到端全景流程图 (支付 + VOID + 恢复)

下图展示了 POS Intent 支付系统的完整链路，包含正常流、异常流、三条恢复链路：

flowchart TD
    Start(["收银员点击 Checkout"])

    subgraph PAY["正常支付流"]
        P1["POST /pos-request"]
        P2["Backend 创建 payment_request (pending)"]
        P3["WebSocket → POS 设备"]
        P4["POS 自动 accept"]
        P5["客人确认订单 → 选小费"]
        P6["CodePay Intent 扣款"]
        P7{"扣款结果?"}
        P8["POST /pos-confirm (success)"]
        P9["Backend 创建 transaction + invoice"]
        P10["WebSocket → Web: payment:completed"]
        P11(["支付成功 ✅"])
        PF["POST /pos-confirm (failed)"]
        PF2["WebSocket → Web: payment:failed"]
        PF3(["支付失败 ❌"])
    end

    Start --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> P7
    P7 -- "成功" --> P8 --> P9 --> P10 --> P11
    P7 -- "失败" --> PF --> PF2 --> PF3

    subgraph SYNC["syncFailed 恢复链路"]
        S1{"3次 confirm 重试"}
        S2["全部失败"]
        S3["SecureStorage.save(JSON)"]
        S4["显示 Success (syncFailed)"]
        S5{"恢复路径?"}
        S6["Web 手动确认到账 (主要)"]
        S7["POS 下一笔请求触发重试 (兜底)"]
        S8["POST /pos-manual-confirm"]
    end

    P7 -- "成功但 confirm 失败" --> S1 --> S2 --> S3 --> S4 --> S5
    S5 -- "收银员操作 Web" --> S6 --> S8 --> P11
    S5 -. "POS 自动" .-> S7

    subgraph REFRESH["Web 刷新恢复链路"]
        R1["页面刷新 / 导航离开"]
        R2["CheckoutFlow mount"]
        R3["GET /pos-request/pending"]
        R4{"有 pending/acknowledged?"}
        R5["恢复进度条 + WebSocket 监听"]
        R6["正常状态"]
        R7{"POS 是否响应?"}
        R8["等待 POS → 正常完成"]
        R9["收银员点击 手动确认到账"]
        R10["输入 tip → POST /pos-manual-confirm"]
        R11["Backend 创建 transaction"]
        R12(["支付成功 ✅"])
    end

    P3 -. "⚡ 刷新" .-> R1 --> R2 --> R3 --> R4
    R4 -- "是" --> R5 --> R7
    R4 -- "否" --> R6
    R7 -- "POS 正常回来" --> R8 --> P10
    R7 -- "POS 无响应" --> R9 --> R10 --> R11 --> R12

    subgraph VOID["VOID 退款流"]
        V1["RefundModal → POST /refunds/card"]
        V2["Backend 检测 source=pos_intent"]
        V3{"设备在线?"}
        V4["创建 refund (pending)"]
        V5["WebSocket → POS: pos:void_request"]
        V6["POS → CodePay VOID Intent"]
        V7{"VOID 结果?"}
        V8["POST /pos-void-confirm (success)"]
        V9["refund → completed"]
        V10(["退款成功 ✅"])
        VF(["退款失败 ❌"])
        VO(["设备离线 → 400 错误"])
    end

    P11 -. "发起退款" .-> V1 --> V2 --> V3
    V3 -- "在线" --> V4 --> V5 --> V6 --> V7
    V3 -- "离线" --> VO
    V7 -- "成功" --> V8 --> V9 --> V10
    V7 -- "失败" --> VF

    subgraph VRECOV["VOID Modal 恢复链路"]
        VR1["关闭 RefundModal"]
        VR2["重新打开 Modal"]
        VR3["GET /refunds/pending"]
        VR4{"有 pending?"}
        VR5["恢复等待状态 + WebSocket"]
        VR6["正常状态"]
    end

    V5 -. "⚡ 关闭" .-> VR1 --> VR2 --> VR3 --> VR4
    VR4 -- "是" --> VR5
    VR4 -- "否" --> VR6

    style PAY fill:#0f1729,stroke:#00d4ff,color:#eee
    style SYNC fill:#1b0f0f,stroke:#f87171,color:#fca5a5
    style REFRESH fill:#0f1b0f,stroke:#4ade80,color:#86efac
    style VOID fill:#1b1b0f,stroke:#fbbf24,color:#fde68a
    style VRECOV fill:#0f1b1b,stroke:#06b6d4,color:#67e8f9

2. PaymentCubit 状态机 (支付流)

2.1 状态流转图

stateDiagram-v2
    [*] --> Idle
    Idle --> RequestReceived: WS payment_request
    RequestReceived --> OrderReview: POST /pos-accept OK
    RequestReceived --> Failure: POST /pos-accept fail
    OrderReview --> TipSelection: 客人确认订单
    TipSelection --> Processing: 客人选择小费
    Processing --> Success: CodePay OK + POST /pos-confirm
    Processing --> Failure: CodePay 拒绝 / Intent 超时

    Success --> Idle: 5s auto idle
    Failure --> Idle: 5s auto idle
    Cancelled --> Idle: 5s auto idle
    Timeout --> Idle: 5s auto idle

    OrderReview --> Cancelled: 收银员/客人取消
    TipSelection --> Cancelled: 收银员取消
    RequestReceived --> Cancelled: WS payment_cancelled
    RequestReceived --> Timeout: WS payment_timeout

    note right of Idle: 收到新请求时，终端状态自动复位
    note right of Processing: CodePay Intent 2分钟超时保护

2.2 状态详解

3. VoidCubit 状态机 (退款/VOID 流)

3.1 状态流转图

stateDiagram-v2
    [*] --> VoidIdle
    VoidIdle --> VoidRequestReceived: WS void_request
    VoidRequestReceived --> VoidProcessing: 自动执行 VOID
    VoidProcessing --> VoidSuccess: CodePay VOID 成功 + 服务端确认
    VoidProcessing --> VoidFailure: CodePay VOID 失败 / Intent 超时

    VoidSuccess --> VoidIdle: 5秒自动回 idle
    VoidFailure --> VoidIdle: 5秒自动回 idle

    VoidRequestReceived --> VoidIdle: WS void_cancelled

    note right of VoidIdle: 收到新请求时，终端状态自动复位
    note right of VoidProcessing: CodePay Intent 2分钟超时保护

3.2 状态详解

4. Backend 状态 (数据库记录)

4.1 支付请求生命周期 (payment_requests 表)

stateDiagram-v2
    [*] --> pending: POST /pos-request 创建
    pending --> accepted: POS 调用 /pos-accept
    accepted --> completed: POS 调用 /pos-confirm (success)
    accepted --> completed: Web 手动确认 /pos-manual-confirm
    accepted --> failed: POS 调用 /pos-confirm (failed)
    accepted --> cancelled: 收银员取消 / POS 取消
    pending --> timeout: 5分钟调度器超时
    accepted --> timeout: 5分钟调度器超时
    timeout --> completed: Web 手动确认 /pos-manual-confirm

4.2 退款生命周期 (refunds 表)

stateDiagram-v2
    [*] --> pending: POST /refunds/card 创建
    pending --> completed: POS 调用 /pos-void-confirm (success)
    pending --> failed_device: POS 调用 /pos-void-confirm (failed)
    pending --> failed_timeout: 5分钟调度器超时

    note right of pending: POS 设备离线时直接返回错误，不创建 pending 记录

5. 端到端支付流 (时序图)

sequenceDiagram
    participant Web as Web 前端
    participant API as Backend API
    participant WS as WebSocket
    participant POS as POS 终端
    participant CP as CodePay 硬件

    Web->>API: POST /api/payment/pos-request
    API->>API: 创建 payment_request (pending)
    API->>API: 调度 5 分钟超时
    API->>WS: broadcast pos:payment_request
    WS->>POS: pos:payment_request

    POS->>API: POST /api/payment/pos-accept
    API->>API: payment_request → accepted
    API-->>POS: 200 OK + tipConfig

    Note over POS: 显示订单 → 客人确认 → 选小费

    POS->>CP: Android Intent (initiatePayment)
    Note over CP: 客人刷卡/插卡/NFC
    CP-->>POS: Intent 结果 (success/fail)

    alt 支付成功
        POS->>API: POST /api/payment/pos-confirm (success)
        API->>API: 创建 transaction + invoice
        API->>WS: broadcast payment:completed
        WS->>Web: payment:completed
        Note over Web: 显示"支付成功"
    else 支付成功但 confirm 失败 (syncFailed)
        POS->>API: POST /pos-confirm (attempt 1/3)
        API--xPOS: 网络错误 / 500
        POS->>API: POST /pos-confirm (attempt 2/3, +2s)
        API--xPOS: 网络错误 / 500
        POS->>API: POST /pos-confirm (attempt 3/3, +4s)
        API--xPOS: 网络错误 / 500
        Note over POS: 3次重试全部失败
        POS->>POS: SecureStorage.saveUnsyncedPayment(JSON)
        Note over POS: 显示 Success (syncFailed: true)
    else 支付失败
        POS->>API: POST /api/payment/pos-confirm (failed)
        API->>WS: broadcast payment:failed
        WS->>Web: payment:failed
        Note over Web: 显示"支付失败"
    end

6. 端到端 VOID 流 (时序图)

sequenceDiagram
    participant Web as Web 前端
    participant API as Backend API
    participant WS as WebSocket
    participant POS as POS 终端
    participant CP as CodePay 硬件

    Web->>API: POST /api/payment/refunds/card
    API->>API: 检查 transaction.source === 'pos_intent'
    API->>API: 检查原始 POS 设备是否在线

    alt 设备离线
        API-->>Web: 400 "原支付终端离线"
    else 设备在线
        API->>API: 创建 refund (pending)
        API->>API: 调度 5 分钟超时
        API->>WS: emitToPosDevice(pos:void_request)
        WS->>POS: pos:void_request
        API-->>Web: 200 { waitingForDevice: true }
    end

    POS->>CP: Android Intent (voidTransaction)
    Note over CP: 设备处理 VOID
    CP-->>POS: Intent 结果

    alt VOID 成功
        POS->>API: POST /pos-void-confirm (success)
        Note over POS: 3次重试 + 指数退避
        API->>API: refund → completed, transaction → refunded
        API->>WS: broadcast payment:void_completed
        WS->>Web: void_completed
    else VOID 失败
        POS->>API: POST /pos-void-confirm (failed)
        API->>API: refund → failed
        API->>WS: broadcast payment:void_failed
        WS->>Web: void_failed
    end

    Note over Web: RefundModal 关闭后重新打开时
    Web->>API: GET /refunds/pending/{transactionId}
    API-->>Web: { pendingRefund: {...} } 或 null
    Note over Web: 如有 pending → 自动恢复等待状态 + 重新监听 WebSocket

7. 四层防护机制

系统采用四层纵深防御策略，前三层确保 POS 设备在任何异常情况下都不会永久卡死，第四层防止并发操作导致双重记账：

// PaymentCubit._onPaymentRequest()
if (state is! PaymentIdle) {
  if (_isTerminalState(state)) {
    // 自动复位 → 继续处理新请求
    emit(const PaymentIdle());
  } else {
    // 真正在处理中 → 拒绝新请求
    return;
  }
}

// 通过 override emit() 自动管理
@override
void emit(PaymentState state) {
  super.emit(state);
  if (state is PaymentIdle) {
    _stateWatchdog?.cancel();
  } else {
    _startStateWatchdog();  // 根据状态类别选择超时
  }
}

final result = await _codePayIntent.initiatePayment(...)
  .timeout(
    const Duration(minutes: 2),
    onTimeout: () => CodePayResult.failed(
      errorCode: 'INTENT_TIMEOUT',
      errorMessage: 'Payment terminal did not respond within 2 minutes.',
    ),
  );

// pos-manual-confirm（手动确认）
SELECT * FROM payment_requests
  WHERE id = $1 AND status IN ('acknowledged', 'timeout')
  FOR UPDATE;   -- ← 后到的请求在此阻塞

// pos-payment-service._handleSuccessResult（POS 自动确认）
SELECT * FROM payment_requests
  WHERE id = $1 AND status = $2
  FOR UPDATE;   -- ← 同一行只有一个事务能通过

8. Backend 超时保护

除了 POS 端的防护，后端也有独立的超时机制：

8.1 支付请求超时 (5 分钟)

8.2 VOID 请求超时 (5 分钟)

9. 异常场景全景 & 对应防护

10. 超时时间汇总

gantt
    title 超时防护时间线
    dateFormat X
    axisFormat %Ls

    section POS 端
    _scheduleReturnToIdle (终端状态)  :a1, 0, 5
    看门狗-终端状态 (30s)            :a2, 0, 30
    看门狗-交互状态 (5min)           :a3, 0, 300
    看门狗-处理状态 (3min)           :a4, 0, 180
    Intent timeout (2min)            :a5, 0, 120

    section Backend
    POS payment timeout (5min)       :b1, 0, 300
    VOID request timeout (5min)      :b2, 0, 300

    section POS confirm 重试
    第1次 (立即)                     :c1, 0, 1
    第2次 (2s 后)                    :c2, 2, 3
    第3次 (4s 后)                    :c3, 6, 7

11. 恢复与韧性机制 (Recovery & Resilience)

系统在正向流（支付/VOID）的四层防护之外，还提供四条恢复与安全链路，处理"中途断开"和"并发竞争"场景：

完整恢复架构

flowchart TB
    subgraph Disruption["中断场景"]
        D1["Web 页面刷新"]
        D2["POS confirm 失败 (syncFailed)"]
        D3["RefundModal 关闭后重开"]
    end

    subgraph Recovery["恢复机制"]
        R1["GET /pos-request/pending
查询 pending/acknowledged 请求"]
        R2a["Web 手动确认到账 (主要)
POST /pos-manual-confirm"]
        R2b["POS SecureStorage 自动重试 (兜底)
下一笔请求时重试 confirm"]
        R3["GET /refunds/pending
查询 pending/processing 退款"]
    end

    subgraph Result["恢复结果"]
        O1a["恢复进度条 → 等待 POS 响应"]
        O1b["手动确认到账 → 创建 transaction"]
        O2["POS 自动重试 / 拒绝新请求"]
        O3["自动恢复 VOID 等待状态"]
    end

    D1 --> R1 --> O1a
    O1a -. "POS 无响应" .-> O1b
    D2 --> R2a --> O1b
    D2 --> R2b --> O2
    D3 --> R3 --> O3

    style Disruption fill:#2d1b1b,stroke:#f87171,color:#fca5a5
    style Recovery fill:#1b2d1b,stroke:#4ade80,color:#86efac
    style Result fill:#1b1b2d,stroke:#60a5fa,color:#93c5fd

11.1 Web 页面刷新恢复

sequenceDiagram
    participant Web as Web 前端
    participant API as Backend API
    participant WS as WebSocket
    participant POS as POS 终端

    Note over Web: 收银员发起支付
    Web->>API: POST /api/payment/pos-request
    API->>WS: broadcast pos:payment_request
    WS->>POS: pos:payment_request
    POS->>API: POST /pos-accept

    Note over Web: ⚡ 页面刷新 — React 状态全部丢失

    Web->>Web: CheckoutFlow 组件 mount
    Web->>API: GET /pos-request/pending/{appointmentId}
    API-->>Web: { pendingRequest: { id, status, deviceId, orderNumber } }

    alt 有 pending/accepted 请求
        Note over Web: 恢复 posRequestId + showPosProgress + isPosRecovered=true
        Web->>WS: 开始监听 payment:completed / payment:failed
        Note over Web: 显示"已恢复 POS 支付 — 正在等待终端响应"

        alt POS 正常响应
            POS->>API: POST /pos-confirm (success)
            API->>WS: broadcast payment:completed
            WS->>Web: payment:completed
            Note over Web: 正常显示"支付成功"
        else POS 无响应（syncFailed / 设备离线）
            Note over Web: 收银员点击"手动确认到账"
            Note over Web: 输入小费金额
            Web->>API: POST /pos-manual-confirm { requestId, tipAmount }
            API-->>Web: { success, totalPaid }
            Note over Web: 补建 transaction → 显示"支付成功" ✅
        end
    else 无 pending 请求
        Note over Web: 正常状态，不做恢复
    end

11.2 POS syncFailed 持久化恢复

sequenceDiagram
    participant POS as POS 终端
    participant SS as SecureStorage
    participant API as Backend API
    participant CP as CodePay 硬件

    Note over POS, CP: 支付场景 — confirm 失败

    POS->>CP: CodePay Intent (扣款)
    CP-->>POS: 扣款成功 ✅

    POS->>API: POST /pos-confirm (attempt 1) ❌
    POS->>API: POST /pos-confirm (attempt 2, +2s) ❌
    POS->>API: POST /pos-confirm (attempt 3, +4s) ❌

    POS->>SS: saveUnsyncedPayment(JSON)
    Note over SS: 加密持久化到 Android Keystore

    Note over POS: 显示 PaymentSuccess (syncFailed: true)
    Note over POS: 5s → 回到 Idle

    Note over POS: ⏰ 新支付请求到达

    POS->>SS: 读取 unsyncedPayment
    SS-->>POS: JSON payload (上一笔未同步)

    POS->>API: POST /pos-confirm (重试上一笔)
    alt 重试成功
        API-->>POS: 200 OK
        POS->>SS: clearUnsyncedPayment()
        Note over POS: 清除后正常接受新请求
    else 重试仍然失败
        Note over POS: 拒绝新请求，防止双重扣款
        Note over POS: Log CRITICAL 等待人工介入
    end

11.3 VOID Modal 恢复

sequenceDiagram
    participant Web as RefundModal
    participant API as Backend API
    participant WS as WebSocket
    participant POS as POS 终端

    Note over Web: 第一次打开 — 发起 VOID
    Web->>API: POST /refunds/card
    API->>POS: WebSocket pos:void_request
    API-->>Web: { waitingForDevice: true, refundId }
    Note over Web: 显示"等待 POS 终端..."

    Note over Web: ⚡ 用户关闭 Modal — React 状态丢失

    Note over Web: 再次打开 Modal
    Web->>API: GET /refunds/pending/{transactionId}
    API-->>Web: { pendingRefund: { refundId, status: 'pending' } }

    alt 有 pending 退款
        Note over Web: 自动恢复 waitingForDevice 状态
        Web->>WS: 开始监听 void_completed / void_failed

        POS->>API: POST /pos-void-confirm (success)
        API->>WS: broadcast payment:void_completed
        WS->>Web: void_completed
        Note over Web: 正常显示"退款成功" ✅
    else 无 pending 退款
        Note over Web: 正常状态，允许发起新退款
    end

11.4 Web 手动确认到账（syncFailed 主要恢复路径）

sequenceDiagram
    participant Web as Web 前端
    participant API as Backend API
    participant DB as PostgreSQL
    participant WS as WebSocket
    participant POS as POS 终端

    Note over Web: 恢复的 POS 进度条（isPosRecovered=true）
    Note over Web: POS 终端无响应 / 客人已离开

    Web->>Web: 收银员点击"手动确认到账"
    Note over Web: 展开面板 — 输入小费金额（tip 上限 = 税前金额）

    Web->>API: POST /pos-manual-confirm
{ requestId, tipAmount }

    API->>DB: BEGIN TRANSACTION
    API->>DB: SELECT ... FOR UPDATE
(status IN acknowledged, timeout)
    Note over DB: 行级排他锁 — 阻塞并发 pos-confirm
    DB-->>API: payment_request 数据

    Note over API: 验证 tipAmount 小于等于 baseTotal
    Note over API, DB: 1. INSERT transactions（无 CodePay 详情，notes: Manual confirm）
    Note over API, DB: 2. UPDATE payment_requests → completed
    Note over API, DB: 3. UPDATE invoices → paid
    Note over API, DB: 4. syncAppointmentPaymentStatus
    API->>DB: COMMIT

    API->>WS: broadcastToPaymentRequest
payment:completed { manual_confirm: true }
    API->>WS: broadcastToStore
payment:completed { manual_confirm: true }
    WS->>Web: payment:completed
    Note over Web: 显示"支付已手动确认成功"

    API->>WS: emitToPosDevice(SYNC_CLEARED)
    WS->>POS: pos:sync_cleared { request_id, order_id }
    Note over POS: clearUnsyncedPayment() — 清除 SecureStorage

四条恢复链路对比

12. 已知限制 & 未来改进

13. 关键代码文件索引

14. 并发锁机制设计决策 (FOR UPDATE)

本节记录 POS 支付系统中引入 PostgreSQL FOR UPDATE 行级锁的决策过程、技术原理和替代方案对比。

14.1 为什么需要这个机制

14.2 PostgreSQL FOR UPDATE 工作原理

在 PostgreSQL 默认的 READ COMMITTED 隔离级别下：

sequenceDiagram
    participant T1 as 事务 A (先到)
    participant DB as PostgreSQL Row
    participant T2 as 事务 B (后到)

    T1->>DB: SELECT ... FOR UPDATE (status=acknowledged)
    Note over DB: 行被 T1 锁定
    DB-->>T1: 返回 payment_request 数据

    T2->>DB: SELECT ... FOR UPDATE (status=acknowledged)
    Note over DB: T2 在此阻塞等待 T1 释放锁

    Note over T1: INSERT transaction
    Note over T1: UPDATE status → completed
    T1->>DB: COMMIT
    Note over DB: 锁释放 — T2 被唤醒

    Note over T2: 重新读取最新数据
    DB-->>T2: status = completed (非 acknowledged)
    Note over T2: WHERE 条件不匹配 → 0 行返回 → 404

14.3 替代方案对比

14.4 最终设计：双层保护

flowchart LR
    subgraph DB["数据库层（保证）"]
        FORUPDATE["SELECT ... FOR UPDATE
行级排他锁"]
        CHECK["status 检查
不匹配 → 404"]
        FORUPDATE --> CHECK
    end

    subgraph APP["应用层（优化）"]
        CLEARED["SYNC_CLEARED
WebSocket 通知 POS"]
        CLEAR["POS clearUnsyncedPayment
停止重试"]
        CLEARED --> CLEAR
    end

    DB -. "COMMIT 后触发" .-> APP

    style DB fill:#1b2d1b,stroke:#4ade80,color:#86efac
    style APP fill:#1b1b2d,stroke:#60a5fa,color:#93c5fd

14.5 受影响的代码位置