|
|
@@ -0,0 +1,114 @@
|
|
|
+# 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），命名驼峰有意义（项目规范）。
|
qmj