# #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`
- [ ] 上线后观察双渠道回调日志，确认无重复落账