Implementation Plan: 可配置支付方式（031-pay-method-config）

Branch: test-202609v2（直接开发，不建 feature 分支） | Date: 2026-09-11 | Spec: spec.md

Input: Feature specification from /specs/031-pay-method-config/spec.md

Summary

支付方式可用性从代码固定行为改为三层闸门：平台开关（方式×维度，新表 payment_method_config，缺行=开）∩ 收款方选择（info_user.pay_methods / flash_pay_methods，NULL=全部）∩ 就绪度（凭证/启用卡）。核心是 ruoyi-system 的 PaymentMethodGateService 单一校验入口，用户餐饮下单、商家建单、闪送下单、027 bankInfo 四处统一调用，顺带堵掉 createOrder 不校验 payType 的漏洞。银行卡从 027 三字段列表化为 info_bank_card（多卡单启用，存量 INSERT...SELECT 迁移），闪送订单复用 pay_type 列并新增 payment_status（骑手确认收款，不阻塞流程）。前端两页：admin-vue 平台开关矩阵页、foodie-store 商家支付设置页（勾选+银行卡管理），均四语言。

Technical Context

Language/Version: Java 21（后端）；Vue2 + Element UI（两前端）

Primary Dependencies: Spring Boot、MyBatis-Plus、vue-i18n（foodie-store）；httpclient4+fastjson2（不涉及新外部调用）

Storage: MySQL（2 张新表 + 3 处加列，DDL 全部入 updatesql/sql.md 手动执行）

Testing: JUnit5 + Mockito（后端单测）；SQL 只读冒烟用 pymysql 直连测试库

Target Platform: Linux 服务端（Spring Boot）+ 两个管理前端（Windows 开发）

Project Type: web-service（多模块 Maven + 两前端仓库）

Performance Goals: 开关读取走字典式缓存（同 DictUtils 模式），结算页/下单路径不新增可感知延迟；保存开关后下一次查询即生效

Constraints: 模块依赖 ruoyi-admin → ruoyi-system 单向；闸门服务放 ruoyi-system；Controller 规范（@RequestHeader/@RequestBody DTO/@RequestParam，DTO 无 Bean Validation）；前端 CRLF 用 Python 编辑；Java 注释禁 */

Scale/Scope: 后端 2 新表 + 3 加列 + 1 新服务 + 6 组新接口 + 3 入口接入；前端 2 新页面；迁移 1 条 SQL；i18n 后端 6 文件 + 前端 4 文件

Constitution Check

.specify/memory/constitution.md 为未填充模板占位，无已批准的项目原则约束 → GATE: PASS（无适用条款）。项目实际约束以 CLAUDE.md（模块边界/Controller 规范/i18n/DDL 流程）为准，已并入 Technical Context Constraints。

Project Structure

Documentation (this feature)

specs/031-pay-method-config/
├── plan.md              # 本文件
├── research.md          # 代码现状核对（含行号锚点）与 15 项既定决策
├── data-model.md        # 表结构/迁移/就绪度判定
├── quickstart.md        # 验证场景（对照 SC-001~006）
├── contracts/api.md     # 接口契约（含闸门服务内部契约与三入口调用点）
├── checklists/requirements.md
└── tasks.md             # /speckit-tasks 生成（待）

Source Code (repository root)

ruoyi-system/src/main/java/com/ruoyi/system/
├── domain/PaymentMethodConfig.java            # 新：平台开关
├── domain/InfoBankCard.java                   # 新：银行卡
├── domain/InfoUser.java                       # 加 payMethods/flashPayMethods
├── domain/flash/FlashDeliveryOrder.java       # 加 paymentStatus
├── mapper/PaymentMethodConfigMapper.java      # 新
├── mapper/InfoBankCardMapper.java             # 新
└── service/PaymentMethodGateService.java      # 新：单一闸门入口(assertUsable/listAvailable)

ruoyi-admin/src/main/java/com/ruoyi/app/
├── pay/PayMethodConfigController.java         # 新：平台开关(list/put)
├── pay/BankCardController.java                # 新：银行卡 CRUD+启用
├── user/... MerchantPayMethodController.java  # 新：商家选择(get/put)
├── qs(RiderFlashPayMethodController).java     # 新：骑手闪送方式(get/put)
├── order/UserOrderController.java             # 改:createOrder 接闸门(:261)
├── order/PosOrderController.java              # 改:/addorder 接闸门(COD对称校验)
├── chanting/... bankInfo 数据源改 info_bank_card + 套闸门
└── flashdelivery/service/FlashDeliveryApplicationService.java  # 改:normalizePayType→闸门;抢单过滤;confirmPayment

E:\QtwCode\foodie\foodie-admin-vue\src\views\pay\methodConfig\   # 新:平台开关矩阵页
E:\QtwCode\foodie\foodie-store\src\views\PayMethodSettings.vue   # 新:商家支付设置页(参照SelfDeliverySettings.vue)
+ 两前端路由/菜单/i18n(四语言)

Structure Decision: 闸门与凭证/卡读取同层（ruoyi-system），Controller 全在 ruoyi-admin；前端独立仓库各一页。pay 包为新建（现有 chanting/store 等包无支付方式配置归属）。

Complexity Tracking

无 Constitution 违规需要豁免。设计保持在"1 服务 + 2 表 + 2 页"最小面：平台开关用结构化表而非逐 key sys_config（矩阵+排序+唯一约束，已决策）；不引入规则引擎、不做逐店覆盖、不做 App 端页面。

变更记录

2026-10-09 商家支付方式备注（US9）：payment_method_config.remark VARCHAR(500) NULL，仅 MERCHANT 使用。MyBatis-Plus BaseMapper 自动映射，无自定义 XML。Entity/平台保存 DTO/平台读写接口增加备注及长度、维度校验；省略/null 保留，空字符串清空。闸门服务增加独立 listMerchantRemarks()，商家设置 GET 返回 remarks（组代码→非空文本），不修改共用 PayMethodOption，保证骑手/用户结算接口不增加说明字段。平台页可编辑，商家/摊位页只读普通插值展示并保留换行，两端新增固定文案四语言。SQL 只写 updatesql/sql.md，部署前开发者执行。验证配置读写、清空/兼容旧请求、长度/维度隔离、摊位一致性及前端 payload/渲染。
2026-09-30 夜市摊位支付设置（US8）：普通商家继续使用 info_user.pay_methods 与用户归属银行卡；摊位新增 pos_store.pay_methods（NULL=全部）和 info_bank_card.store_id（摊位卡，user_id 为空）。摊位主仅凭有效登录账号的 store_id 解析摊位，校验账号启用、未删除、摊位未删除且 is_stall=1；夜市主无摊位设置权限。闸门在 MERCHANT 维度根据 store_id 判断摊位归属，支付方式选择和线下转账就绪度分别读摊位字段和摊位启用卡；bankInfo 同一归属规则。商家端复用支付设置页并向摊位主显示菜单。通用门店/摊位 JSON 不可改 payMethods 和 isStall，editStall 校验夜市主归属并固定支付路由字段。摊位卡新增和启用在事务内先以 pos_store 行锁串行化，避免多位摊位主并发产生两张首启用卡。SQL 仅登记在 updatesql/sql.md，由开发者手工执行后再部署代码。验证：访问隔离、同摊位共享、跨摊位隔离、结算/下单闸门与 bankInfo，并回归普通商家和骑手。
2026-09-20 自取/堂食现金支付（spec US7）：现金（payType=4）从"完全不管控、仅商家建单"调整为"纳入商家勾选（info_user.pay_methods 新增 CASH 组）、仍无平台开关与就绪度"；可用场景扩展到用户自取/堂食下单（外送单直传现金被闸门拒绝）。闸门新增带 orderType 上下文的 assertUsableForOrder 重载，原四处调用点行为不变。无 DDL。任务见 tasks.md Phase 10（T026-T030）。
2026-09-28 商家PC联调修复与 DDL 补登记：商家端联调暴露四项问题当日修复——①foodie-store 侧边菜单缺「支付设置」入口（T031）；②未配置商家（NULL）展示为全不勾，改为默认全选展示对齐「NULL=接受全部」口径（T032）；③银行名称下拉误调不存在的 /system/bankList，改调 /infouser/user/bankList（T033）；④保存 SQL 写入 info_user 不存在的 update_time 列致 Unknown column，商家/骑手两处移除（T034）。同日补登记 031 全套 DDL 至 updatesql/sql.md（原误只写在 data-model.md 从未入库，已执行测试库并完成 027 存量卡迁移）；清理 6 文件 17 处无效 @Auth(session=true) 标注（947867e）。部署链提醒：商家PC 测试站须以 .env.test 构建（曾误用生产 API 基址 api.awayqtw.com 导致 401 与行为漂移）。
2026-10-10 骑手 LINE Pay：PaymentMethodGateService 在 RIDER_FLASH 且 payeeUserId 已知时读取 IInfoRiderLinePayService.getEnabledCurrent；用户未确定骑手仍服从平台开关。待抢列表复用 listAvailable，接单新增同闸门 assertUsable，金额/收款人与凭证由 019 流程在服务端确定。新增凭证/SQL/UI由 019 管理，031 不新增字段或 App 改动，现金转账及商家就绪规则回归。

plan.md 8.9 KB История Исходник