155 lines
17 KiB
Markdown
155 lines
17 KiB
Markdown
# 租赁模块三端实现与运行说明
|
||
|
||
用户套餐绑定增量:核心表新增 rent_user_package,管理员授权具体套餐版本;应用按 user_id 选择已绑定套餐,省略 package_id 自动选择默认。部署前执行增量表SQL并配置用户绑定,见 [用户套餐绑定与脚本](user-package-bindings.md)。历史订单和在途处理不受绑定变更影响。
|
||
|
||
本文对应当前工作区的 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连接、双向签名心跳、加密可靠日志、钱包本地限制、只构建签名一次、原交易恢复 |
|
||
| 本地 JavaFX Agent(替代实现) | `rent-agent-java/src` | JDK17 + JavaFX20.0.2,使用同一节点协议;桌面启停、广播确认、本地签名与原交易恢复 |
|
||
|
||
供应商可选择 Node.js 24 + TronWeb 6.0.4,或独立的 JDK17 + JavaFX20.0.2 桌面Agent。Java版安装、配置与验证见 [Java Agent README](../../../rent-agent-java/README.md),不依赖Node运行时,不修改示例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没有任意确认区块的资源历史查询。现已增加与云端同进程部署的内置历史采集/证明服务:执行 `sql/rent_history_init.sql` 增加4张历史表,设置 `RENT_HISTORY_EMBEDDED_ENABLED=true` 和 `RENT_HISTORY_NETWORKS=NILE`。派单前采集确认关系基线,持续归档确认区块和资源参数,交付核验直接调用Java服务;不需要填写 `RENT_NILE_HISTORY` / `RENT_MAINNET_HISTORY`。表设计、接口、配置、采集缺口与部署详见 [内置历史证明服务](history-service.md)。
|
||
|
||
外部服务模式继续兼容:内置关闭时,`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}
|
||
```
|
||
|
||
示例参数不代表当前链。内置实现从启用时开始保存真实确认状态,不会补造上线前或停机期间漏采的全网参数。**未配置历史服务,或内置服务缺少该高度参数/派单前基线时,可以确认真实委托,但订单转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委托/回收或历史证明服务进行联调;这些必须在专用测试环境验收后再启用业务。本实现不自动开放主网广播、不自动建设历史节点、不自动出金。
|