Files
usdt/docs/rental/topup-payment.md
T
2026-10-29 04:07:57 -04:00

98 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 租赁资金账户在线充值
资金账户详情页新增「在线充值」和充值记录。用户只需选择账户网络、填写 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,应先完成在途核对再轮换。停止某网络通道也会暂停该网络的支付查询。
## 业务流程与资金安全
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 检查。
- `PAYMENT_CREATE_RESPONSE_VALIDATE`:支付返回单号、金额、地址、有效期或收银台地址不符合要求。
- `CHAIN_VERIFY` / `LEDGER_CREDIT`:链上核验或账务事务失败。
异常摘要保留异常因果类型、前五个堆栈位置及 SQLState/数据库错误码,不记录异常原文,避免 SQL 参数、支付响应、Secret、公钥正文和签名进入日志。日志定位到阶段后,再检查对应服务器文件或配置;不要向日志追加完整配置对象。
隔离测试使用 H2 事务和可控支付/链上适配器,覆盖通知验签、重复请求、超时补偿、双网络金额核对、冻结账户、共享幂等键、并发补偿及租约接管。测试不会访问真实支付账户、修改线上数据库或广播交易。上线前仍需在 NILE 配置真实支付通道完成端到端验收。