提交冻结USDT,同一用户全网络仅允许一笔进行中提现。
支持后台、Telegram审核;拒绝后释放冻结。 支持管理员填写Hash核验到账、链上监听自动到账,记录到账方式和操作日志。 严格核对网络、付款方、收款方、金额及审核后交易时间,防止重复扣款。 已补齐前端申请、记录、审核、扫描状态和交易明细页面。
This commit is contained in:
1 parent
dc2564b1d4
commit
f837befe99
17 files changed
+1604
-4
No files matched your search
@@ -0,0 +1,87 @@
|
||||
# 租赁资金账户提现
|
||||
|
||||
## 业务边界
|
||||
|
||||
提现只使用当前用户对应网络 `rent_account.available_amount`,不提取冻结余额或供应商待结算金额。NILE与MAINNET分别记账,但数据库用 `active_user_id` 唯一槽保证同一用户全网络只能有一笔未完成提现。提交即在同一事务写 `WITHDRAW_HOLD` 流水:可用余额减少、冻结余额增加。拒绝写 `WITHDRAW_RELEASE`;链上到账写 `WITHDRAW_COMPLETE`,只减少冻结,不再次减少可用。
|
||||
|
||||
状态为 `PENDING_REVIEW → EXECUTING → VERIFYING/MANUAL_REVIEW → COMPLETED`,拒绝为 `REJECTED`。进入执行后不能直接退款,因为管理员可能已经付款;RPC失败、未确认或证据冲突均保持冻结。
|
||||
|
||||
后台和Telegram审核调用相同服务。Telegram数字ID除原白名单外,还必须在 `telegram-reviewers` 映射到具有 `rent:withdraw:review` 权限且有效的系统用户,不能用昵称授权或虚构系统操作者。审核通过保存当时的付款地址JSON快照,后续修改配置不改变已审核订单。
|
||||
|
||||
## 手动与自动到账
|
||||
|
||||
管理员手动:完成外部钱包付款后填写交易Hash、可选日志索引和执行备注。系统独立查询TRON交易及收据,核验成功才能到账,不能强制改变余额。
|
||||
|
||||
自动监听:按网络持久化扫描已固化区块,RPC确认深度由 `rental.confirmations` 再次限制。逐块读取完整交易收据,发现审核快照付款地址发出的真实USDT `Transfer`,保存 `rent_withdraw_transaction` 后匹配提现。匹配同时要求网络、USDT合约、付款地址、收款地址、6位金额完全相同,并且链上区块时间严格晚于 `approved_at`。不拼接多笔、不接受多付少付;多单歧义转人工核对。
|
||||
|
||||
两种入口最终调用同一个 `complete` 事务。提现单行锁、链上事件唯一键、`withdraw_id`唯一认领及账本business_key共同防止并发重复扣款。到账记录 `arrival_mode=MANUAL/AUTO`、Hash、日志索引、区块与时间。自动扫描游标仅在整块事件保存完成后推进,多实例使用短租约;故障重启会重扫,幂等约束防重复。
|
||||
|
||||
## 部署
|
||||
|
||||
1. 执行 `sql/rent_withdraw_migration.sql`,再执行 `sql/rent_withdraw_menu.sql`;不删除或重算历史余额。
|
||||
2. 配置每个启用网络的付款地址、额度、Telegram映射;先保持 `enabled=false` 和 `scan-enabled=false`。
|
||||
3. 部署前后端,赋予运营角色 `rent:withdraw:list/review/execute`;申请角色由脚本获得 `rent:withdraw:create`。
|
||||
4. 打开提现但暂不开扫描,使用小额单验证后台审核及人工Hash核验。
|
||||
5. 验证RPC支持 `/wallet/gettransactioninfobyblocknum` 后开启扫描,观察后台页面游标和服务日志,再扩大额度。
|
||||
|
||||
```yaml
|
||||
rental:
|
||||
withdraw:
|
||||
enabled: ${RENT_WITHDRAW_ENABLED:false}
|
||||
min-amount-usdt: ${RENT_WITHDRAW_MIN_USDT:1}
|
||||
max-amount-usdt: ${RENT_WITHDRAW_MAX_USDT:10000}
|
||||
scan-enabled: ${RENT_WITHDRAW_SCAN_ENABLED:false}
|
||||
poll-interval-ms: ${RENT_WITHDRAW_POLL_MS:10000}
|
||||
scan-batch-blocks: ${RENT_WITHDRAW_SCAN_BATCH_BLOCKS:5}
|
||||
telegram-reviewers: ${RENT_WITHDRAW_TELEGRAM_REVIEWERS:}
|
||||
nile:
|
||||
payout-addresses: ${RENT_WITHDRAW_NILE_PAYOUT_ADDRESSES:}
|
||||
mainnet:
|
||||
payout-addresses: ${RENT_WITHDRAW_MAINNET_PAYOUT_ADDRESSES:}
|
||||
```
|
||||
|
||||
服务不保存付款私钥、不自动广播。配置多个地址用英文逗号分隔;地址与Telegram映射属于敏感运营配置,不提交代码仓库。日志打印提现ID、网络、金额、Hash、日志索引、模式和脱敏异常定位,不打印凭证、私钥、签名原文或完整RPC响应。
|
||||
|
||||
## 页面及接口
|
||||
|
||||
本人资金账户页提供申请、记录和时间线:`POST /rental/withdraw/create`、`GET /rental/withdraw/list`、`GET /rental/withdraw/{id}`。管理员菜单页面使用 `/rental/manage/withdraw` 下的列表、详情、审核及transaction接口;只读交易明细接口便于定位未匹配事件。用户ID始终来自登录上下文。
|
||||
|
||||
申请示例(使用已登录后台身份,不使用租赁应用API凭证):
|
||||
|
||||
```json
|
||||
{"network":"NILE","receiver_address":"你的TRON地址","amount":"30.000000","client_request_no":"客户端唯一请求号","remark":"提现说明"}
|
||||
```
|
||||
|
||||
`client_request_no`重试必须保持不变。相同用户与请求号、相同内容返回原申请;变更金额或地址需要新请求号,并且原在途申请必须先结束。金额以十进制字符串传递,最多6位小数;初版不收提现手续费,申请金额等于链上应付USDT金额。
|
||||
|
||||
管理员审核:`POST /rental/manage/withdraw/{id}/review`,请求 `{"approve":true,"reason":"审核意见"}`。手动到账:`POST /rental/manage/withdraw/{id}/transaction`,请求 `{"transaction_id":"64位Hash","log_index":0,"remark":"付款执行说明"}`;日志索引可省略,但同一交易存在多个符合条件的事件时必须明确指定。核验未通过时返回保留冻结的当前状态及`last_error`,前端不得仅根据HTTP成功提示到账。
|
||||
|
||||
交易排查:`GET /rental/manage/withdraw/transactions?network=NILE&page=1&hash=可选完整Hash`。本人列表固定每页20条,管理员列表支持network/status/page;本人详情禁止跨用户访问。相同区块发现多笔符合单张提现申请的付款时转人工核对,不自动选择第一笔。
|
||||
|
||||
## 数据表职责
|
||||
|
||||
| 表 | 关键字段与职责 |
|
||||
| --- | --- |
|
||||
| rent_withdraw_order | user_id/account_id/network确定资金归属;amount/frozen_amount记录申请与冻结金额;active_user_id唯一约束防全网络重复申请;client_request_no/request_hash保证重试幂等;approved_at与payout_sender_snapshot固定匹配边界;arrival_mode/arrival_transaction_id/completed_at记录到账结果 |
|
||||
| rent_withdraw_transaction | network+transaction_id+log_index唯一标识真实链上事件;保存合约、付款方、收款方、6位USDT金额、最小单位、区块Hash/时间和证据;withdraw_id唯一约束防止一笔付款核销两次 |
|
||||
| rent_withdraw_scan_cursor | 每网络一个持久扫描位置,last_block只在整块处理成功后推进;lock_owner/lock_until支持多实例租约;last_error记录可排查故障 |
|
||||
| rent_ledger | 新增nullable withdraw_id关联提现;WITHDRAW_HOLD/RELEASE/COMPLETE与余额更新同事务,不更改既有充值和租赁流水 |
|
||||
| rent_event | 保存申请、审核、手动核验、MANUAL/AUTO到账操作轨迹和操作者 |
|
||||
| telegram_audit_record及推送队列 | 沿用项目现有Telegram审核模型,业务类型RENT_WITHDRAW;创建申请时与冻结一并持久化,机器人推送失败不丢审核单 |
|
||||
|
||||
## 排查及运行边界
|
||||
|
||||
管理员详情突出展示本单网络的允许付款钱包,并在通过审核前再次确认网络、付款地址、收款地址与金额。待审核使用当前配置,通过后展示审核时的地址快照;地址未配置或详情未加载完成时禁止点击通过。提示同时适用于后续手动Hash核验与自动到账。
|
||||
|
||||
按withdrawId/withdrawNo、network、Hash检索日志;扫描日志包含cursor、confirmedHead及backlog。余额不足、重复申请、本人审核、权限映射无效均拒绝;网络异常、未确认、付款方/金额不匹配均不解冻。管理员不能审核自己的提现。
|
||||
|
||||
首次扫描从最早有效审核时间前定位区块,之后按持久断点追赶。默认每10秒最多扫描5块,积压时可调大batch(上限100),并观察RPC限流。RPC必须支持整块回执接口,不支持或回执缺失时停止推进并保留冻结;不会降级成忽略交易。服务使用已有TRON网络配置和对应USDT合约,不能把测试网交易用于主网到账。
|
||||
|
||||
增量脚本需先于新服务执行,因为公共账本插入已包含withdraw_id。脚本仅新增结构和菜单,不会付款、不重算余额、不删除历史数据。真实MySQL、Telegram机器人及NILE钱包仍需部署后小额联调。
|
||||
|
||||
## 本地验证记录
|
||||
|
||||
- JDK8执行`Rental*Test`:108项通过,0失败、0错误,其中提现专项12项。
|
||||
- 覆盖冻结/拒绝释放、跨网络并发申请、幂等重试、手动与自动并发核销、未知链上结果保留冻结、重复付款歧义、Telegram真实审核路由和重复回调、RPC失败后恢复,以及真实USDT日志解码和确认边界。
|
||||
- 前端staging构建完成;存在项目原有的3个API导出缺失告警以及资源体积告警。提现相关Vue模板与脚本解析通过。
|
||||
- 新建表在初始化、独立建表和增量脚本中的定义一致。数据库测试使用H2 MySQL兼容模式,未执行生产MySQL脚本,未发送Telegram消息或广播交易。
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
2026-10-29扩展:新增地址上链订单ADDRESS_ONCHAIN,供应商固定转1TRX,用户USDT账户承担本金折价及服务费;复用订单、任务、交易及账务,新增字段和节点能力见 [地址上链完整设计与实现](../rental-address-onchain.md)。该类型不绑定套餐、不做资源换算、无租期及回收;原有资源租赁规则保持本基线。
|
||||
|
||||
资金账户新增可用USDT提现:申请冻结、后台/Telegram审核、管理员Hash核验及链上监听自动到账,完整表、状态、配置及部署见 [租赁资金账户提现](../rental-withdraw.md)。提现不保存付款私钥、不自动广播,所有到账均以已确认USDT Transfer为依据。
|
||||
|
||||
2026-10-25增量:新增第17张表 rent_user_package,按系统用户绑定套餐与默认项;下单从应用user_id确定授权,见 [用户套餐绑定](user-package-bindings.md)。以下16表描述为原设计基线。
|
||||
|
||||
状态:V2.2设计基线;当前已新增后端、Vue及本地Node.js Agent实现,运行配置、接口与验证边界见[三端实现说明](implementation.md)。未执行现有数据库迁移或真实链上广播。当前权威 DDL 为 [rent_init.sql](../../sql/rent_init.sql),共16张表;历史设计复核见[业务复核与修正说明](business-review-v2.2.md),逐表说明见[table-functional-flows.md](table-functional-flows.md)。下文“本次仅设计”描述设计审查阶段,不替代当前实现记录。
|
||||
|
||||
Reference in new issue
Block a user