转账管理
转账管理用于记录和查询企业向用户、员工、商户或钱包账户付款的转账单。RuoYi Office 当前 Pay 模块提供转账单列表、详情、导出能力，并通过“示例提现单”演示支付宝、微信和钱包转账的最小链路。
本页基于 PayTransferController、PayDemoWithdrawController、PayDemoWithdrawServiceImpl 和管理端转账页面整理。
当前实现边界
| 层 | 路径 / 接口 |
|---|---|
| 转账单控制器 | controller/admin/transfer/PayTransferController.java |
| 转账服务 | service/transfer/PayTransferService |
| 示例提现控制器 | controller/admin/demo/PayDemoWithdrawController.java |
| 示例提现服务 | service/demo/PayDemoWithdrawServiceImpl.java |
| 管理端转账页 | apps/web-antd/src/views/pay/transfer |
| 管理端示例提现页 | apps/web-antd/src/views/pay/demo/withdraw |
| 转账单接口 | /admin-api/pay/transfer/* |
| 示例提现接口 | /admin-api/pay/demo-withdraw/* |
转账链路
示例提现单同样固定使用 appKey = demo。生产业务需要根据业务域设计自己的付款单、提现单或结算单，并通过 PayTransferApi 创建转账单。
渠道选择规则
PayDemoWithdrawServiceImpl#getTransferChannelCode 当前按提现类型选择渠道：
| 示例提现类型 | 转账渠道编码 | 说明 |
|---|---|---|
| 支付宝 | alipay_pc | 示例中复用支付宝 PC 渠道编码 |
| 微信 | wx_lite | 微信转账需要额外用途说明 |
| 钱包 | wallet | 本地钱包转账/记账能力 |
微信转账比较特殊，示例服务会设置渠道扩展参数：
java
PayTransferCreateReqDTO.buildWeiXinChannelExtra1000("测试活动", "测试奖励")生产环境应按微信商户平台要求填写真实用途、场景和收款身份信息。
转账单管理
管理端「转账单」页面提供分页、详情和导出：
| 功能 | 接口 | 权限 |
|---|---|---|
| 转账分页 | GET /pay/transfer/page | pay:transfer:query |
| 转账详情 | GET /pay/transfer/get | pay:transfer:query |
| 导出转账 | GET /pay/transfer/export-excel | pay:transfer:export |
列表会展示商户转账单号、Pay 转账单号、渠道转账单号。排查时建议按以下顺序定位：业务付款单号 → merchantTransferId → Pay 转账单 → 渠道转账单。
发起转账前校验
示例提现单发起转账前会校验：
- 提现单存在。
- 状态为等待中或转账失败关闭状态。
- 如果曾经失败，会先重置为等待中再重新发起。
- 创建 Pay 转账单时写入
merchantTransferId、转账主题、金额、收款账号、收款人姓名和渠道编码。
生产业务应额外增加：余额、账户实名、风控、审批、日限额、黑名单和财务复核等校验。
回调与状态更新
渠道完成转账后，Pay 模块会通知示例提现单：
text
POST /pay/demo-withdraw/update-transferred回调处理会校验：
- 示例提现单是否存在。
- 业务单是否已经结束，重复回调要幂等返回。
- Pay 转账单是否存在且状态为成功或关闭。
- 转账金额是否一致。
merchantTransferId是否等于提现单 ID。- 转账渠道是否和提现单记录一致。
只有校验通过后，才会把示例提现单更新为成功或失败，并记录渠道错误信息。
和退款的区别
| 对比项 | 退款 | 转账 |
|---|---|---|
| 资金来源 | 原支付订单原路退回 | 商户主动付款到用户账户 |
| 关联单据 | 支付订单、退款申请、售后单 | 提现单、结算单、奖励单、工资单等 |
| 渠道要求 | 依赖原支付渠道退款能力 | 依赖商户转账/付款到零钱/支付宝转账等能力 |
| 风控重点 | 可退金额、重复退款、原路退回 | 收款实名、限额、用途、审批、失败重试 |
不要用“转账”替代可原路退回的支付退款；也不要用“退款”处理没有原支付单的付款场景。
排查清单
| 现象 | 优先检查 |
|---|---|
| 发起转账失败 | 提现单状态、渠道配置、收款账号/姓名、金额单位 |
| 微信转账失败 | 用途说明、商户权限、收款用户 OpenID/实名要求 |
| 转账一直处理中 | 渠道状态、payTransferSyncJob、回调地址、渠道错误码 |
| 业务单未更新 | /pay/demo-withdraw/update-transferred 日志、merchantTransferId 是否匹配 |
| 重试失败 | 是否只允许等待中/失败关闭状态重试，历史转账单是否已终态 |
二次开发建议
- 生产转账必须有独立业务付款单，不建议直接从页面创建 Pay 转账单。
- 大额转账要接入审批流或财务复核。
- 转账失败要保留渠道错误码和错误信息，支持运营人工处理。
- 同一业务单只允许一个有效转账单，重试要明确旧单状态。
- 导出转账单属于敏感能力，建议限制到财务或管理员角色。
