Files
usdt/docs/rental/schema-design.md
T

328 lines
42 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
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,按系统用户+网络+资源类型绑定当前套餐;已有库先执行 sql/rent_user_package_scope.sql;下单从应用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)。下文“本次仅设计”描述设计审查阶段,不替代当前实现记录。
## 1. 简化范围和保留边界
本版采用以下明确设计假设:同时出租Energy和Bandwidth,固定套餐,一单一种资源、一个供应钱包,全额交付、单币种USDT内部记账;供应商自行质押并提供可委托本金,平台不替其质押。一个钱包首版只绑定一个Agent,Agent通过主动出站WSS长连接收取任务并上报,具有双向心跳和断线恢复,不再长轮询领取。套餐价格和供应商成本由运营预先配置,无独立报价流程。
登录、Google、用户、角色、菜单和按钮权限沿用若依sys_*体系,不增加成员/角色表。租赁应用、凭证、订单、资金和任务独立,不复用支付apps、orders、wallet_address或余额。通过现有TRON查询service获取链上事实,业务调度、交易执行和核验编排独立。
首版暂缓动态报价、多级代理佣金、自动续租、复杂供应商竞价、自动链上充值识别和自动出金。人工充值审核和供应商结算仍必须有依据、去重、余额流水及审计;未来需要这些功能时再增量扩展,不能把暂缓功能隐含进JSON自动执行。
保留供应商本地密钥、默认禁止广播、链上独立核验、订单幂等、原交易恢复、未知状态隔离、资金冻结、资源预留、到期回收、回调持久队列和不可变流水。
### 参与角色与应用、节点、资金账户
“租赁用户”指购买资源的商户;“供应商”指提供质押资源的一方。两种身份均依托若依 `sys_user`,同一用户可以同时承担两种角色。
| 表 | 仅出租资源的供应商 | 购买资源的租赁用户(商户) |
| --- | --- | --- |
| `rent_node` | 需要,代表供应节点并连接本地 Agent;通过 `user_id` 归属供应商 | 不需要;同时经营供应业务时才需要 |
| `rent_app` | 不需要;同时购买资源时才需要 | 需要,承载订单归属、应用 API 认证和回调 |
| `rent_account` | 需要,记录供应商待结算收入、退款冲正和结算 | 需要,记录充值余额、订单冻结和扣款 |
`rent_account` 是平台内部 USDT 账本账户,不是链上钱包,不存储私钥,也不按应用或节点分别开立。账户按 `user_id + network` 唯一;同一用户兼任商户和供应商时,共用同一网络下的账户,NILE 与 MAINNET 分开记账。
供应关系为 `sys_user → rent_node → rent_wallet`;供应钱包用于提供链上资源,本地 Agent 保管私钥。供应收入根据节点所属用户及订单网络定位 `rent_account`。当前实现在调度选中供应商时自动创建或复用该账户,因此供应商无需手动配置资金账户,但数据库仍须保留账户记录以完成收入及结算记账。不能将“不需要手动配置”理解为“不需要这张表”。
## 2. 16张表及职责
以下为业务核心16表。内置历史证明复用4张采集/审计证据表,另有1张 `rent_history_sample` 保存待确认参数,独立增量安装,详细字段及协作见 [内置历史服务表设计](history-service.md) 和 [历史DDL](../../sql/rent_history_init.sql)。按该业务核心口径合计21张,不修改原16表结构。待确认缓冲不用于直接结算,确认并核对哈希后提升至证据表。
| 表 | 作用 |
| --- | --- |
| rent_app | 独立商户应用,user_id关联sys_user |
| rent_credential | APP/NODE统一api_key与加密api_secret,轮换保留历史 |
| rent_nonce | HMAC认证域内防重放 |
| rent_node | 供应商节点、审核、心跳,直接关联供应商sys_user |
| rent_wallet | 公开钱包授权、能量/质押带宽可信快照、按资源类型隔离的可委托SUN与预留 |
| rent_package | 固定套餐版本、数量、时长、USDT售价、供应商应付及费用约束 |
| rent_account | 用户在某网络的可用USDT、冻结USDT及供应商待结算USDT |
| rent_order | 下单、价格快照、履约、退款累计、租期和回收调度 |
| rent_task | 委托/回收执行任务、重试历史、原子资源占用和持久队列 |
| rent_transaction | 任务唯一链上交易与回执、关系增量和独立核验 |
| rent_ledger | 不可变余额变更流水与业务幂等键 |
| rent_settlement | 人工供应商结算审核及付款证据 |
| rent_settlement_item | 每个订单的供应商应收只能结算一次 |
| rent_refund | 内部余额退款审批、业务幂等、费用承担及逐次退款来源 |
| rent_webhook | 订单事件回调持久队列 |
| rent_event | 关键操作、状态转换及节点消息去重的追加审计 |
简化方式:供应商不再单独建档(使用节点user_id);产品、规则和报价合并为不可变版本套餐;快照/资源池合并到钱包,预留明细合并到任务;委托关系与回收调度放订单和任务,链上证据独立;资金采用余额+不可变流水,不建设整套复式会计总账;业务任务表和回调表直接作可靠队列,不额外建设消息中间件与通用Outbox。
### 资源类型与字段约定
- rent_package、rent_order、rent_task、rent_transaction均有resource_type,允许ENERGY或BANDWIDTH,不设默认值;套餐、订单、任务及实际链上类型必须一致。
- 套餐、订单、任务使用resource_quantity正整数:ENERGY单位Energy,BANDWIDTH单位bytes;不再使用energy_quantity。单位由类型唯一确定,不另存可冲突的单位字段。
- 每个套餐及订单只租一种资源;同一用户需要两种资源时分别下单,价格和供应商应付独立配置。套餐同一package_code各版本不允许变换资源类型,新类型使用新代码。
- 钱包保留energy_available并增加bandwidth_available(仅可出租质押带宽,不含免费带宽)。energy_enabled/bandwidth_enabled独立开关,默认关闭。
- 能量本金字段为energy_delegatable_sun、energy_reserved_sun、energy_retain_sun;带宽对应bandwidth_delegatable_sun、bandwidth_reserved_sun、bandwidth_retain_sun。同一钱包行锁串行修改,只更新本任务的资源类型字段;未知能量任务不占用带宽本金,反之亦然。
- total_energy_limit/weight及total_bandwidth_limit/weight分别表示各自全网额度/权重,使用同一时点可信快照;两类快照未完整成功时不推进共同snapshot_at/expires_at,失败不能用零值覆盖另一类型占用。
- 链上BANDWIDTH的resource_code=0,ENERGY=1;免费带宽不可委托,账户普通TRX余额、收到代理量均不能直接视为可出租本金。RECLAIM必须使用原委托的resource_type和对应SUN,不能撤销另一类本金。
- HMAC意图、下单摘要、商户查询、回调、管理列表及审计都须明确资源类型和数量;内部统计按类型分组,不把Energy数量和bytes相加。
- 任务唯一键仍按order_id/task_type/active_slot,因为一个订单只含一种资源;钱包地址唯一键保持(network,address),不为两类资源重复创建钱包。
- V2.2 订单以 `(wallet_id,receiver_address,resource_type,relation_slot)` 限制同地址对同类型只有一笔在租或待回收订单,任务以 `(wallet_id,resource_type,wallet_execution_slot)` 限制同钱包同类型只有一个在途操作。两个占位均只能为 1 或 NULL;未知不可释放。不同接收者可分别在租,但同钱包同类型的链上操作串行。
- 钱包 `snapshot_block_height / snapshot_min_block_height` 配合 version CAS 防止旧快照覆盖。确认交易、释放预留与快照失效屏障同事务;获取新快照前不能再调度。详细顺序见复核说明第 3 节。
- 首版仅 `delegate_lock=0` 非锁定 Stake 2.0 委托,套餐 rules 和任务 intent 必须一致。不得直接复用现有 NILE/MAINNET 通用 `delegateResourceV2`(写死 `lock=true,86400` 且直接签名广播)。租赁只复用只读查询,本地 Agent 自行构建、持久化再广播。
### 请求资源量、冗余和委托TRX换算
链上Stake 2.0委托提交的是该资源类型对应的质押等值TRX本金,接口单位SUN,不直接提交Energy或bytes,也不是将TRX转账给接收人。Energy和Bandwidth必须使用各自当前网络总额度及权重,禁止固定TRX/资源汇率。
设Q为用户请求resource_quantity,R为锁定的redundancy_percent(20表示20%),L为该类型当前全网资源总额度,W为该类型当前全网总权重(协议的TRX权重单位,不是SUN):
```text
目标资源量 T = max(Q + 1, ceil(Q × (1 + R / 100)))
委托TRX本金 P = ceil(T × W / L)
委托SUN本金 S = P × 1,000,000
预计可交付资源 E = floor(S × L / (W × 1,000,000))
必须满足:Q > 0,R > 0,L > 0,W > 0,E >= T > Q
```
本版选择按整TRX向上取整,是避免不足的业务保守策略,不声称链上只能接受整TRX;若未来支持更细SUN步长,必须另定精度策略并验证节点最小委托限制及实际资源映射。公式使用BigDecimal/BigInteger和显式CEILING/FLOOR,中间乘积不能用long直接相乘或double;转换为BIGINT入库前执行精确范围检查。Q+1也必须检查溢出。
示例仅用于说明计算,不是当前网络价格:Q=65000 Energy,R=20%,T=78000;若当时L/W=60 Energy/TRX,则P=1300 TRX,S=1300000000 SUN,E=78000。带宽Q=1000 bytes、R=20%,若当时L/W=1.5 bytes/TRX,则T=1200、P=800 TRX。两种比例均从实时网络取得,不能把示例常量写入代码。
冗余仅放大用户购买的资源额度,不凭空增加同额TRX费用预算,也不自动扩大商户计价数量。固定套餐仍按resource_quantity收取快照售价,供应商成本和费用限制须已覆盖冗余;不能因实时换算需要更多本金而绕过本地额度/费用上限。Q表示本次应委托增加的资源量,不默认减去接收地址已有可用资源。
字段分工:套餐保存resource_quantity和默认20%的redundancy_percent;订单锁定二者及target_resource_quantity;任务保存原请求、冗余目标、换算参数/区块/时间、estimated_resource_quantity和delegate_sun;链上交易保存实际amount_sun、verified_total_limit/weight和verified_resource_quantity。TRX展示从SUN用BigDecimal除1000000得到,不额外存一份可冲突的本金TRX字段。
任务生成前可信查询L/W及可委托本金,按S而非未加冗余的估算量预留对应类型SUN。Agent签名前再次查询L/W、可委托额度、链上限制和费用:若原任务S已不足覆盖T,明确未构建/广播时拒绝旧任务并释放旧占位,由云端重新计算、预留、签发新attempt;Agent不可悄悄改大已签HMAC的S。原任务已构建/广播或结果未知时只按原交易恢复,不重签或新建一笔补额交易。
云端在确认区块用实际amount_sun与该区块L/W核验资源额度及链上委托增量,必须满足verified_resource_quantity >= T > Q才可结算成功。这里核验的是本单委托所对应的资源额度,不是接收方瞬时可用余额差;后者会受已有委托和并发消费影响,不能直接当作本单交付。
交易已成功但参数变化导致不足T时,不回滚链上事实、不将其标为未执行失败,不释放已委托本金、不重复委托;订单进入MANUAL_REVIEW并保留资金,按原确认SUN追踪回收,经审核选择撤销/退款等处置。首版不自动补委托以维持一单一笔成功委托的模型。冗余只是确认时的交付缓冲,不保证租期内全网参数永不变化,不能承诺资源额度恒定。
撤销以原已确认amount_sun为准,保持同资源类型,绝不能按到期时L/W重新换算原resource_quantity,否则可能多撤或少撤。RECLAIM任务的换算字段仅复制原委托审计快照,不用于决定撤销SUN。发生本金已委托但订单未成功的异常也必须进入回收扫描,不能仅扫描SUCCESS订单。
## 3. 业务流程示意图
```mermaid
flowchart TD
A["商户选择能量或带宽固定套餐并下单"] --> B{"HMAC、幂等、余额校验"}
B -->|不通过| X["拒绝请求"]
B -->|通过| C["事务:创建订单、冻结USDT"]
C --> R["请求数量加正冗余,得到更大的目标量"]
R --> D["按当前资源参数换算TRX并向上取整,预留SUN"]
D --> E["本地Agent复核额度并签名广播"]
E --> F{"云端独立核验链上结果"}
F -->|明确最终失败| G["释放冻结资金与预留资源"]
F -->|明确未执行且允许重试| V["释放旧资源占位,保留冻结资金"]
V --> D
F -->|结果未知| H["保持占用,查询原txId或人工核对"]
H --> F
F -->|确认且资源额度覆盖冗余目标| I["事务:扣款、供应商应收、回调入队"]
F -->|已委托但额度不足或核验已到期| U["人工核对、保留资金及本金记录,不重复委托"]
U --> K
I --> J["商户使用能量或带宽"]
J --> K["租期结束,生成撤销任务"]
K --> L["Agent撤销,云端核验"]
L --> M{"本金回收且资源恢复?"}
M -->|未恢复或被锁定| N["等待链上条件并告警"]
N --> L
M -->|是| O["回收完成,资源可再次出租"]
I --> P["运营人工审核供应商结算"]
```
### 3.1 开通与充值
1. 用户通过共用系统登录,运营在系统角色/菜单中授予rent:*权限。商户创建rent_app,获取独立API凭证;供应商创建rent_node并申请钱包接入。
2. 供应商在平台通过TronLink完成一次性消息签名验证,后端恢复的地址必须与待绑定地址一致;不要求发送链上证明交易或支付验证费用。运营审核与链上委托权限检查另行执行,未通过验证和审核的钱包不可接单。
3. 供应商Agent配置自己的钱包、留存本金/费用上限,默认广播关闭。人工确认后在本地允许广播;平台无法替节点打开。
4. 商户提交充值依据,运营通过受保护接口审核,原子增加rent_account.available_amount并追加TOPUP流水及rent_event。TOPUP的business_key使用规范化唯一充值凭据,例如TOPUP:network:txid:logIndex,唯一约束阻止同一凭据给不同用户重复入账。币种仅USDT且网络必须一致,凭据必须独立核验;不以截图作为到账真相。此版无待审充值单表,未审核请求不先增加余额。
### 3.2 下单与调度
TronLink钱包验证的完整规则见下方“TronLink钱包控制权验证”;下单仍使用原有HMAC或系统登录认证。
1. 请求提交network、resource_type、merchant_order_no、receiver_address(禁止提交package_id,由服务端按用户与分类匹配套餐),可指定回调URL。应用/用户由认证结果派生。查同一(app_id,merchant_order_no),相同规范化摘要返回原单,不同摘要拒绝。
2. 事务内锁套餐及账户,校验上架、网络、价格、地址和余额,保存订单/规则快照:可用减售价、冻结加售价,写HOLD流水和订单WAITING。同事务写状态审计。套餐改价新增revision,旧行不直接改金额。
3. 后台扫描WAITING并条件抢占。按锁定正冗余比例计算target_resource_quantity,再选在线、审核通过且快照有效的供应钱包,以当前该资源L/W换算整TRX向上取整后的delegate_sun。预计资源必须覆盖冗余目标,并保存完整换算快照;Energy和Bandwidth参数不能混用。
4. 事务内锁订单与钱包,按订单 resource_type 检查对应 delegatable_sun-retain_sun-reserved_sun 足够,取得地址对占位和钱包执行占位,固定 supplier_account_id,仅增加该类型 reserved_sun、创建 DELEGATE 任务并置订单 EXECUTING。任务显式保存 network,意图固定网络、类型、数量、地址、本金、非锁定参数、期限、费用和目标节点。签名前还须核验接收账户可委托条件及同类型地址对基线为零。
5. 创建订单时将等待上限固化为 dispatch_deadline,任务 deadline 不得晚于它。WAITING 超时且从未生成任务时取消并解冻。已投递的任务不因截止或断线被推定未执行;查原交易并隔离。明确未执行的可重试任务在截止前保留商户 HELD 资金,释放旧任务及地址对占位后重新调度;终结失败才解冻。用户仅可取消从未生成执行任务的 WAITING 单,取消与调度锁同一订单行裁决。
### 3.3 委托与确认
1. Agent持久化接单,验HMAC及本地授权/资源/费用,实时检查可委托额度;拒绝可返回明确未执行结果。
2. 本地仅构建签名一次,先持久化原签名交易及txId再广播;任何重试先查原txId,不重签另一笔交易。云端租约过期不能证明未执行。
3. 云端独立检查网络、owner、receiver、资源类型(ENERGY或BANDWIDTH)、SUN、回执、确认深度、委托前后差异;节点自报成功及HTTP200均不代表成功。
4. 确认成功后同事务:订单 SUCCESS、fund_status=CHARGED,冻结余额减售价;供应商先记 SUPPLIER_EARN 毛收入,再记 SUPPLIER_FEE 扣费,待结算净增加 supplier_net_amount;流水、审计和 SUCCESS 回调原子提交。service_started_at 使用独立核验交易的 block_time,service_expires_at=起点+租期;核验延迟不得延长租期。核验时已到期或无法取得足够历史证据则转人工核对,不静默扣款。多账户按 account_id 升序加锁,同账户只锁一次。
5. 链上事实确认即将对应委托预留转 COMMITTED 并扣除 reserved_sun,提升钱包 snapshot_min_block_height 至确认区块,令 snapshot_expires_at=NULL,再释放任务 wallet_execution_slot;与订单是否达到交付目标分开处理。后台按版本和区块屏障应用新的可信快照,之后才可接新任务;不能沿用旧值或先释放后异步补屏障。
6. 明确未执行的可重试失败只释放资源并重新调度,不写终态 FAILED 回调或解冻;决定最终失败时才同事务释放冻结、写 RELEASE 和 FAILED 回调。UNKNOWN 保留占位及预留,扫描任务及交易的 next_check_at;即使没有 txId 也必须扫描任务恢复,不能只扫描交易表。未知不能改钱包。已构建交易只有证实链上失败或超过原交易有效期且独立确认未上链才可重试;未找到一次、租约超时或 Agent 丢记录都不算证明。
### 3.4 到期回收
1. 业务服务到期只生成RECLAIM任务,不改已成功的履约状态,不自动退租金。
2. Agent查询实际锁定及可撤销量,按链上规则撤销;云端确认撤销交易后仍需核对资源实际恢复。
3. 首版同钱包、同 receiver、同类型仅允许一笔占位订单,拒绝存在该类型外部委托基线的钱包地址对;同地址对的下一笔单排队或选择其他钱包。RECLAIM 的 source_transaction_id 必须指向本单原确认 DELEGATE;仅撤销原 amount_sun。回收任务 reservation_status=NONE,不新增可委托本金预留,但要取得钱包执行占位。部分可回收或关系变化转人工,不撤销他人份额。
4. 链上仍锁定则 next_reclaim_at 等待;未知保留执行占位。撤销确认后更新快照区块屏障并失效旧快照,再释放执行占位;本金已回收但资源未恢复为 RECOVERING,按新的 getCanDelegatedMaxSize 及资源使用证据核对,不机械等待数值回到旧快照。确认本单恢复后才置 DONE 并释放订单 relation_slot。回收未发起前也要持久化 next_reclaim_at,不能遗漏异常委托。
5. active_slot保留成功DELEGATE任务用于定位原始SUN和链上证据;RECLAIM任务独立占位,不能把履约与回收混成一个status。
### 3.5 人工结算与退款
### 供应商手续费
平台在订单链上履约核验成功、订单转SUCCESS时向供应商扣取手续费;不在下单冻结、节点自报、未知状态、到期回收或结算付款时重复收取。商户售价不因此额外增加。套餐显式配置supplier_fee_percent(百分数,5代表5%),不擅自指定实际费率;下单锁定费率及金额,后续调费新增套餐版本,不改历史订单。
```text
供应商毛收入 G = supplier_amount
平台供应商手续费 F = round(G × supplier_fee_percent / 100, 6, HALF_UP)
供应商净应收 N = G - F
必须满足:0 < 费率 < 100,0 < F < G,N > 0,G <= 商户售价
```
例如毛收入10 USDT、配置费率5%,则平台手续费0.5 USDT、供应商净应收9.5 USDT。5%仅为示例,不是初始化默认费率。若极小金额舍入后手续费为0,拒绝启用套餐/创建订单,不能无提示按0收费或额外收最低费。
同一成功事务写两条供应商rent_ledger:SUPPLIER_EARN的delta_supplier_pending=+G、delta_platform_fee=0;SUPPLIER_FEE的delta_supplier_pending=-F、delta_platform_fee=+F。分别使用包含订单与事件类型的唯一business_key;只有首次成功状态转换可记账,重复扫描/回报不能再次扣费。三种余额的after值按两条流水顺序连续保存,事务提交后净增加N。平台手续费事实以不可变流水delta_platform_fee累计,不将其放入用户可用余额;这是简化收入统计,不是另一个可提款账户。
平台经营统计分别展示商户售价、供应商毛收入、供应商手续费、净应付和售采差价。平台总服务收入为商户售价减G再加F(仍需另计实际其他成本),不能将F重复加进已经按售价减N计算的收入。
结算来源金额为 supplier_net_amount-supplier_reversed_amount+supplier_fee_returned_amount,不能使用原 supplier_amount 或再次扣手续费。失败及未执行取消不计应收不抽手续费;已委托但资源不足的人工核对单也不能提前收取。
每次退款先创建 rent_refund,以 (order_id,request_no) 和 request_hash 幂等。只处理已 CHARGED 且已确认收入的订单。PENDING 不改余额;独立审批时重新校验累计金额,APPLIED 与订单累计、余额、各事件流水及退款回调同事务。分别保存商户退款额、供应商原净额冲正、平台手续费退回额及 fee_return_to。手续费退商户时已经包含在 refund_amount,不得再次加余额;退供应商时增加待结算及 supplier_fee_returned_amount。手续费退回累计不超过原手续费,原净额冲正累计不超过 supplier_net_amount,商户退款累计不超过售价。fee_return_to=NONE 当且仅当手续费退回为零;退商户手续费不得大于本次退款额。若来源已结算或已被结算占用,涉及供应商或手续费变化的退款不得应用;商户单方由平台承担的退款可单独审核。无外部退款出金。
结算发起时锁供应商账户及订单来源,检查订单SUCCESS、已核验、净应付未被占用;rent_settlement_item的(order_id,active_slot)唯一。结算金额按订单净应付汇总,不能超过账户待结算余额。结算审核不提前减少待结算,所有已占用来源都禁止再入其他结算单。
人工付款前先将 APPROVED 条件更新为 PAYING,持久化唯一 payout_no、payment_started_at 及审计,提交后才允许出款。付款后独立核验凭据,再同事务扣待结算、写 SETTLE、标记 PAID 并审计。PAYING/UNKNOWN 禁止普通拒绝、释放明细或重新出款;恢复时查询原 payout_no 和凭据。只有独立核验明确未付款且原授权已作废后,才可审核拒绝并释放来源。payment_reference 全局唯一。创建、审批职责分离,首版每来源整笔结算。
普通执行失败是解冻,不叫退款。退款按锁定规则和上述退款单审批执行,禁止制造负应付或修改已付历史。每次部分退款产生独立 event_key=REFUND:refund_no;回调不再按 (order_id,event_type) 唯一,而按业务事件键及订单事件序号唯一,避免第二次退款无法通知。
结算拒绝、退款及调度恢复都必须写审计,不能仅手工UPDATE数据库余额。
## 4. 状态和必须执行的约束
- 履约order.status:WAITING → EXECUTING → VERIFYING → SUCCESS;失败/取消明确终态FAILED/CANCELLED,结果不确定MANUAL_REVIEW。任务UNKNOWN不直接映射FAILED。
- 资金fund_status:HELD → CHARGED或RELEASED;退款累计refunded_amount另记,不覆盖原扣款事实。
- 回收reclaim_status:NOT_STARTED → WAITING → RUNNING → RECOVERING → DONE;异常MANUAL_REVIEW。
- 任务status:PENDING → ACCEPTED → BROADCASTED → VERIFIED,另有REJECTED/FAILED/UNKNOWN;任务类型DELEGATE/RECLAIM。
- 关联记录的network必须一致,用户id逻辑关联sys_user。API权限不等于数据归属,所有操作校验app.user_id或node.user_id,管理操作另查rent:*权限。
- available/frozen/supplier_pending均不得负数。余额变更、流水、状态、回调和审计同事务提交;相同business_key不重复变动余额。
- 不可变流水记录三种余额的正负增量及变更后值,可根据历史重建;不冒充双重记账总账。每日校验冻结合计与HELD订单、供应商待结算与未结应付、余额投影与流水。差异记录在rent_event并人工核对,不静默补差。
- 云端扫描数据库持久任务后经节点WSS连接推送,回调仍由数据库队列重试;数据库扫描是云端内部恢复机制,不是Agent长轮询。按状态/version及worker租约条件更新,先验证租约再落结果;Socket只负责传输,任务状态与节点本地持久化才负责副作用幂等。
- 一个任务唯一交易,(network,tx_id)全局去重;task(node_id、credential_id)和钱包节点归属必须一致。节点事件用rent_event.event_no唯一键原子去重,相同事件编号不同内容必须拒绝。
- HMAC通过后原子预留nonce;业务幂等与nonce是两种约束,重试新nonce、原merchant_order_no。云端定时任务都需限流、分页、超时及显式关闭。
- 所有表和字段有COMMENT;日期UTC DATETIME(3),金额DECIMAL(30,6),使用BigDecimal;MYSQL5.7跨表约束必须应用落实。禁止记录Secret、私钥及口令。
## 5. HMAC规则与共享权限
### TronLink钱包控制权验证
此流程是用户明确指定的钱包验证例外:使用TRON原生消息签名证明地址控制权,不引入RSA、公钥认证表,也不改变API/节点/任务/回调的HMAC体系。签署消息不是链上交易,不广播、不转账、不收链上手续费,平台不索取私钥、助记词或钱包密码。
1. 已登录供应商进入钱包绑定页,连接TronLink并获取当前地址,选择NILE或MAINNET。平台检查rent:*权限、node.user_id归属及(network,address)唯一性;Base58格式不能区分网络,网络必须作为独立声明和后续RPC校验条件。
2. 后端生成至少32随机字节的nonce和建议5分钟有效期,保存到rent_wallet的ownership_challenge、ownership_message及签发/到期字段。文本应可读,明确写明“仅验证钱包控制权,不授权转账或委托”,并包含固定协议版本、受信任站点域名、登录user_id、wallet_id、network、address、nonce、签发及过期UTC时间。站点域名来自受信任配置,不盲信请求Host。nonce不得由客户端指定;重新签发前将旧记录写rent_event,再覆盖当前挑战并清空本次签名和消费状态。
3. 前端将后端返回的原文原样传入TronLink提供的tronWeb.trx.signMessageV2(message),不预先SHA256、不二次hex编码,不使用sign交易接口或旧signMessage接口替代。签名前后核对当前连接地址与目标地址一致;用户拒签、钱包锁定、账户切换或不支持该版本时显示明确错误,不自动降级到其他签名协议。
4. 前端只提交wallet_id、challenge及signature,后端读取已保存原文,校验登录归属、当前地址/网络、有效期及未消费。Java后端使用与TronWeb verifyMessageV2相同的TRON消息前缀、UTF-8字节长度和签名恢复规则,恢复Base58Check地址并严格比较address;不能仅接受前端验签布尔值。JDK8实现应选兼容库并用TronLink真实样本及跨语言向量验证,不能假设Ethereum personal_sign直接兼容。
5. 验签通过后以当前challenge、version及未消费状态做条件更新,原子保存signature、恢复地址、ownership_verified_at和challenge_consumed_at,并写rent_event。同一挑战只接受一次;并发仅一方成功,重复完成请求可返回既有验证状态,但不再次产生授权或审核副作用。旧nonce、过期、改原文、跨用户/钱包/域/网络的签名均拒绝。
6. 服务端验证当前账户的链上委托权限、本金和网络状态,运营确认后才将钱包设为ACTIVE。地址签名通过仅说明该地址密钥控制能力,不保证质押资源充足、Agent拥有足够的Active Permission,也不证明TronLink实际连接网络;多签/权限密钥不能恢复为目标owner时首版明确拒绝,后续需专门设计多签证明,不能绕过校验。
7. 已验证钱包更换地址或网络必须新建/重新验证并先处理在途任务;禁止直接修改已承载订单的钱包地址。认证签名原文与结果作为公开证明数据仍应仅向所属用户/运营展示,日志只记录必要标识和摘要。
建议接口(共用系统登录与权限,不要求为网页再签一次API HMAC):POST /system/rental/wallet/{id}/challenge、POST /system/rental/wallet/{id}/verify。前者返回message/challenge/expires_at/签名版本,后者返回验证状态和恢复地址;不提供私钥输入框。前端增加连接、签名中、验证成功、拒签/过期/账户切换状态。
```mermaid
sequenceDiagram
participant U as 供应商
participant P as 平台网页
participant T as TronLink
participant S as 后端
U->>P: 登录并绑定钱包地址
P->>S: 申请一次性挑战
S-->>P: 完整原文、nonce、有效期
P->>T: signMessageV2(原文)
T->>U: 展示原文并请求确认
U->>T: 确认签名
T-->>P: 消息签名
P->>S: 提交挑战与签名
S->>S: 验签恢复地址、检查归属与有效期
S->>S: 原子消费挑战并保存验证结果
S-->>P: 钱包验证成功,等待审核/权限核验
```
旧版若已建ownership_tx_id,仅为旧链上证明字段,不直接当成TronLink验证结果;按实际数据做增量迁移,新验证字段先置空并要求新挑战。旧供应商在途任务保持可核对,不自动将旧签名或历史交易转换为本次签名证明。当前仅修改初始化DDL设计,未执行数据库迁移。
统一rent_credential:APP主体owner_id为rent_app.id,NODE为rent_node.id;新版本生成新api_key/api_secret,保留旧行。Secret仅在受认证TLS通道创建时展示一次,云端保存AES-GCM封装,主密钥在外部配置。ACTIVE用于新消息,VERIFY_ONLY仅接受明确绑定旧在途任务的有效验证,REVOKED一律拒绝。
HMAC-SHA256小写64位十六进制;签名覆盖协议版本RENT_HMAC_SHA256_V1、scope、api_key、Unix毫秒timestamp、nonce、HTTP方法、规范化path/query、SHA256实际body。字段以换行分隔,限制字段中换行,查询编码/排序及空body规则需固定跨语言测试向量;签名自身置于外层信封不参与body哈希。常量时间比较,Secret不上传请求,TLS提供传输加密。
API、NODE、TASK、WEBHOOK四域区分方向和用途。TASK使用节点凭证,完整intent及task_no、node_id、deadline纳入认证,按deadline验时效;回调只选择该订单APP的ACTIVE凭证,每次重试新timestamp/nonce,同一event_no保持不变。商户返回HTTP200且正文ok才确认,失败退避直至最大次数后DEAD并告警。回调逐次执行SSRF、DNS及重定向校验。共享Secret不具不可否认性,独立链上核验不可省略。
系统登录沿用GoogleOauthService及若依权限;后端@PreAuthorize和前端v-hasPermi使用rent:order:list、rent:node:audit、rent:account:topup、rent:settlement:approve等。不创建新角色表,凭证只供外部API/Agent使用,不能替代用户菜单权限。
## 6. 实施步骤与验证
### 云端与节点Socket通信和心跳
本版明确采用WebSocket(生产WSS)作为双向Socket协议,建议入口wss://平台域名/node/v1/socket。由Agent主动连接,适配NAT且无需开放本地公网端口;服务端复用当前JDK8/Spring Boot可兼容的WebSocket能力,Agent选兼容JDK8的客户端。API及商户回调仍用HTTPS,浏览器TronLink流程不走节点通道。
**认证与会话:**TLS升级后连接仍未认证,云端先发短期随机挑战,Agent在5秒内提交AUTH(node_no、api_key、timestamp、nonce、挑战及HMAC);Secret不放URL、查询参数或消息正文。AUTH按NODE域覆盖协议版本、用途、挑战、请求路径和全部业务字段,查rent_credential的NODE归属/状态、节点审核状态及防重放记录。只有成功后才能处理心跳和业务消息。服务端响应AUTH_OK也用该节点Secret认证并回显挑战,生成session_id及原子递增session_epoch。不能把HTTP升级成功当认证成功。
每节点仅允许一个当前认证会话。新连接认证成功后以node行CAS替换旧会话、递增epoch并关闭旧连接;每帧携带且签名覆盖当前session_id/epoch、方向、type、message_id、timestamp、递增sequence及payload摘要。节点上行和云端下行各自独立sequence,从1递增;字段/nonce不可跨NODE/TASK签名域复用。服务端下行序号由持连接进程串行维护,重启必须重新认证新会话,不能从旧序号继续。数据库last_client_sequence用于上行去重和连接恢复审计,不支持一个节点被多个实例并发接单。
节点业务status和连接connection_status分离:PENDING审核、ACTIVE允许接单、PAUSED暂停、REVOKED吊销不因连接变化而更改;OFFLINE离线、SYNCING恢复、ONLINE可通信独立变化。PAUSED可保持连接用于上报和核对在途任务,不能分配新单;REVOKED立即关闭通道并拒绝认证,云端继续独立链上核对历史交易。
**双向心跳:**默认每15秒发带HMAC的应用层PING,对端立即回PONG并回显ping message_id;云端和Agent都维护最近有效PONG及超时,默认45秒未收到则断开并重连。只接受属于当前会话、有效签名及未过期的心跳,重复旧PONG或任意TCP字节不能续租;云端用接收时间更新heartbeat_at/heartbeat_expires_at,不能信任节点自报时钟。WebSocket原生Ping/Pong可辅助探活,但不替代带身份的应用心跳。任务执行在线程池中进行,不能阻塞Socket事件线程而丢心跳。
所有节点状态、心跳、业务帧及断线回调更新都带node_id/session_epoch条件;旧会话close事件不得把新会话置OFFLINE。云端定时扫描过期心跳并条件标离线,调度只选status=ACTIVE、connection_status=ONLINE且租约未过期的节点,同时资源快照必须有效。数据库心跳可按15秒粒度合并写入,不将每次PING/PONG写rent_event以免无限增长。
**消息类型和可靠交付:**AUTH/AUTH_OK、PING/PONG、TASK_PUSH/TASK_ACK、TASK_ACCEPT/TASK_REJECT、TASK_EVENT/TASK_RESULT、RESULT_ACK、SYNC_REQUEST/SYNC_STATE/SYNC_ACK、PAUSE/ERROR。TASK_ACK只表示节点已持久化接收到的任务;TASK_ACCEPT才表示本地策略与资源允许执行,二者均不是广播成功。Socket发送成功不能将任务设ACCEPTED,更不能设SUCCESS。
云端先提交rent_task再推送,保留delivery_message_id;丢ACK时只重发同一任务及同一message_id,外层会话签名可以重新生成,原任务intent/HMAC和txId不可重构。Agent先持久化task_no及消息摘要再ACK,已存在任务相同内容返回本地状态,不同内容拒绝。过期任务即使重投也不能新执行。delivery_count仅投递计数,不是交易重试次数。
节点事件先存本地可靠发送队列,云端以rent_event.event_no=nodeId:eventId同事务去重、更新任务及交易后才发RESULT_ACK;ACK丢失可重发同事件,不能重复扣费/结算。云端当前帧sequence防会话重放,跨会话message_id/eventId/task_no负责持久幂等。逐帧HMAC与TASK内层HMAC分开:外层认证当前连接,内层认证冻结授权意图。
**重连恢复:**断线采用带随机抖动的指数退避,建议1、2、4、8秒逐步到最大30秒;连接并完成稳定认证后复位。新会话先SYNCING:Agent发送未完成task_no、已持久化txId、最后本地状态及待确认事件;云端与数据库及链上证据核对,ACK历史结果,返回需重发的原任务及禁止执行/过期状态。完成SYNC_ACK才ONLINE并允许新单。不能仅根据“本地没有该任务”就认定未执行;云端已有广播线索或未知副作用时仍先核对链上。
断线/心跳超时不等于链上失败,已接受/已广播/UNKNOWN任务继续保留资金和对应资源占用。Agent断线后不得接受新任务;尚未签名广播的任务暂停直到恢复认证并核对授权,已广播的交易仅本地查询原txId和持久化结果,重连回传;不因断线重签另一笔交易。网络恢复不能延长原deadline。
**多实例及限流:**session_id/epoch及server_instance_id落node表,Socket对象仅存在持连接实例内存。首版可单Socket入口;多实例时任务只能由连接所属实例投递,其他实例通过受控路由/发布通知唤醒持连接实例,持久事实始终在MySQL。进程重启连接失效并重新认证;Redis只作路由缓存。配置认证超时、帧大小上限(建议64KiB)、JSON深度、每节点消息速率、发送队列和线程池上限,慢消费者背压/断开而非无限堆积;日志禁止Secret和完整认证材料。
```mermaid
sequenceDiagram
participant A as 本地Agent
participant C as 云端WSS
participant D as 数据库
A->>C: 主动建立WSS连接
C-->>A: 一次性认证挑战
A->>C: AUTH(api_key及HMAC)
C->>D: 校验身份、分配session及epoch
C-->>A: AUTH_OK(HMAC)
A->>C: SYNC_STATE(历史任务及txId)
C-->>A: SYNC_ACK,允许接单
loop 每15秒双向心跳
C->>A: PING
A-->>C: PONG
A->>C: PING
C-->>A: PONG
end
C->>A: TASK_PUSH(持久化原任务)
A-->>C: TASK_ACK(已本地持久化)
A-->>C: TASK_ACCEPT / TASK_RESULT
C->>D: 原子更新并去重事件
C-->>A: RESULT_ACK
Note over A,C: 45秒无有效心跳则离线;重连先核对原任务,不盲目重派
```
测试增加:认证超时/伪造HMAC、旧PONG重放、心跳与长链上调用并发、网络半开、丢TASK_ACK、丢RESULT_ACK、重复推送、连接代次抢占、旧close不能影响新会话、重连未同步禁止接单、节点吊销、多实例路由、帧超限/背压、离线已广播成功后的恢复。现有表需新增会话与投递字段的版本化迁移,不能靠IF NOT EXISTS升级。本次仅设计,不声称已实现Socket服务或真实断线测试。
1. 建 16 表及 Mapper、共享菜单权限、HMAC 测试向量,隔离 MySQL 检查 DDL 及逻辑归属;验证本文及复核说明中的跨表约束。
2. 套餐、应用、节点/钱包审核、人工充值和不可变流水。
3. 下单冻结、单节点调度及Fake Agent闭环,覆盖并发/崩溃/幂等/未知。
4. NILE真实委托、云端独立核验、回调、到期撤销及资源恢复证据。
5. 人工结算/退款、每日账实核对、权限及限额、暂停接单与持续核对在途任务。
6. 主网上线单独批准,小额限额逐步开放;未完成资金及链上规则验收不得自动广播。
本文件与 DDL 是 V2.2 新设计,不是 V2.1 或旧 53 表的就地升级。初始化脚本不含 DROP 或 ALTER;已有表必须按实际历史数据另写增量迁移,不能依赖 IF NOT EXISTS 覆盖。字段回填、冲突隔离和旧 HMAC 兼容要求见复核说明。本次只改设计文件,无现有数据库操作。
测试至少覆盖:重复下单不同参数、余额不足、两个节点/任务抢同钱包、套餐改价、广播超时但实际成功、重启后按原交易恢复、未知单取消/重派拒绝、回收锁定/未恢复、同地址对同类型多订单及异类型并发、重复回调和SSRF、充值凭据重复、结算占位和未知付款、退款冲正、越权及UTC映射。Fake通过不等于NILE真实验证,编译通过不等于资金并发测试通过。
### V2单能量稿升级说明
若V2单能量表已执行,不能重跑IF NOT EXISTS完成升级。须备份后编写版本化ALTER:历史套餐/订单/task/transaction明确回填resource_type=ENERGY;energy_quantity改为resource_quantity;钱包原delegatable_sun/reserved_sun/retain_sun分别迁为energy_*,保留原金额与预留;新增带宽字段初始为0、bandwidth_enabled=0,重新可信查询并审核后才能启用。任务新增resource_quantity从原订单快照回填。旧HMAC任务的intent和签名不能原地篡改,应保留旧协议验证直到在途完成,新任务才使用包含资源类型的版本。最终去掉resource_type临时迁移默认值并验证非空。此处为迁移要求,本次未执行ALTER或修改数据库数据。