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

Date: 2026-09-11 | Spec: spec.md | Data Model: 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）。

/** 校验支付方式可用，不可用抛 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（该支付方式当前不可用，请更换支付方式）。

0.1 现金（CASH，payType=4）闸门增量（2026-09-20 变更，spec US7/FR-006）

现金不设平台开关行、无就绪度，闸门判定需要订单类型上下文：

/** 带订单类型的校验重载：用户餐饮下单调用；其余入口沿用原签名（商家建单/闪送现金按现状放行）。 */
void assertUsableForOrder(String payType, GateScope scope, Long storeId, Long payeeUserId, Long orderType)

payType=4：orderType∈{1自取,2堂食} → 仅查商家勾选（info_user.pay_methods 含 CASH，或 NULL=全部接受）→ 通过；orderType=0外送 → 拒绝（pay.method.not.available）；orderType=null（商家建单/闪送）→ 放行（现状）。
商家勾选保存（§2.2）值域校验 groupsOf(MERCHANT) 扩展含 CASH；allGroups()（平台矩阵）不含 CASH。
结算页 §7 listAvailable 增加可选 orderType 入参：type∈{1,2} 且商家接受时追加 {methodCode:"CASH", payType:"4", ready:true}；orderType 缺省不追加（老客户端零变化）。

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 = 平台商家维度开放集合（附就绪度标记）追加 CASH 项（2026-09-20 变更：无平台开关、ready 恒 true，是否可用由商家勾选决定），selected = 商家当前选择（NULL 视为全部，返回时展开为全部可用项含 CASH）。

2.2 保存选择

PUT /system/merchantPayMethods
Body: { methodCodes: ["COD", "CARD_OMG"] }   // 空数组=清空=回落全部；值域含 "CASH"（2026-09-20 变更）

写 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），命名驼峰有意义（项目规范）。

7. 用户端结算页可用支付方式（App 渲染依据）

GET /system/storePayMethods?storeId={storeId}&type={type}    // type 可选（2026-09-20 变更）：1自取/2堂食

鉴权：匿名（@Anonymous，同 bankInfo 风格）；App 结算页进入时调用，按返回渲染支付方式列表。
逻辑：pos_store.id → user_id（商家主账号）→ listAvailable(MERCHANT, 主账号, orderType)。
返回：data: [ { methodCode, payType, ready } ]——methodCode 组代码 / payType 对应数值（CARD_OMG 展开 2 与 5 两项）/ ready 就绪度。线下转账 ready=false 时不渲染（替代 027 时代"bankInfo!=null 才显示"的判断，App 可统一按本接口渲染）。
现金项（2026-09-20 变更）：type=1 或 2 且商家接受现金（勾选含 CASH 或未设置）时，追加 {methodCode:"CASH", payType:"4", ready:true}；type=0 外送 或不传 type 不返回现金（老客户端零变化）。
与 bankInfo 关系：本接口管"选项显隐"，bankInfo 仍管"转账信息内容"（结构不变，第 5 节）。
现金下单语义：现金仅接受 type∈{1,2}；订单创建后 payStatus 置 1（同到付线下收款语义，直接进入"进行中"，不经"待付款"）；type=0 直传现金被闸门拒绝（pay.method.not.available）。

api.md 8.0 KB History Raw