9.9 KiB
通用转账接入与部署
服务与资金口径
转账业务入口为 ThirdAppPlusTransferServiceImpl，渠道扩展点为 ThirdTransferChannel。当前注册支付宝 20，其他平台在新指令受理前拒绝。收款与转账分别持久化，现有支付流水页面通过分类切换查询。
内部 R 成功表示本次受理或查询成功。资金结果读取 status，取值为 ACCEPTED、PROCESSING、UNKNOWN、SUCCESS、FAILED。任务执行状态和业务结果通知状态分别展示。
币种固定 CNY。amountFen 使用 Long 整数分，JSON以字符串传输，金额范围为 10 至 10000000000 分。小数、指数、溢出金额明确拒绝。金额达到 5000000 分必须提供付款理由，渠道实际签约额度由支付宝返回。
内部发起及恢复
调用方依赖 thirdparty-api 的 RemoteThirdTransferService，并沿用平台租户上下文与内部调用保护。
| 方法 | 路径 | 语义 |
|---|---|---|
| POST | /transfer-remoter |
受理原付款指令，事务提交订单、事件和提交任务 |
| GET | /transfer-remoter/{transferNo} |
读取原单资金与通知结果 |
| GET | /transfer-remoter/by-request?requestNo=… |
响应丢失后按原请求恢复结果 |
ThirdTransferCreateDto 包含稳定 requestNo、bizType、bizId、platformType、amountFen、ownerDeptId、initiatorUserId，可选 mchId，以及 receiver、title、remark、scene。调用方在自身业务内完成付款授权、金额与收款人确认，并保证付款指令的持久幂等边界。
同租户同请求号的规范化参数相同返回原单，金额、收款人、归属或业务参数变化时拒绝。受理响应丢失后使用原请求号查询或重试，同一指令始终沿用原转账号。
收款身份支持 ALIPAY_LOGON_ID、ALIPAY_USER_ID、ALIPAY_OPEN_ID。登录号必填实名，其他身份提供姓名时由支付宝核对一致性。商户 smid 与收款身份分别使用。
场景申报
scene.name 与已向支付宝申报的真实业务场景一致，scene.reports 为 {type, content} 数组。所有必需信息类型都要提供，每种只出现一次，内容不能为空。
| 场景 | 必需上报类型 |
|---|---|
| 现金营销 | 活动名称、奖励说明 |
| 企业退款 | 退款原因 |
| 佣金报酬 | 佣金报酬说明 |
| 业务结算 | 结算款项名称 |
| 二手回收 | 回收商品名称 |
| 公益补助 | 公益活动名称 |
| 行政补贴和退款 | 补贴/退款类型 |
| 保险理赔 | 业务类型、保险险种、业务交易订单号 |
服务使用 alipay.fund.trans.uni.transfer 和 alipay.fund.trans.common.query，固定 DIRECT_TRANSFER 与 TRANS_ACCOUNT_NO_PWD。SDK沿用 4.40.251.ALL，新场景字段由独立结构化请求写入 biz_content。转账接口、场景上报规则
付款应用与业务通知配置
付款应用复用 app-plus.pay.ali-pay-config，须配置 CERT、应用私钥、应用公钥证书、支付宝公钥证书及根证书。证书配置方式沿用现有支付宝双模式部署说明。配置或证书更换后重启全部 thirdparty 实例。
历史单据固定保存原付款AppID。更换默认应用时继续登记旧应用及其可用证书，使原单查询和恢复能够精确选择原凭据。加密保存原指令所用的项目加密配置必须持续可用。
酒店结账业务 hotel-checkout 已内置结果接收目标 pjcloud-wallet-biz，预检与正式受理共用这一解析规则。其他业务由服务端按业务类型登记。显式配置可以覆盖内置目标，下面为酒店结账的覆盖示例。
app-plus:
transfer:
notify-targets:
hotel-checkout:
service-id: pjcloud-wallet-biz
显式配置为空或格式非法时仍会阻止预检和受理。只接受服务发现名称，调用方无法传入任意通知URL。受理时固定保存接收服务，所有通知重试沿用原目标、通知ID及结果版本。
结果接收契约
业务服务实现 ThirdTransferResultReceiver，接口为 POST /inner/third-transfer/result，使用 @Inner 保护。发送端通过 OpenFeign 复用内部调用标识和租户头。
通知包含 notifyId、resultVersion、转账号、请求号、业务类型及ID、平台、资金终态、分金额、币种、渠道单号、付款完成时间和安全错误摘要。
接收方在本地事务内校验原付款指令、业务关联和金额，按通知ID幂等，按转账号的结果版本防止旧通知覆盖新事实。处理成功或已经处理过该通知返回 R.ok(true)，其他响应独立重试。事实纠正产生更高结果版本，原通知版本保持可追溯。
应用网关通知
支付宝应用网关配置现有 /third-app-pay/app/subscribe-callback 的公网入口，订阅 alipay.fund.trans.order.changed。网关微服务前缀沿用当前部署路由。
入口返回纯文本 success 或 fail。通知先按 app_id 精确选择证书及过渡期旧公钥验签，再按全局唯一转账号最小定位租户，通过 TenantBroker 恢复订单租户并核对来源接口、产品、场景、金额及有回传的同类收款身份。
本地资金事实、去重事件及后续通知任务提交成功后应答。业务接收服务暂时不可用时由独立通知任务重试。重复表单键被拒绝，外部通知ID以固定哈希写入去重键。支付宝通知协议
任务与人工恢复
| 任务类型 | Quartz触发间隔 | 默认每轮数量 | 职责 |
|---|---|---|---|
TRANSFER_SUBMIT |
5秒 | 100 | 原指令提交，恢复时先查询，明确查无原单后才同号重发 |
TRANSFER_QUERY |
10秒 | 100 | 原转账号只读核对 |
TRANSFER_NOTIFY |
10秒 | 100 | 最终结果可靠通知，任务键包含结果版本 |
Worker复用数据库租约、有界队列、指数退避及告警，原任务的重试上限沿用 third.payment.task.max-attempts。任务用尽保留实际资金状态，管理页显示人工核对提示。
管理端查单只安排原单查询。恢复任务仅恢复当前允许执行的失败阶段，已终态资金提交任务不可重新执行。新付款由源业务在明确失败并完成付款授权后创建新的付款指令。
页面与权限
原页面路由沿用 /thirdparty/third-pay-order/index，组件路径 thirdparty/third-pay-order/index，组件及KeepAlive名称 systemThirdPayOrder。原 payNo、aggregateScene 定位继续支持，转账定位使用 recordType=TRANSFER&transferNo=…。
以下按钮挂在现有“支付流水”菜单下，由管理端手动添加，真实父菜单ID待确认。
| 名称 | 类型 | 父级菜单及ID | 权限标识 | 路由 |
|---|---|---|---|---|
| 转账查看 | 按钮 | 支付流水，ID待确认 | third_thirdTransferOrder_view |
— |
| 转账查单 | 按钮 | 支付流水，ID待确认 | third_thirdTransferOrder_query |
— |
| 转账任务恢复 | 按钮 | 支付流水，ID待确认 | third_thirdTransferOrder_retry |
— |
列表、详情、事件、查单和恢复均按保存的部门、发起用户快照检查数据权限。通用支付任务列表及重试入口同时应用转账权限。账号和姓名原文仅存在加密指令内，列表及事件返回脱敏字段。
迁移与发布
- 在第三方业务库执行独立迁移
db/20261110_add_third_transfer.sql，前置为既有third_payment_task表。脚本包含两张转账业务表及任务关联字段，可重复执行。 - 部署 thirdparty，检查CERT应用及通知登记，业务接收服务先准备统一接收契约。
- 部署Quartz，确认三个固定任务均完成初始化。
- 部署前端并手动配置按钮权限及角色数据范围。
- 配置支付宝转账产品、业务场景和应用网关订阅，完成专用测试账户联调。
本次仅交付迁移文件。数据库执行、真实支付宝付款与渠道联调需单独安排。
集中验证清单
定向回归代码覆盖严格分金额输入、稳定请求摘要、重复受理、金额边界、场景完整性、超时先查后重发、查询异常分类、回调事实核对、终态冲突、旧通知回执及通用任务越权路径。
集中验证时运行受影响模块测试、编译、前端检查和构建，并在隔离数据库验证唯一键竞争、真实事务回滚、租约恢复、响应丢失及通知重投。支付宝联调单独记录实际AppID、产品签约、网关消息、渠道结果和业务确认结果，记录中使用脱敏账号。
酒店结账内部接入
酒店整批付款由钱包保存原授权并逐商户调用通用转账。创建指令可携带 expectedPayerAppId，第三方新受理时校验实际付款应用，原请求重放优先恢复原单。缺省该字段继续使用原V1摘要。
专用 POST /transfer-remoter/merchant-receivers/resolve 按商户及当前支付配置解析唯一默认转账接收方，要求关系的 enableTransfer=1、isTransferDefault=1。收款默认标记、分账作用、比例及绑定状态独立。完整身份仅供受保护的服务间调用，管理端使用脱敏结果。
支付作用改造先执行 db/20261110_add_mch_payment_purposes.sql，检查重复默认及配置异常清单，再发布 thirdparty 全部实例和前端。迁移首次沿用原有效支付宝默认接收方的转账用途，重复执行保留管理员后续配置。转账预览校验当前默认用途，已受理付款及原任务重试继续使用原加密指令快照。
POST /transfer-remoter/{transferNo}/recheck 恢复原任务并同步查单一次。未知查询不能作为再次发款依据。明确失败且渠道确认无原单的结果可由源业务重新发起人工授权。酒店端口径和发布步骤见 pjcloud-wallet/docs/checkout-transfer.md。