Files
usdt/docs/rental/implementation.md
T
2026-10-23 02:31:41 -04:00

150 lines
16 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.
# 租赁模块三端实现与运行说明
本文对应当前工作区的 V2.2 实现。设计依据仍为 [schema-design.md](schema-design.md) 和 [rent_init.sql](../../sql/rent_init.sql)。代码交付不等于生产迁移或真实链上验收;本次没有修改现有数据库,没有执行任何真实广播。
## 1. 三端职责
| 端 | 入口 | 职责 |
| --- | --- | --- |
| Java 8 后端 | `ruoyi-system/.../rental` | 归属及权限、钱包控制权、固定套餐、冻结与不可变流水、任务调度、独立核验、回收、退款、人工结算、持久回调 |
| Vue 2 前端 | `usdt-ui/src/views/rental` | 商户/供应商工作台与运营操作;原16个管理菜单和3个用户菜单路径保留,复用业务组件 |
| 本地 Node.js Agent | `rent-agent/src` | 主动WSS连接、双向签名心跳、加密可靠日志、钱包本地限制、只构建签名一次、原交易恢复 |
本地 Agent 使用 Node.js 24 和锁定版本的 TronWeb 6.0.4。这里的 Node 既是供应节点角色,也明确采用 Node.js 实现;不修改示例 JavaFX 钱包程序,不要求供应商运行完整TRON节点。
核心链路:商户下单冻结USDT → 后端按可信动态资源参数预留SUN → 推送冻结任务意图 → Agent先保存再ACK、复核后本地签名、原交易落盘后广播 → 云端独立核验 → 达标且未到期则扣款及记供应商净应收 → 到期按原SUN撤销 → 资源实际恢复后释放地址对占位。
生成器的 `/system/rentXxx` 接口已由 `RentalLegacyGuard` 拒绝,包括读取、导出及写入。这样既防止任意覆盖余额/状态,也防止旧凭证导出接口泄露密文。新页面使用 `/rental`,不要再调用旧CRUD。旧Service/Mapper保留作为已生成基础代码,业务链路不调用其任意修改方法。
### 角色配置与资金账户
角色编码、专属首页及完整接口授权 SQL 见 [角色首页与权限配置](role-permissions.md)。
| 角色 | 需要配置的业务主体 | 资金账户用途 |
| --- | --- | --- |
| 供应商(仅出租) | `rent_node`、节点凭证、本地 Agent 及 `rent_wallet`;无需 `rent_app` | 通过 `rent_account` 记录净待结算收入、退款冲正和结算 |
| 租赁用户(购买资源的商户) | `rent_app`;使用外部 API 时配置应用凭证 | 通过 `rent_account` 记录充值、可用余额、订单冻结和扣款 |
供应商无需手动创建或配置 `rent_account`:当前代码在调度选中供应商时,根据 `rent_node.user_id` 与订单网络自动创建或复用账户,并将其固定到订单的 `supplier_account_id`。这不意味着供应商不需要资金账户记录。
`rent_account` 是平台内部 USDT 账本账户,不是链上钱包,不需要配置私钥。每个用户在每个网络只有一个账户(`user_id + network` 唯一),不按应用或节点单独开立;同一用户可以同时出租和购买资源,共用对应网络的账户。NILE 和 MAINNET 的资金分别记账。完整角色与表关系见 [设计说明](schema-design.md)。
## 2. 数据库、菜单和后端配置
1. 新环境检查MySQL5.7.8+/8.0配置后执行 `sql/rent_init.sql`。已有旧表不能靠 `IF NOT EXISTS` 升级,必须按实际结构和在途数据编写增量迁移;本次未运行脚本。
2. 执行 `sql/rent_menu.sql` 创建租赁工作台、16个运营查询菜单及按钮权限,不自动向任何现有角色授权。通过若依角色管理分配商户、供应商、运营、退款申请人、独立财务审批人。
3. 使用 JDK8;在 Spring Boot 配置中包含 `rental` profile,载入 `application-rental.yml`。通过环境变量注入配置。默认 `RENT_ENABLED=false`,不开调度或节点Socket。
4. `RENT_MASTER_KEY` 必须为外部生成的32字节随机密钥的Base64。不要使用测试代码中的零值密钥,也不要把实际值提交到仓库。`RENT_MASTER_KEY_VERSION` 标识当前版本;当前运行实例必须保留解密历史Secret所需的相同主密钥。本实现不自动迁移主密钥版本,换主密钥前须另行完成离线重封装。
5. 配置 `RENT_NILE_RPC` / `RENT_MAINNET_RPC`、可选 `RENT_RPC_KEY`,以及每个网络的租赁USDT收款地址 `RENT_NILE_DEPOSIT` / `RENT_MAINNET_DEPOSIT`。USDT合约地址复用 `TronServiceProvider.getServiceForNetwork()`,不随支付全局网络切换。
6. 单实例Socket入口启用 `RENT_ENABLED=true`,通过HTTPS反向代理暴露 `/node/v1/socket`。代理保留WebSocket Upgrade,读超时大于45秒,对API及Socket入口设置连接数和速率限制。首版不承诺跨实例Socket路由;数据库持久事实可以多worker争抢,但节点WSS须固定一个入口实例。
可在本地用以下命令生成随机主密钥,仅把输出放入安全配置:
```shell
node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
```
UTC字段使用 `LocalDateTime` 显式按UTC写入,不改变支付业务的LOCAL JDBC连接时区。租赁HTTP响应把BIGINT和USDT转为字符串,防止浏览器浮点数丢精度;时间输出UTC ISO8601,响应设置 `Cache-Control: no-store`。
## 3. 首次开通流程
1. 商户进入租赁工作台,创建应用,开通所需网络的租赁账户,在凭证页为本人APP签发Secret并立即安全保存。充值发到配置的租赁收款地址后,运营填写原USDT交易哈希、Transfer日志序号及精确金额审核;后端独立校验合约、接收地址、金额及确认深度,同一日志不能给不同用户重复入账。
2. 供应商注册节点,运营用不同账号审核通过;供应商为本人NODE创建凭证。节点审核与连接在线是两个不同状态。
3. 供应商绑定公开钱包,TronLink切换到该地址,点击一次性消息验证。挑战绑定平台域、用户、钱包、网络、nonce及有效期;后端恢复地址并原子消费挑战。此步骤不广播、不收取验证费。
4. 运营审核钱包;供应商分别开启能量/带宽出租并设置SUN本金留存。平台不接受钱包私钥。Agent首版只支持owner权限单签,不自动处理多签或自定义active权限;不满足时拒绝执行。
5. 运营新增不可变套餐版本,显式填写正数量、正冗余、租期、售价、供应商毛收入、0至100之间的正手续费率及正费用预算,然后审核上架。改价新增版本,不覆盖旧订单快照。
6. Agent启动且同步完成后节点才ONLINE;对应钱包可信快照有效时才可调度。
## 4. Agent安装与恢复
在 `rent-agent` 目录执行:
```shell
npm ci --ignore-scripts
node --env-file=.env src/index.js
```
复制 `.env.example` 为本机 `.env` 并填写。`.env`、`data` 和 `node_modules` 已忽略提交。私钥只留在本地;日志密钥 `RENT_JOURNAL_KEY` 必须与云端主密钥、API Secret分离。填写本人 `RENT_NODE_ID`、`RENT_NODE_NO`、NODE凭证、网络RPC和本地额度。默认 `RENT_ALLOW_BROADCAST=false`,任务会明确拒绝为未构建;供应商在本地审核后才可改为true并重新启动。平台无法替本地开启广播。
`RENT_MAX_SUN`、`RENT_MAX_FEE_SUN` 为每笔上限;`RENT_ENERGY_ENABLED` / `RENT_BANDWIDTH_ENABLED` 是本地独立出租开关,默认false,需供应商明确开启。关闭某类出租不阻止原授权本金回收,但全局广播关闭仍不广播。两个资源各有留存本金;另有 `RENT_TRX_RETAIN_SUN` 费用留存。Agent查询实时 `getTransactionFee`,用600字节保守预算检查原生交易费用,构建后再次限制实际原文和签名预留不超过预算字节;这是本地预算策略,不是协议的 `fee_limit` 硬上限。SDK无法精确表示的整数超过 `Number.MAX_SAFE_INTEGER` 时直接拒绝,绝不转成不精确数字广播。
本地 `journal.gcm` 保存完整原任务、原签名交易、txId和待ACK事件,使用AES-256-GCM;写临时文件、fsync、原子rename,成功后才ACK或广播。重复任务相同内容只恢复,内容变化拒绝。广播超时、断线、租约过期或重启均不能构造新交易;过期原交易只查询。无已保存交易的BUILDING/UNKNOWN保持隔离,不重新构建。未知不等于失败。
同一数据目录用 `agent.lock` 排除并发进程。正常关闭会先停止接单并等待RPC归档,再释放锁。崩溃保留锁:先确认原进程已退出、只有一套Agent使用该钱包、备份整个加密数据目录,再人工移除该精确锁文件后重启。不得删除日志“重置”任务。丢失日志密钥、签名交易或原Secret时停止接单并核对云端与链上,不按空记录重新执行。
凭证轮换时通过 `RENT_OLD_KEYS` 保留仍有在途任务的旧 `api_key:secret` JSON映射。云端新连接使用当前ACTIVE凭证,历史任务内层意图使用原凭证验签。REVOKED不再投递;历史链上独立核验继续进行。
## 5. HTTP业务接口
所有 `/rental` 接口使用若依JWT及明确 `rent:*` 权限,用户归属由服务端关联查询决定。分页每页50条,页码从1开始。
| 接口 | 功能 |
| --- | --- |
| `GET /rental/mine/{resource}` | 本人的应用、节点、钱包、订单、资金及公开上架套餐 |
| `GET /rental/manage/{resource}` | 运营16表脱敏查询,不返回Secret、签名或挑战 |
| `POST /rental/register/{app,node,wallet}` | 创建本人业务主体 |
| `POST /rental/credential/issue`、`/{id}/revoke` | 凭证轮换、吊销;Secret仅一次展示 |
| `POST /rental/wallet/{id}/{challenge,prove,policy}` | 钱包挑战、TronLink验证和出租策略 |
| `POST /rental/package`、`/status/{resource}/{id}` | 套餐版本创建及运营审核启停 |
| `POST /rental/account/open`、`/account/{id}/topup` | 开户及独立校验充值 |
| `POST /rental/order`、`/order/{id}/cancel` | 订单幂等冻结及未派单取消 |
| `POST /rental/order/{id}/refund`、`/refund/{id}/review` | 退款申请、不同账号审批和内部入账 |
| `POST /rental/settlement` | 按同一供应商同网络的订单净来源建立结算 |
| `POST /rental/settlement/{id}/{approve,reject,pay,unknown,confirm}` | 独立审批、原付款授权及核验;PAYING/UNKNOWN不可拒绝释放 |
| `POST /rental/wallet/{id}/refresh`、`/task/{id}/verify` | 可信快照和原交易独立核验 |
| `POST /rental/task/{id}/attach` | 只给原在途任务补充已独立核对的原交易哈希 |
| `POST /rental/order/{id}/resolve` | 仅MANUAL_REVIEW、HELD且回收DONE的异常单可解冻终结 |
| `POST /rental/webhook/{id}/retry` | 人工修正配置后重新投递DEAD事件,原编号和业务内容不变 |
| `GET /rental/reconcile?afterId=0` | 分批核对余额与不可变流水、钱包SUN预留与任务占用 |
每天UTC02:00自动进行账账核对,发现差异只告警,不直接修复余额或释放未知本金。运营可在资金账户/流水页主动执行完整分页核对。
结算 `pay` 先持久化唯一 `payout_no` 及本次收款地址,再由人工付款;重试返回原授权,不产生新的付款。`confirm` 根据原授权收款地址、账户网络及精确USDT金额核对原交易日志。后端不自动对外出金。
## 6. 外部商户签名接口
`POST /api/rental/v1/create`、`query`、`packages`,仅JSON,最多64KiB,不允许查询串。请求头为 `X-Rent-Key`、`X-Rent-Timestamp`(Unix毫秒)、`X-Rent-Nonce`、`X-Rent-Signature`。认证窗口前后60秒,nonce保留180秒后可清理。
签名原文用换行连接,末尾不加换行:
```text
RENT_HMAC_SHA256_V1
API
api_key
timestamp
nonce
POST
/api/rental/v1/create
SHA256(实际UTF-8请求体)的小写十六进制
```
使用Secret做HMAC-SHA256,输出小写64位十六进制。scope为API/NODE/TASK/WEBHOOK,不能互换;不共用支付MD5。下单字段:`package_id`、`merchant_order_no`、`receiver_address`,可选 `notify_url` 和与套餐一致的 `resource_type`。APP和用户从凭证推导。`query` 用 `merchant_order_no`;`packages` 用 `network`。
跨语言固定向量:Secret=`test-secret`、scope=`API`、key=`test-key`、timestamp=`1700000000123`、nonce=`abcdefghijklmnop`、method=`POST`、path=`/api/rental/v1/create`、body=`{"amount":"1.000000"}`,结果为 `47241a34f0813881384317eafbfc068dc9f7c6061a8fe269cb815e7820d48430`。此值仅用于测试,不是有效运行凭证。
回调使用相同请求头但scope=WEBHOOK;仅HTTPS公网443、无用户信息/fragment/query,实际DNS连接地址逐个检查,不跟随重定向。HTTP200且正文精确为 `ok` 才确认。最多10次,失败指数退避,终止为DEAD;每次新timestamp/nonce,业务event_no、payload和订单事件序号不变。商户按event_no去重并按序号识别乱序。无回调地址的事件直接确认,不发HTTP。
## 7. WSS协议与历史资源证明
通道 `/node/v1/socket`:CHALLENGE → AUTH → 签名AUTH_OK → 分页SYNC_STATE/SYNC_ACK → ONLINE。未同步不得接新单。外层帧的 `body` 是原始JSON字符串;信封含 `api_key,timestamp,nonce,body,signature`,NODE域、method=FRAME、path固定。body含type、方向、session_id、session_epoch、sequence、message_id、payload。双方向序号各自从1递增。每15秒签名PING/PONG,45秒超时断开,nonce重复或旧会话帧拒绝。
TASK_PUSH中保留稳定delivery_message_id、原api_key/intent/timestamp/nonce/signature。TASK域、method=PUSH、path=`/node/v1/task`。任务intent为按键排序的紧凑JSON;任务字段只含ASCII字符串/布尔值。MySQL JSON规范化后由后端按同一规则重建,再传输原意图,不改变授权内容。
Agent事件先落本地可靠队列,云端同事务以 `NODE:nodeId:eventId` 去重后RESULT_ACK。ACK只说明持久接收,ACCEPTED只说明本地接受,BUILT/BROADCASTED/RESULT只说明执行线索。云端另查交易合约、owner/receiver、网络、资源类型、非锁定、SUN、回执、确认深度和关系,不能凭节点消息扣款。
普通TRON RPC没有任意确认区块的资源历史查询,因此自动交付核验要求 `RENT_NILE_HISTORY` / `RENT_MAINNET_HISTORY` 指向运营自行部署、独立于供应商的可信历史证明服务。后端向 `/rental/resource-proof` POST `network,tx_id,block_height,owner,receiver,resource_type`,服务必须基于该实际区块状态返回:
```json
{"tx_id":"原交易哈希","block_height":123,"baseline_sun":0,"after_sun":1300000000,"total_limit":60000000,"total_weight":1000000}
```
示例参数不代表当前链。证明服务是外部基础设施契约,仓库没有伪造历史状态或用当前L/W替代的实现。**未配置历史服务时,可以确认真实委托,但订单转MANUAL_REVIEW、保留HELD资金并按原SUN回收,不自动记SUCCESS或供应商收入。** 交易已确认而交付不足、核验时已过期,同样人工隔离。可在确认回收DONE后通过受保护的resolve解冻。外部擅自变更委托关系会告警并转人工,不能任意释放关系占位。
## 8. 验证与边界
具体命令、结果及尚未验收的外部条件见 [validation-implementation.md](validation-implementation.md)。
已提供后端 `RentalBusinessTest` 与 Agent `test/agent.test.js`,分别覆盖资金/并发/状态机/协议和本地加密持久化/原交易恢复。H2测试从权威16表DDL只替换H2不支持的存储及JSON声明,保留字段与唯一键;不等同真实MySQL并发验收。Socket测试使用可控会话,不等同公网TLS/半开连接验收。前端构建输出到独立目录,不覆盖现有dist。
未接入项目数据库、实际部署WSS、真实TronLink浏览器签名、NILE委托/回收或历史证明服务进行联调;这些必须在专用测试环境验收后再启用业务。本实现不自动开放主网广播、不自动建设历史节点、不自动出金。