foodie-server/docs/issue-pay-method-switch.md

#661 待支付订单无法更换支付方式

来源：Trello/Bug 单 #661（台湾外卖 ChaChaEat，代码错误，优先级 3，2026-09-18 创建） 记录时间：2026-09-22 状态：后端已实现（POST /pay/switch），待用户端 App 接入

需求

用户选了一个支付方式，支付不成功，返回订单是待支付状态，点击付款按钮时无法更换支付方式。期望：用户可更换支付方式。

根因

订单 payType 在下单时写死（UserOrderController 创建时 setPayType），之后没有任何接口能修改；而两个支付渠道的创建校验各自按 payType 把关：

• OMG（信用卡 2 / Apple Pay 5）：OmgPaymentCreateService 校验 OrderLifecycleService.isCardWalletPayType(order.getPayType())
• LINE Pay（3）：LinePayOrderGuard / LinePayService 校验 payType == 3，且 /pay/line/create 只收 ddId 无方式参数

因此支付失败后只能原路重试。唯一已支持的切换是卡钱包组内 Credit↔ApplePay（/pay/omg/retry 已支持传新方式，但不回写 payType）。

方案

新增统一入口 POST /pay/switch（PayMethodSwitchController → PayMethodSwitchService），入参 orderId + paymentMethod：

1. 校验：订单属于当前用户、主订单（非多门店子单）、state 0-2、payStatus=0、金额有效
2. 方式取值限 1/2/3/4/5（6=线下转账不开放，商家侧流程）；到付(1)/现金(4) 仅自取(type=1)/堂食(type=2)订单可切（与下单现金闸门同规则）
3. 先回写 order.payType（同方式跳过回写），写订单日志「用户更换支付方式：X → Y」
4. 路由拉起支付：2/5 → OmgPaymentCreateService.create；3 → LinePayService.create；1/4 → 无支付环节直接成功
5. 响应：data.payParams 携带渠道支付参数（线下方式为 null，App 刷新订单即可）

顺序约束：必须先回写再拉起——两渠道创建校验都以 order.payType 为闸门。

已知边界（有意为之，非遗漏）：旧渠道未完结的支付尝试不做主动跨渠道关闭，依赖其回调处的 payStatus 守卫（双通道回调只有一个能落账）与既有补偿任务（OMG OmgPaymentAutoCompensationTask、LINE Pay LinePayCancellationCompensationService）收口；极端情形（旧渠道回调晚到且已付款）走对账/退款流程。后续如需主动关闭，可在回写前接入两渠道的取消/作废能力。

改动文件

文件	改动
com.ruoyi.app.pay.PayMethodSwitchController	新增 /pay/switch 入口
com.ruoyi.app.pay.PayMethodSwitchService	新增切换/校验/路由逻辑
com.ruoyi.app.pay.dto.PayMethodSwitchRequest	新增请求 DTO
i18n ×6（messages / vi / en_US / th_TH / zh_CN / zh_TW）	新增 no.pay.switch.* 5 个 key
PayMethodSwitchServiceTest	新增 8 个用例

原渠道接口（/pay/omg/create、/pay/omg/retry、/pay/line/create）与下单流程零改动。

验证

• PayMethodSwitchServiceTest：线下切换回写+日志+跳过支付、外送单拒线下、跨渠道先回写后拉起（InOrder）、同方式不重复回写、已支付/非法方式/非本人单/多门店子单拒绝
• 全量回归：除既有已知红测试 createRejectsUnsupportedPayType（payType 白名单停用基线，另行处理）外全部通过

待办

• 用户端 App：付款按钮增加「更换支付方式」选择，调 POST /pay/switch
• 上线后观察双渠道回调日志，确认无重复落账