# 租赁资金账户在线充值 资金账户详情页新增「在线充值」和充值记录。用户只需选择账户网络、填写 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`,默认关闭。以下是环境变量示例,替换域名和凭证后再启用: ```properties 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信任库: ```properties 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:::` 幂等键,避免重复入账。多实例补偿使用数据库租约与所有者校验,过期任务不能回写终态。 支付新订单保存网络快照,扫描按订单网络选择节点;历史 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解析失败单独输出安全异常位置,不输出响应正文。 - `PAYMENT_CREATE_RESPONSE_VALIDATE`:支付返回单号、金额、地址、有效期或收银台地址不符合要求。 - `CHAIN_VERIFY` / `LEDGER_CREDIT`:链上核验或账务事务失败。 异常摘要保留异常因果类型、前五个堆栈位置及 SQLState/数据库错误码,不记录异常原文,避免 SQL 参数、支付响应、Secret、公钥正文和签名进入日志。日志定位到阶段后,再检查对应服务器文件或配置;不要向日志追加完整配置对象。 隔离测试使用 H2 事务和可控支付/链上适配器,覆盖通知验签、重复请求、超时补偿、双网络金额核对、冻结账户、共享幂等键、并发补偿及租约接管。测试不会访问真实支付账户、修改线上数据库或广播交易。上线前仍需在 NILE 配置真实支付通道完成端到端验收。