Files
usdt/docs/rental/topup-payment.md
T

13 KiB
Raw Blame History

租赁资金账户在线充值

资金账户详情页新增「在线充值」和充值记录。用户只需选择账户网络、填写 USDT 金额,不需要输入支付 API 凭证。NILE 测试资产与主网资产严格隔离,充值不会跨网络增加余额。

部署与数据库

  1. 支付服务数据库执行 sql/payment_topup_upgrade.sql,为 orders 增加 payment_network。此列是新版支付实体必需字段,即使暂不启用在线充值也须执行。脚本为一次性迁移,重复执行前先检查字段。
  2. 租赁服务数据库执行 sql/rent_topup_init.sql,新增 rent_topup_order 与 rent_topup_notify,不删除历史表或数据。
  3. 同步部署新版支付后端、租赁后端和前端。两套后端可以部署在同一个应用实例,也可以独立部署。
  4. 在支付平台创建应用及有效 API 凭证,准备该应用对应的 RSA 公钥文件,确保支付钱包池有可分配地址,并将 payment.checkout-url 设置为真实 HTTPS 收银台地址。

rent_topup_order 保存用户、账户、网络、请求幂等号、支付单号、金额、收款地址、支付通道公钥快照、状态、补偿租约和最终链上事件。rent_topup_notify 保存已经通过 RSA 验签的通知摘要和事件,不保存 Secret、私钥或原始签名。余额与流水继续复用 rent_account、rent_ledger。

application-rental.yml 配置

配置位于 rental.payment,默认关闭。以下是环境变量示例,替换域名和凭证后再启用:

RENT_PAYMENT_ENABLED=true
RENT_PAYMENT_NILE_ENABLED=true
RENT_PAYMENT_NILE_BASE_URL=https://pay.example.com
RENT_PAYMENT_NILE_API_KEY=<支付应用API_KEY>
RENT_PAYMENT_NILE_API_SECRET=<支付应用API_SECRET>
RENT_PAYMENT_NILE_PUBLIC_KEY=file:/opt/ruoyi/keys/nile-payment-public.pem
RENT_PAYMENT_NILE_NOTIFY_URL=https://rent.example.com/api/rental/payment/notify/NILE
RENT_PAYMENT_NILE_MIN_AMOUNT=1.00
RENT_PAYMENT_NILE_MAX_AMOUNT=10000.00

RENT_PAYMENT_MAINNET_ENABLED=false
RENT_PAYMENT_MAINNET_BASE_URL=https://pay.example.com
RENT_PAYMENT_MAINNET_API_KEY=<主网支付应用API_KEY>
RENT_PAYMENT_MAINNET_API_SECRET=<主网支付应用API_SECRET>
RENT_PAYMENT_MAINNET_PUBLIC_KEY=file:/opt/ruoyi/keys/mainnet-payment-public.pem
RENT_PAYMENT_MAINNET_NOTIFY_URL=https://rent.example.com/api/rental/payment/notify/MAINNET
RENT_PAYMENT_MAINNET_MIN_AMOUNT=1.00
RENT_PAYMENT_MAINNET_MAX_AMOUNT=10000.00

BASE_URL 是外部可访问的后端基地址,适配器追加 /api/v1/order/create-transaction 和 /api/v1/order/query。如果反向代理有路径前缀,基地址需要包含此前缀。NOTIFY_URL 必须是支付服务能访问的完整 HTTPS 地址,通道名使用大写。RSA 公钥不是 TLS 证书,也不是租赁应用凭证;应使用支付应用配置中对应的公钥。自签 TLS 证书需要导入运行租赁服务的 JVM 信任库,不能通过关闭证书验证处理。

可选超时配置:RENT_PAYMENT_CONNECT_TIMEOUT_MS=5000、RENT_PAYMENT_READ_TIMEOUT_MS=15000、RENT_PAYMENT_RECONCILE_MS=15000。单次支付 HTTP 总时限为 30 秒。后台核对需要现有 rental.rpc 正常可用及对应网络的 USDT 合约配置。

在途订单保存 API Key、公钥、基地址快照,但不保存 API Secret。存在未完成充值时应保持对应通道旧凭证有效;本实现不支持通过覆盖配置无缝轮换在途 Secret,应先完成在途核对再轮换。停止某网络通道也会暂停该网络的支付查询。

业务流程与资金安全

自签HTTPS支付服务

支付客户端支持独立信任证书,无需修改全局JVM信任库:

RENT_PAYMENT_NILE_TLS_CERTIFICATE=file:/etc/nginx/certs/fullchain.pem
# 主网若需要独立证书,可另外配置:
RENT_PAYMENT_MAINNET_TLS_CERTIFICATE=file:/etc/nginx/certs/fullchain.pem

对应 rental.payment.nile.tls-certificate-location / mainnet.tls-certificate-location。文件须为经过管理员核对的X.509证书或CA证书(PEM/DER),不能使用privkey.pem或支付RSA公钥。运行后端的用户须有读取权限;容器需挂载文件。证书SAN必须包含支付域名或IP,例如 IP:192.168.3.103。修改后重启服务,原充值单会后台重试。

本功能合并当前JVM默认信任锚与指定证书,仅作用于支付HTTP客户端,保留证书有效期和域名校验。请移除此前仅为自签支付服务添加的全局 -Djavax.net.ssl.trustStore... 参数(如其他业务仍需要自定义全局信任库,应保留包含完整CA的合并库),恢复TronGrid等调用使用的正常默认CA。不会修复证书域名不匹配、过期或错误代理地址。

  1. 登录用户创建充值,服务端校验账户归属、ACTIVE 状态、网络、金额上下限和最多两位小数;以 user_id + client_request_no 幂等落库。
  2. 在数据库事务外调用项目支付加密协议,明文业务参数包含 network=NILE/MAINNET、amount_currency=USDT,避免充值金额被业务币汇率转换。未传币种的原支付客户端继续使用原汇率逻辑。
  3. 展示真实支付地址、准确金额、二维码、倒计时和收银台链接。每笔充值使用 rent:<充值单号> 支付用户标识,隔离支付金额槽位;因此需要持续补充或维护支付钱包池容量。 用户点击「创建支付单并前往支付」后,支付单就绪即自动跳转支付接口返回的 url。支付服务的 payment.checkout-url 应配置为 https://你的前端域名/public/usdtPay,服务端会追加 tradeId。旧配置的 /public/usdtCheckout 在生成新支付链接时自动转换为 /public/usdtPay。若暂未生成支付单,弹窗显示失败阶段并持续轮询,就绪后自动跳转;关闭弹窗不会触发跳转。已有订单可以从详情点击「前往支付」。
  4. 支付通知必须通过 X-Payment-Api-Key 和 X-Payment-Rsa-Signature 验证,仅保存通知收件箱并返回纯文本 ok,不会直接修改余额。通知缺失时后台主动查单仍可完成充值。
  5. 后台比较支付查询结果的订单号、交易号、网络、地址和金额,随后独立核验对应网络的已确认 USDT Transfer 日志、时间窗口、金额、收款人和交易执行结果。仅链上核验成功才可入账。
  6. 同一事务内锁定充值单及资金账户,写入 TOPUP 流水、增加可用余额、标记 CREDITED。人工和自动充值共享 TOPUP:<network>:<txhash>:<logindex> 幂等键,避免重复入账。多实例补偿使用数据库租约与所有者校验,过期任务不能回写终态。

支付新订单保存网络快照,扫描按订单网络选择节点;历史 NULL 网络订单继续使用原全局网络配置。历史 NULL 数据不能凭猜测批量回填。

接口与状态

支付页在新窗口(或浏览器新标签页)打开,当前资金账户页保留并继续刷新状态。点击创建或重试时同步预留支付窗口,异步生成订单后载入付款链接,减少浏览器拦截;若窗口被拦截或已被用户关闭,页面保留「前往支付」和收银台链接供手动打开。关闭充值弹窗时仅关闭尚未载入付款链接的等待窗口,不关闭已经打开的支付页。

登录接口复用 rent:portal:view 权限,不新增菜单:

方法 路径 用途
POST /rental/topup/create 请求体:network、字符串 amount、唯一 client_request_no
GET /rental/topup/list?network=NILE&page=1 当前用户指定网络记录,每页 20 条
GET /rental/topup/{topup_no} 当前用户充值详情
POST /rental/topup/{topup_no}/retry 核对本人原单,遵守现有租约和重试间隔,不新建支付订单
POST /api/rental/payment/notify/{channel} 支付 RSA 通知,channel 为 NILE 或 MAINNET

支付查单接口增加 network、payment_address、payment_amount、expiration_time 字段,保留原有响应字段。创建接口新增可选 network、amount_currency=USDT 参数,所有参数仍须进入 SecureClient 加密与认证。

公共收银台使用只读接口 GET /api/v1/order/checkout/{tradeId}。随机32位交易号应当视为支付链接访问凭据,不公开传播;接口仅返回交易号、网络、金额、地址、状态与有效期,不返回商户订单号、用户身份、回调地址或密钥。反向代理应对公共查询配置限流。支付成功展示收款结果,租赁余额仍由后台独立链上核验入账。无 tradeId 时保留原演示创建表单;有 tradeId 时直接展示现有订单,不调用演示创建接口或依赖浏览器已有缓存。

状态流转:CREATING → WAITING_PAYMENT → VERIFYING → CREDITED。创建响应不确定进入 CREATE_UNKNOWN 并使用原单号重试;支付端明确过期进入 EXPIRED。订单数据不一致、账户冻结、转账已通过其他入口入账进入 MANUAL_REVIEW。暂时网络异常和链上确认不足继续后台补偿,不生成新支付订单。浏览器关闭不影响后台核对。

仅 rent_topup_order 存在不代表支付创建已成功。正常情况下保存本地单后立即调用支付创建接口,无需额外操作。失败会保留原单和安全的 payment_hint 阶段提示,后台继续重试。支付创建已成功但查单超时时保留可支付状态与收银台入口。历史错误通道快照需要管理员核对:配置修正并不会自动覆盖已经保存的基地址、公钥或API Key。

运维可以在数据库只读检查 topup_no/status/query_attempts/last_error/next_query_at、支付订单及 TOPUP 流水。MANUAL_REVIEW 为人工处理终态,当前没有专用人工审核页面;不得直接改余额或删除幂等流水。确认原因并完成业务审核后,由受控运维流程恢复核对或按既有人工充值流程处理,恢复前须核对原链上事件是否已入账。

验证范围

充值失败日志定位

默认 INFO 级别即可看到充值阶段日志,不需要打开全局 DEBUG。搜索 充值创建失败 或 充值核对失败,按 diagnosticId、topupNo 或 orderId 关联同一次处理。

启动及创建充值时会输出「充值配置诊断」「充值开关来源」「充值配置层级检查」。boundEnabled/boundChannelEnabled 是配置对象实际绑定值;resolved 是当前Spring环境解析值;source 列出配置来源(按优先级排列),可发现命令行、系统属性、环境变量或外部YAML覆盖。ABSENT 表示未找到配置,NON_BOOLEAN 表示值不是true/false,RESOLUTION_FAILED 表示占位符解析失败。同时输出激活profile与进程实例标识,方便核对是否重启了正确实例。只检查已知开关,其他环境变量和凭证不会输出。总开关和网络开关现分别返回明确错误提示。

  • CHANNEL_CONFIG:检查该网络启用状态及凭证是否配置,日志只记录布尔值。
  • PUBLIC_KEY_LOAD:公钥文件读取或 RSA 解析失败;fileResource=false 时检查是否遗漏 file: 前缀。
  • LOCAL_ORDER_TRANSACTION:账户检查、本地充值表查询或插入失败。
  • PAYMENT_RECONCILE:补偿租约申请等失败,包括旧表缺少 lease_token 字段。
  • PAYMENT_CREATE / PAYMENT_QUERY:支付连接、TLS、认证、解析失败;结合支付 HTTP 状态和 businessCode 检查。 若定位到支付响应校验,搜索「充值支付业务失败」:包含HTTP状态、businessCode、dataType、safeMessage及响应字符数。safeMessage只允许项目已知固定错误,未知消息显示UNKNOWN_MESSAGE_REDACTED,避免响应中的SQL或认证信息进入日志。JSON解析失败单独输出安全异常位置,不输出响应正文。 若支付订单已生成但未跳转,搜索「充值支付跳转校验」「充值支付链接已保存」,核对HTTPS、tradeId、有无未来有效期以及本地状态。浏览器充值详情会明确提示链接无效或有效期异常;创建成功后的跳转优先于二维码和列表刷新,避免展示异常影响付款。有效期兼容毫秒时间戳和ISO日期。旧记录中已经保存的错误域名不会随新配置自动改写,需要核对记录来源后处理,不可将支付URL指向仍为占位符的“你的前端域名”。
  • PAYMENT_CREATE_RESPONSE_VALIDATE:支付返回单号、金额、地址、有效期或收银台地址不符合要求。
  • CHAIN_VERIFY / LEDGER_CREDIT:链上核验或账务事务失败。

异常摘要保留异常因果类型、前五个堆栈位置及 SQLState/数据库错误码,不记录异常原文,避免 SQL 参数、支付响应、Secret、公钥正文和签名进入日志。日志定位到阶段后,再检查对应服务器文件或配置;不要向日志追加完整配置对象。

隔离测试使用 H2 事务和可控支付/链上适配器,覆盖通知验签、重复请求、超时补偿、双网络金额核对、冻结账户、共享幂等键、并发补偿及租约接管。测试不会访问真实支付账户、修改线上数据库或广播交易。上线前仍需在 NILE 配置真实支付通道完成端到端验收。