用户支付

1. 微信支付流程

说明： 用户在收银台选择微信支付后，系统创建支付单并调起微信客户端或 JSAPI 完成支付；支付成功后由微信异步通知商户服务端，系统验签并驱动订单进入已支付状态。

参与角色： 用户、VortMall 支付服务、微信支付平台、订单服务。

sequenceDiagram
    participant user as 用户
    participant app as 客户端或H5
    participant pay as 支付服务
    participant wx as 微信支付
    participant order as 订单服务
    user->>app: 选择微信支付并确认
    app->>pay: 请求预支付或下单参数
    pay->>wx: 统一下单获取预支付信息
    wx-->>pay: 返回预支付参数
    pay-->>app: 返回调起参数
    app->>wx: 调起微信支付SDK完成支付
    wx-->>user: 展示支付结果
    wx->>pay: 异步回调通知支付结果
    pay->>pay: 验签并解析结果
    pay->>order: 触发订单确认链路
    order-->>user: 订单状态更新可查询

步骤说明：

1. 用户在订单待支付页选择「微信支付」并提交。
2. 支付服务根据订单金额、商户号等生成支付请求，调用微信统一下单接口。
3. 微信返回预支付会话标识等，支付服务封装为客户端可调起的参数并返回前端。
4. 客户端调起微信 SDK（App、小程序或 JSAPI），用户在微信内完成密码或生物识别支付。
5. 用户侧展示支付成功或失败后，以服务端异步通知为准；微信向商户配置的 notify_url 发送支付结果。
6. 支付服务对回调报文验签，确认订单号、金额、交易状态一致后，进入「支付回调与订单同步」统一流程（见第 6 节）。
7. 订单服务将对应订单从待支付推进为已确认（或业务约定的已支付态），用户可在订单详情查看结果。

特别说明：

• 同一笔商户订单号应对应唯一支付流水；重复回调应幂等处理。
• 客户端展示的「成功」若与服务端未收到回调不一致，以服务端状态与后续补偿为准。

---

2. 支付宝支付流程

说明： 用户选择支付宝后，系统生成支付宝交易请求并调起支付宝 App 或手机网站收银台；用户完成支付后，支付宝通过异步通知告知商户，系统验签后更新业务状态。

参与角色： 用户、VortMall 支付服务、支付宝开放平台、订单服务。

sequenceDiagram
    participant user as 用户
    participant app as 客户端或H5
    participant pay as 支付服务
    participant ali as 支付宝
    participant order as 订单服务
    user->>app: 选择支付宝并确认
    app->>pay: 请求创建支付宝交易
    pay->>ali: 下单或获取唤起参数
    ali-->>pay: 返回orderStr或表单
    pay-->>app: 返回调起参数
    app->>ali: 调起支付宝SDK或跳转收银台
    ali-->>user: 完成支付授权
    ali->>pay: 异步通知trade_status
    pay->>pay: 验签与业务校验
    pay->>order: 同步订单支付结果

步骤说明：

1. 用户在收银台选择「支付宝」并确认支付金额与订单信息。
2. 支付服务调用支付宝下单接口，传入商户订单号、金额、回调地址等。
3. 支付宝返回可唤起交易的字符串或手机网站表单，前端调起支付宝客户端或跳转 H5 收银台。
4. 用户在支付宝内完成付款或取消；页面可同步跳转回商户，但最终以异步通知为准。
5. 支付宝向商户 notify_url 发送交易状态；支付服务使用平台公钥验签。
6. 校验商户订单号、金额、交易成功状态后，进入统一回调处理，驱动订单确认。
7. 用户返回商户端时可拉取最新订单状态展示。

特别说明：

• 需同时处理同步 return_url 与异步 notify，业务上以 notify 为确权依据。
• 部分场景存在延迟通知，应允许用户稍后刷新订单状态。

---

3. PayPal 支付流程（跨境版）

说明： 【overseas 版】海外用户选择 PayPal 时，订单与展示币种可能经汇率转换为 PayPal 结算币种；支付完成后由 PayPal Webhook 或回调通知商户，系统按原订单币种记账并更新状态。

参与角色： 海外用户、VortMall 支付服务、PayPal、汇率与配置服务、订单服务。

sequenceDiagram
    participant user as 海外用户
    participant app as 客户端
    participant pay as 支付服务
    participant fx as 汇率服务
    participant pp as PayPal
    participant order as 订单服务
    user->>app: 选择PayPal支付
    app->>pay: 创建PayPal订单请求
    pay->>fx: 获取展示币种与汇率快照
    fx-->>pay: 汇率与金额明细
    pay->>pp: 创建PayPal订单或授权
    pp-->>pay: approve链接或token
    pay-->>app: 跳转或内嵌收银台
    user->>pp: 在PayPal完成付款
    pp->>pay: 回调或Webhook capture完成
    pay->>pay: 验签与金额币种核对
    pay->>order: 按订单币种确认收款

步骤说明：

1. 用户在国家或站点配置为海外业态时，收银台展示 PayPal 作为可选渠道。
2. 支付服务读取订单记账币种与应付金额，根据策略决定是否向用户展示外币金额。
3. 若涉及汇率转换，调用汇率服务获取快照并写入支付单，避免后续争议。
4. 调用 PayPal Orders/Capture 相关接口创建或批准支付，引导用户至 PayPal 完成授权与扣款。
5. PayPal 异步通知 capture 成功；支付服务验证 Webhook 签名与资源 ID。
6. 将 PayPal 实际清算金额与订单应付进行容差比对（按业务规则处理币种与舍入）。
7. 通过后进入统一订单同步流程，订单以平台记账币种记录实收。

特别说明：

• overseas 版需单独配置 PayPal ClientId、WebhookId 及合法回调 URL。
• 汇率快照应可追溯；退款时按原支付流水与原币种规则执行。

---

4. 余额支付流程

说明： 用户使用预充值或平台发放的账户余额直接抵扣订单应付金额，扣款在系统内原子完成，不经过第三方支付渠道。

参与角色： 用户、VortMall 支付服务、账户余额服务、订单服务。

flowchart TD
    startNode([用户选择余额支付])
    checkBal{余额是否充足}
    lockOrder[锁定订单或支付单]
    deduct[扣减可用余额]
    recordPay[写入余额支付流水]
    syncOrder[通知订单服务确认收款]
    failMsg[提示余额不足]
    startNode --> checkBal
    checkBal -->|否| failMsg
    checkBal -->|是| lockOrder
    lockOrder --> deduct
    deduct --> recordPay
    recordPay --> syncOrder

步骤说明：

1. 用户在收银台选择「账户余额」并确认订单金额。
2. 系统查询用户可用余额，与应付金额比较；不足则拒绝并提示充值或其他支付方式。
3. 在事务或等价一致性保障下，对订单或支付单加锁，防止并发重复支付。
4. 扣减用户可用余额，增加冻结或已消费明细（按账户模型实现）。
5. 写入支付流水，渠道标记为余额，状态为成功。
6. 调用订单服务将订单从待支付更新为已确认，释放库存占用等业务逻辑与线上一致。
7. 前端展示支付成功与余额变动。

特别说明：

• 扣款失败或订单更新失败时须回滚余额扣减，或进入补偿任务，保证账务一致。
• 余额支付无外部回调，不依赖第 6 节的外部验签路径，但订单状态机应与线上一致。

---

5. 混合支付流程

说明： 单笔订单应付拆分为「余额抵扣部分」与「在线支付部分」；先完成余额扣减与登记，再对剩余金额发起微信或支付宝等渠道支付，两段均成功才视为整单支付完成。

参与角色： 用户、VortMall 支付服务、账户余额服务、第三方支付、订单服务。

flowchart TD
    startNode([用户选择混合支付])
    splitAmt[计算余额扣减额与线上应付额]
    balPart{余额部分大于0}
    deductBal[扣减余额并记余额流水]
    skipBal[跳过余额段]
    chooseCh[用户选择微信或支付宝]
    invokeOnline[发起线上支付调起SDK]
    waitCb[等待渠道异步回调]
    mergeState[合并支付单状态]
    doneNode([订单确认或失败回滚])
    startNode --> splitAmt
    splitAmt --> balPart
    balPart -->|是| deductBal
    balPart -->|否| skipBal
    deductBal --> chooseCh
    skipBal --> chooseCh
    chooseCh --> invokeOnline
    invokeOnline --> waitCb
    waitCb --> mergeState
    mergeState --> doneNode

步骤说明：

1. 用户勾选使用账户余额，并输入或确认使用金额（不得超过可用余额与应付上限）。
2. 系统拆分：余额支付额 = min(可用余额, 应付总额)，线上应付 = 应付总额 − 余额支付额。
3. 若余额部分大于零，先执行余额扣减与余额支付流水，状态为「混合单中的余额段成功」。
4. 若线上应付大于零，展示微信或支付宝等选项；用户选择后按第 1 或第 2 节流程调起渠道。
5. 渠道支付成功后，异步回调与订单同步逻辑识别本单为混合支付，合并渠道流水与余额流水。
6. 两段均成功时，订单置为已支付；任一段失败则按规则回滚已扣余额或关闭渠道单。
7. 用户端展示组合支付明细（余额 + 渠道）。

特别说明：

• 顺序上建议「先余额后渠道」，避免渠道已付而余额扣减失败导致复杂冲正。
• 混合支付单号、子流水号应可追溯，便于对账与客服查询。

---

6. 支付回调与订单同步流程

说明： 第三方支付异步回调进入系统后，先验签与业务校验，再先通知订单服务将订单从 PENDING 推进为 CONFIRMED；仅当订单侧成功后，才将支付日志更新为已支付。若订单侧失败，支付日志保持未成功状态，依赖渠道重试回调直至一致。

参与角色： 支付渠道、VortMall 支付服务、订单服务、支付日志存储。

flowchart TD
    recvNode([接收渠道回调])
    verifySig{验签与参数校验}
    rejectRsp[返回失败或非法]
    idemCheck{幂等是否已处理}
    ackOk[直接返回成功]
    notifyOrder[先调用订单服务确认支付]
    orderOk{订单更新是否成功}
    updateLog[更新支付日志为成功]
    keepPending[支付日志保持待支付]
    retryLater[等待渠道重试回调]
    recvNode --> verifySig
    verifySig -->|否| rejectRsp
    verifySig -->|是| idemCheck
    idemCheck -->|已处理| ackOk
    idemCheck -->|未处理| notifyOrder
    notifyOrder --> orderOk
    orderOk -->|是| updateLog
    orderOk -->|否| keepPending
    keepPending --> retryLater
    updateLog --> ackOk

步骤说明：

1. 支付服务接收 HTTPS POST 回调报文，记录原始请求便于审计。
2. 使用渠道公钥或对称密钥完成验签，校验商户订单号、金额、币种、交易状态。
3. 幂等判断：若该支付单已成功且订单已确认，直接返回渠道成功响应，避免重复记账。
4. 先调用订单领域服务：在一致的业务规则下将订单从 PENDING 转为 CONFIRMED（或等价已支付态），并处理库存、营销等副作用。
5. 若订单更新成功，再更新支付日志为成功，并关联渠道交易号、完成时间。
6. 若订单更新失败（网络超时、业务拒绝、临时故障），不将支付日志标为成功，响应可按渠道要求返回成功或重试语义，依赖渠道后续重复通知。
7. 补偿：定时任务扫描「渠道已成功、订单未确认」的异常单，人工或自动重试订单确认。

特别说明：

• 关键设计：先订单后支付日志，避免「日志已付、订单仍挂起」且无法感知的不一致。
• 应对重复回调：以支付单号 + 渠道交易号为幂等键。

---

7. 支付对账流程

说明： 系统持续维护支付与退款日志，按日或按账期从第三方平台下载对账文件或与 API 核对，识别长款、短款、状态不一致等差异并进入异常处理闭环。

参与角色： 对账任务调度、VortMall 支付与退款日志、第三方支付平台、财务或运营。

flowchart TD
    startNode([触发对账周期])
    exportLocal[导出本侧支付与退款流水]
    fetchBill[拉取渠道对账单或批量查询]
    matchRows[按商户订单号与金额匹配]
    diffScan{是否存在差异}
    diffType{差异类型}
    markOk[标记已对账一致]
    exLong[长款：渠道有付本侧无或状态异常]
    exShort[短款：本侧成功渠道无]
    exAmt[金额或币种不一致]
    ticket[生成异常工单与调账待办]
    retrySettle[重试回调或补单]
    finishNode([对账报告归档])
    startNode --> exportLocal
    exportLocal --> fetchBill
    fetchBill --> matchRows
    matchRows --> diffScan
    diffScan -->|否| markOk
    diffScan -->|是| diffType
    diffType -->|长款| exLong
    diffType -->|短款| exShort
    diffType -->|金额或币种| exAmt
    exLong --> ticket
    exShort --> ticket
    exAmt --> ticket
    ticket --> retrySettle
    markOk --> finishNode
    retrySettle --> finishNode

步骤说明：

1. 定时任务（如每日凌晨）触发对账作业，指定账期与渠道。
2. 从本库导出该账期内所有成功、退款中、已退款的支付与退款流水。
3. 从微信、支付宝、PayPal 等获取对账单文件或调用批量查询接口。
4. 以商户订单号、渠道交易号、金额、币种、交易类型为键进行逐笔匹配。
5. 完全一致则标记对账成功，生成汇总统计供财务下载。
6. 发现渠道有收本侧无或状态未闭环，判为长款风险，触发补单或人工核实。
7. 发现本侧已成功渠道无记录，判为短款或伪造风险，触发紧急核查与风控。
8. 金额不一致时冻结相关退款或调账流程，直至查明原因。
9. 异常处理完成后更新对账状态与结案说明，保留审计轨迹。

特别说明：

• 对账文件应加密存储，访问权限限于财务与系统任务账号。
• 与第 6 节配合：回调丢失导致的差异应能被对账任务发现并重试订单确认。