# API Contracts: 可配置支付方式（031-pay-method-config）

**Date**: 2026-09-11 | **Spec**: [spec.md](spec.md) | **Data Model**: [data-model.md](data-model.md)

所有接口遵守项目 Controller 规范：token 用 `@RequestHeader String token`，POST 业务参数用 `@RequestBody` DTO，GET 查询参数逐个 `@RequestParam`；DTO 字段不加 Bean Validation 注解，校验在 Service，错误信息走 `MessageUtils.message`。

## 0. 核心内部契约：PaymentMethodGateService（ruoyi-system）

单一校验入口，**唯一**闸门实现（spec FR-004）。

```java
/** 校验支付方式可用，不可用抛 ServiceException(国际化)；三下单入口统一下单时调用。 */
void assertUsable(String payType, GateScope scope, Long payeeUserId)

/** 列出某维度对收款方可用的支付方式（结算页可选项、骑手列表过滤共用）。 */
List<PayMethodOption> listAvailable(GateScope scope, Long payeeUserId)

enum GateScope { MERCHANT, RIDER_FLASH }
```

调用点（**仅此三处 + bankInfo 一处**，禁止新增重复实现）：

| 调用方 | 位置 | 参数 |
|---|---|---|
| 用户餐饮下单 | `UserOrderController.createOrder`（setPayType 前后） | payType=input.paymentMethod, MERCHANT, 商家主账号 userId |
| 商家建单 | `PosOrderController /addorder` | payType 固定 "1"(COD), MERCHANT —— COD 默认开，校验保持对称 |
| 闪送下单 | `FlashDeliveryApplicationService.create`（normalizePayType 处） | payType, RIDER_FLASH, 无收款方（抢单前，只校验平台开关） |
| 027 bankInfo | `ChantingStoreController.bankInfo` | OFFLINE_TRANSFER, MERCHANT, 商家 userId |

错误 key（6 语言文件全配）：`pay.method.not.available`（该支付方式当前不可用，请更换支付方式）。

## 1. 平台端（foodie-admin-vue，权限 `pay:method:config`，操作记 @Log）

### 1.1 查询开关矩阵

```
GET /system/payMethodConfig/list
```

返回：方式×维度全矩阵（含缺行按"开"补齐的虚拟行），每项 `{methodCode, methodName(i18n key), scope, enabled, sort}`。

### 1.2 保存开关

```
PUT /system/payMethodConfig
Body: { items: [ { methodCode, scope, enabled } ] }
```

批量 upsert；`@Log(title="支付方式设置")`；`@PreAuthorize("@ss.hasPermi('pay:method:config')")`。

## 2. 商家端 PC（foodie-store，token = 商家主账号/子账号）

### 2.1 支付方式设置页数据

```
GET /system/merchantPayMethods
```

返回：`{ available: [ {methodCode, methodName, ready} ], selected: ["COD", ...] }`——available = 平台商家维度开放集合（附就绪度标记），selected = 商家当前选择（NULL 视为全部，返回时展开为全部可用项）。

### 2.2 保存选择

```
PUT /system/merchantPayMethods
Body: { methodCodes: ["COD", "CARD_OMG"] }   // 空数组=清空=回落全部
```

写 `info_user.pay_methods`（主账号行；子账号可编辑，写其主账号——与 022 子账号权限体系一致）。

### 2.3 银行卡管理（商家/骑手通用）

```
GET    /system/bankCard                    // 本人卡列表（含启用标记）
POST   /system/bankCard                    // 新增 {bankName, accountNo, accountName}
PUT    /system/bankCard                    // 修改 {id, bankName, accountNo, accountName}
DELETE /system/bankCard/{id}               // 删除（启用卡删除后无启用卡→线下转账不就绪）
PUT    /system/bankCard/activate/{id}      // 启用某卡（同事务停旧卡）
```

校验：bankName ∈ 字典 `taiwan_bank_list`；条数上限 10；只能操作本人卡。

## 3. 骑手端（骑手 App 接口，本期无前端）

```
GET /system/riderFlashPayMethods           // 返回同 2.1 结构（scope=RIDER_FLASH）
PUT /system/riderFlashPayMethods           // { methodCodes: [...] }，空=回落全部
```

写入 `info_user.flash_pay_methods`；要求 token userType=2。

## 4. 闪送（FlashDelivery 现有接口的增量）

- **报价/下单**：`FlashDeliveryQuoteRequest` / `FlashDeliveryCreateRequest` 增加可选 `payType`；下单时经闸门校验（RIDER_FLASH，仅平台开关层）；缺省=现金 4（现状不变）。
- **用户端可见性**：报价响应/首页返回闪送维度可选支付方式列表（`listAvailable(RIDER_FLASH, null)`）。
- **骑手抢单列表**：现有查询追加过滤——订单 payType ∈ 骑手接受集合（flash_pay_methods NULL=全部开放项）。`pickupDistanceMeters` 等既有行为不变。
- **骑手确认收款**（新）：

```
POST /system/flashDelivery/rider/orders/{id}/confirmPayment
```

条件：本人中单 + 状态已达已送达或之后；效果：payment_status 0→1 + 日志（RIDER）；幂等：已确认再调返回成功。

## 5. 027 兼容改造

`GET /chanting/store/bankInfo?id={storeId}` —— **路径、匿名、返回结构（bankAccountName/bankName/bankAccountNo 三字段或 data=null）完全不变**：

- 数据源：info_user 三字段 → `info_bank_card` 该商家 is_active=1 的卡
- 可见性：原"data != null 才显示"→ 闸门（OFFLINE_TRANSFER 平台开 ∩ 商家接受 ∩ 存在启用卡）不满足时返回 data=null，老客户端自然隐藏
- 老客户端提交线下转账下单（paymentMethod=6）被闸门拒绝 → 国际化提示（FR-004 兜底）

## 6. i18n

后端 `messages*.properties` ×6：`pay.method.not.available`、银行卡校验类 key（`pay.bankcard.*`）。前端：admin-vue 支付方式设置页、foodie-store 支付设置页全部 key 四语言（vi/zh/tw/en），命名驼峰有意义（项目规范）。