支付功能开启

支付模块用于把业务订单、钱包充值、退款、转账等动作统一收敛到 yudao-module-pay。在 RuoYi Office 中，它不是一个孤立的“支付示例”，而是商城、会员钱包、合同收款等业务接入第三方支付渠道的公共能力。

本页按本仓库当前实现说明如何开启支付、配置应用与渠道、验证回调链路，并列出上线前必须检查的任务和安全项。

适用范围

项目	当前实现
后端模块	ruoyi-office/yudao-module-pay
单体引入位置	ruoyi-office/yudao-server/pom.xml 中的 yudao-module-pay-server
管理端页面	ruoyi-office-vben/apps/web-antd/src/views/pay
管理端 API	ruoyi-office-vben/apps/web-antd/src/api/pay
主要接口前缀	/admin-api/pay/app、/admin-api/pay/channel、/admin-api/pay/order、/admin-api/pay/refund

功能链路

支付模块建议按“先跑通模拟支付，再配置真实渠道”的顺序落地。模拟支付用于验证订单、回调、业务单状态联动；真实渠道再补齐证书、密钥和公网回调地址。

第一步：确认模块已启用

单体工程默认已经在聚合工程和启动工程中引入 Pay 模块：

<!-- ruoyi-office/pom.xml -->
<module>yudao-module-pay</module>

<!-- ruoyi-office/yudao-server/pom.xml -->
<dependency>
  <groupId>cn.iocoder.cloud</groupId>
  <artifactId>yudao-module-pay-server</artifactId>
  <version>${revision}</version>
</dependency>

如果你裁剪过模块，至少要确认：

1. yudao-module-pay 仍在根 pom.xml 聚合中。
2. yudao-server 已依赖 yudao-module-pay-server。
3. 菜单、权限和支付相关表已导入数据库。
4. 后端启动后 Knife4j / OpenAPI 中可以看到 管理后台 - 支付应用信息、管理后台 - 支付渠道 等接口。

第二步：配置支付应用

管理端入口通常在「支付管理 -> 支付应用」。页面实现位于：

• apps/web-antd/src/views/pay/app/index.vue
• apps/web-antd/src/views/pay/app/modules/app-form.vue
• apps/web-antd/src/views/pay/app/modules/channel-form.vue

应用用于区分业务来源，例如商城订单、会员钱包、合同收款可使用不同应用。后端接口由 PayAppController 提供，常用动作如下：

动作	接口	权限标识
创建应用	POST /pay/app/create	pay:app:create
更新应用	PUT /pay/app/update	pay:app:update
启停应用	PUT /pay/app/update-status	pay:app:update
应用分页	GET /pay/app/page	pay:app:query

应用创建后，列表会展示各支付渠道的配置状态。绿色/勾选表示该应用下已经配置并启用对应渠道；点击渠道按钮会打开渠道配置弹窗。

第三步：配置支付渠道

渠道配置保存在 pay_channel，接口由 PayChannelController 提供。管理端弹窗会根据渠道编码生成不同的配置字段。

渠道类型	编码示例	关键配置
支付宝	alipay_pc、alipay_wap、alipay_app、alipay_qr、alipay_bar	应用 ID、网关地址、签名方式、应用私钥、支付宝公钥/证书、加密配置
微信支付	wx_pub、wx_lite、wx_app、wx_native、wx_wap、wx_bar	AppId、商户号、API 版本、商户密钥、证书、API v3 Key、平台公钥
钱包支付	wallet	本地钱包扣款配置
模拟支付	mock	开发联调配置

建议先启用 mock 渠道完成闭环验证：

1. 新建或选择一个支付应用。
2. 点击 mock 渠道配置按钮。
3. 保持启用状态，保存渠道。
4. 到「支付示例订单」或业务订单中发起支付。
5. 检查支付订单、支付通知和业务订单状态是否同步变化。

第四步：配置回调地址和定时任务

真实支付上线必须保证第三方平台能访问回调地址。Pay 模块在回调、补偿和同步上依赖以下任务：

任务 Handler	类路径	作用
payNotifyJob	job/notify/PayNotifyJob.java	将支付、退款等结果补偿通知到业务系统
payOrderExpireJob	job/order/PayOrderExpireJob.java	关闭超时未支付订单
payOrderSyncJob	job/order/PayOrderSyncJob.java	主动同步支付订单状态
payRefundSyncJob	job/refund/PayRefundSyncJob.java	主动同步退款状态
payTransferSyncJob	job/transfer/PayTransferSyncJob.java	主动同步转账状态

上线前请检查 XXL-Job 或当前环境的调度配置是否已启用这些 Handler。若只配置渠道、不启用补偿任务，偶发网络异常时业务单可能长期停留在“待支付/退款中”。

验证清单

验证项	通过标准
应用列表	可以新增、编辑、启停支付应用
渠道配置	mock、支付宝或微信渠道能保存，列表显示已配置
支付订单	发起支付后产生 pay_order 记录
回调通知	pay_notify_task 能记录并推进通知状态
业务状态	示例订单、商城订单或钱包充值状态随支付结果更新
退款链路	退款申请后 pay_refund 与业务退款状态一致
日志排查	C:\Users\ZZY\logs\yudao-server.log 中无支付回调异常

常见问题

渠道已保存，但业务侧看不到可用支付方式

优先检查三点：

1. 支付应用是否启用。
2. 支付渠道是否启用。
3. 业务单使用的 appId 是否就是该支付应用的编号。

支付成功但业务订单未更新

重点排查通知链路：

• 第三方平台是否能访问后端公网回调地址。
• payNotifyJob 是否正常调度。
• 业务回调接口是否返回成功。
• 日志中是否存在签名校验、租户、数据权限或业务单不存在异常。

本地开发没有公网地址怎么办

本地优先使用 mock 渠道验证业务闭环。确需验证支付宝/微信异步通知时，可使用内网穿透工具暴露后端回调地址，但不要把测试密钥提交到仓库。

下一步

• 订单支付联调：查看管理端 pay/order、pay/demo/order 页面。
• 退款联调：查看管理端 pay/refund 页面。
• 商城交易闭环：继续阅读 商城交易订单。