76 lines
7.0 KiB
Markdown
76 lines
7.0 KiB
Markdown
# 租赁资金账户在线充值
|
|
|
|
资金账户详情页新增「在线充值」和充值记录。用户只需选择账户网络、填写 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:<充值单号>` 支付用户标识,隔离支付金额槽位;因此需要持续补充或维护支付钱包池容量。
|
|
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 | `/api/rental/payment/notify/{channel}` | 支付 RSA 通知,channel 为 NILE 或 MAINNET |
|
|
|
|
支付查单接口增加 `network`、`payment_address`、`payment_amount`、`expiration_time` 字段,保留原有响应字段。创建接口新增可选 `network`、`amount_currency=USDT` 参数,所有参数仍须进入 SecureClient 加密与认证。
|
|
|
|
状态流转:CREATING → WAITING_PAYMENT → VERIFYING → CREDITED。创建响应不确定进入 CREATE_UNKNOWN 并使用原单号重试;支付端明确过期进入 EXPIRED。订单数据不一致、账户冻结、转账已通过其他入口入账进入 MANUAL_REVIEW。暂时网络异常和链上确认不足继续后台补偿,不生成新支付订单。浏览器关闭不影响后台核对。
|
|
|
|
运维可以在数据库只读检查 `topup_no/status/query_attempts/last_error/next_query_at`、支付订单及 TOPUP 流水。MANUAL_REVIEW 为人工处理终态,当前没有专用人工审核页面;不得直接改余额或删除幂等流水。确认原因并完成业务审核后,由受控运维流程恢复核对或按既有人工充值流程处理,恢复前须核对原链上事件是否已入账。
|
|
|
|
## 验证范围
|
|
|
|
隔离测试使用 H2 事务和可控支付/链上适配器,覆盖通知验签、重复请求、超时补偿、双网络金额核对、冻结账户、共享幂等键、并发补偿及租约接管。测试不会访问真实支付账户、修改线上数据库或广播交易。上线前仍需在 NILE 配置真实支付通道完成端到端验收。
|