基础代码生成

This commit is contained in:
lu7213 committed 2026-10-22 11:09:36 -04:00
1 parent 352d7d023f
commit 1c0544afe0
122 files changed
+21475

No files matched your search

+235
View File
@@ -0,0 +1,235 @@
# 能量与带宽出租业务复核与修正 V2.2
## 1. 结论与适用范围
原 V2.1 的独立余额、供应商本地签名、链上独立核验、未知隔离、履约和回收分离方向可保留,但退款、人工付款、资源快照和多单回收存在实质缺口。V2.2 已在 [初始化 SQL](../../sql/rent_init.sql)、[主设计](schema-design.md) 和[逐表说明](table-functional-flows.md)中同步修正,表数由 15 增至 16。
这是设计及初始化脚本修正,不是运行时修复报告。当前未实现租赁服务、未对现有数据库执行迁移、未进行 NILE 真实委托。下述应用约束必须由后续服务及 Agent 实现,MySQL 5.7 不会替应用执行 CHECK 或逻辑外键。
| 问题与触发场景 | 原设计后果 | 本次修正 |
| --- | --- | --- |
| 同订单第二次部分退款 | 回调 `(order_id,event_type)` 唯一键冲突;没有退款请求幂等主体 | 新增 rent_refund;回调改为 event_key 及订单事件序号唯一 |
| 审批后已人工付款,但尚未登记结果 | 仍处于 APPROVED,可能被拒绝并释放订单,或再次付款 | 新增 PAYING、唯一 payout_no、payment_started_at,先持久化授权再付款 |
| 平台手续费退给供应商 | 账户待结算增加,但订单结算来源公式不包含这部分 | 增加 supplier_fee_returned_amount,并纳入净可结算公式 |
| 委托已确认、资源预留已扣减,但异步旧查询回写 | 旧可委托本金再次可见,可能超卖 | 钱包最低快照区块、快照高度、version CAS、旧快照失效和任务执行占位配合 |
| 同钱包同接收者同类型存在多笔委托 | 链上聚合关系难归单,锁定及撤销可能互相影响 | 订单 relation_slot 持久互斥,直到本金回收且资源恢复;同地址下一单排队或改选钱包 |
| 可重试失败时先解冻,再生成新任务 | 可能无冻结资金继续履约 | 明确重试与终结:重试保留 HELD;最终失败才 RELEASE |
| 只扫描交易表恢复 UNKNOWN | Agent 已接单但未回 txId 的任务永远遗漏 | 同时扫描任务和交易,未知占位不释放 |
| 核验晚于实际交付很久 | 用核验时间作为租期起点,额外延长占用或对已过期业务扣款 | 保存 block_time,以确认交易区块时间算租期;已到期转人工 |
| 任意业务租期直接调用现有通用委托方法 | 当前实现写死 lock=true、86400 且直接广播,无法遵守本地持久化恢复协议 | 套餐 delegate_lock=0,首版只非锁定委托,Agent 独立执行;只复用查询 |
| 回收任务未显式绑定原交易 | 可能按当前资源换算或引用错误本金 | task.source_transaction_id 固定原确认委托,撤销原 SUN、同网络同类型 |
| 已上链但资源量不足 | 若按普通失败释放,将低估实际已委托本金 | 链上 CONFIRMED 与订单 SUCCESS 分离;先记事实及屏障,再人工处置和回收 |
## 2. 修正后的业务主流程
```mermaid
flowchart TD
A["应用认证、订单幂等、套餐校验"] --> B["下单事务:冻结USDT、锁定价格规则和执行截止"]
B --> C{"钱包、关系占位、快照和资源满足?"}
C -->|无| D["WAITING等待;截止前重试"]
D --> C
D -->|从未派单且超时| Z["取消、解冻、回调"]
C -->|有| E["预留SUN、关系占位、创建唯一在途任务"]
E --> F["Agent持久化、复核、原交易签名广播"]
F --> G{"云端独立核验"}
G -->|未知| H["保留占用、查询原任务和交易"]
H --> G
G -->|明确失败可重试| I["释放旧资源占位,保留冻结资金"]
I --> C
G -->|最终失败| J["解冻资金、释放安全占位、失败回调"]
G -->|上链但交付不足或核验已过期| M["确认链上事实、快照屏障、人工核对及回收"]
G -->|达标且未过期| K["扣款、供应商净应收、快照屏障、成功回调"]
K --> R["租期届满,按原交易SUN创建回收任务"]
M --> R
R --> S["撤销核验、快照屏障、资源恢复检查"]
S -->|未恢复| S
S -->|恢复| T["回收DONE,释放关系占位"]
K --> P["结算占用、独立审批、PAYING授权、人工付款核验"]
K --> Q["独立退款单审批、余额与流水原子调整"]
```
首版保持固定套餐、一单一种资源、一个钱包、整笔交付、整笔回收、每订单来源全额结算一次。能量与带宽分别下单、换算和预留。非锁定不表示自动回收,供应商必须承诺租期内不擅自撤销;平台监测委托关系,提前撤销转人工并按规则退款。平台不掌握私钥,不能用数据库约束阻止供应商自行链上操作。
## 3. 钱包快照、预留和互斥协议
### 3.1 两种占位分别负责什么
- `rent_order.relation_slot=1`:限制同钱包、同接收者、同类型只保留一笔在租或待回收订单。成功履约后仍保留;只有明确未执行释放,或原本金回收且本单资源恢复后才置 NULL。
- `rent_task.wallet_execution_slot=1`:同钱包同类型只允许一个在途链上操作,包括委托、回收和 UNKNOWN。核验终结并写入屏障后可置 NULL,让其他接收者的任务继续执行。
- `rent_task.active_slot=1`:同订单同任务类型的有效或已成功尝试占位。成功后继续保留用于追溯,只有明确失败且安全时才能置 NULL 后产生新 attempt。
三个占位业务上只允许 1 或 NULL。唯一键不阻止写入 2,所以服务端必须校验,不能接受客户端提交。节点不能把 UNKNOWN 当失败;租约、会话失效不释放占位。
### 3.2 取得和应用快照
1. 先读取钱包 version、snapshot_min_block_height 及地址、网络、策略,不持有长事务进行 RPC。
2. 通过受信任节点获取两类资源状态、对应全网参数、`getCanDelegatedMaxSize`、确认区块高度及必要证据。高度必须代表这些数据的实际观测状态,不得给旧数据贴上新高度。
3. 若 RPC 不支持按区块一致查询,应通过前后区块检查和节点一致性验证形成可验证观测;不能证明数据覆盖下界就拒绝调度,不伪造“确认区块参数”。历史交付核验需要可信历史快照或支持历史状态的节点,不能拿当前 L/W 冒充确认区块值。
4. 短事务 CAS 更新:version 仍等于查询前值,快照区块不回退且不低于 snapshot_min_block_height;成功后递增 version。任一条件失败丢弃并重查。
5. 快照刷新只改链上投影、参数、时间及高度,不覆盖 reserved_sun、占位和供应商策略。两类查询有一类失败时不推进共同快照,不用零覆盖旧值。
6. 调度还要检查对应 enabled、节点在线和审核状态、快照未过期、执行占位为空及可调度本金。普通 TRX 余额、免费带宽、收到代理量不参与本金池。
### 3.3 委托确认与快照屏障
假设旧快照可委托 1000 SUN,本次在途预留 600 SUN,链上已执行但旧查询仍返回 1000。若只减预留至 0,旧值会错误允许再委托 1000。
修正顺序:确认交易 → 同事务将该笔预留从 HELD 转 COMMITTED,reserved_sun 减 600 → snapshot_min_block_height 提升到确认区块 → snapshot_expires_at=NULL → version 递增 → 释放钱包执行占位。此时任何调度都因快照失效失败;旧查询因版本或区块不符失败。新查询覆盖已确认委托,取得真实剩余额度后才恢复出租。
撤销确认同样先写屏障、失效快照,再释放执行占位。回收任务固定 `reservation_status=NONE`,不能把回收本金当一笔新的待委托预留,也不能一确认撤销就机械增加可出租本金。接收者使用资源后撤销可能将资源使用债务转回供应者,实际可委托上限需重新查询。
未知时不释放预留或执行占位,即便快照已经包含交易变化,多扣一份也只会暂时保守,不得以“看起来余额够了”为由解除未知隔离。
### 3.4 地址对、链上锁定与外部修改
首版任务必须非锁定,接收者不是 owner,地址有效、已激活且满足目标网络当下委托条件。签名前检查同 owner/receiver 同类型已委托基线为零;存在外部委托或锁定关系则不使用该地址对。回收前确认关系与本单原本金对应,发现外部追加、提前撤销或部分变化则暂停相关调度并转人工。
参与租赁的钱包不得同时由其他平台或无协调脚本修改相同资源池。Agent 本地也要按钱包及类型串行,不只依赖云端。数据库无法防止拥有私钥者绕开 Agent;必须持续核对链上变化,不把事先审核当永久授权事实。
共享快照可能因另一资源类型的确认暂时整体失效,这是保守的首版取舍;不能跨类型转移本金。将来若拆独立快照,应为两类分别设置版本和区块屏障。
### 3.5 费用与任务授权
Stake 2.0 委托和撤销是原生操作,不应把智能合约调用的 fee_limit 字段当作它们的协议费用硬上限。此设计的 fee_limit_sun 是本地允许预算,Agent 根据当下带宽、网络费用、权限/签名附加费用和费用留存进行检查;预算为零或无法估算则拒绝。它不承诺协议费率变化时绝对不超额,供应商毛收入须覆盖双方约定的委托及回收成本。
新任务 intent 使用业务结构版本 `RENT_TASK_V2`,外层 HMAC 协议仍为 RENT_HMAC_SHA256_V1;签名覆盖新增 network、source_transaction_id、原委托 txId、精确 SUN、类型、两端地址、预算及期限等完整意图。Agent 对标量字段和签名原文一致性逐项校验,不能只验 JSON 一份却使用另一份未校验字段执行。回收来源必须可对应真实原交易;旧任务仍保留旧结构原文和验证路径,不原地重签。
## 4. 失败、重试、交付与回收
### 4.1 截止与重试
订单创建时固化 `dispatch_deadline`,DELEGATE 任务 deadline 不晚于它;RECLAIM 使用独立有效期,不受原下单截止限制。Agent 不能在任务过期后新签名/新广播,原交易查询和结果回报仍允许。
只有从未创建过执行任务的 WAITING 单可以用户取消或等待超时直接取消;已有投递线索时先恢复原任务。明确未执行拒绝可在截止前释放资源、保持 HELD 并重派;原订单 wallet_id、供应商及账号只在已证明无副作用且旧占位释放的安全重试中可重选,旧尝试归属保留在 task。最终 FAILED/CANCELLED 与资金 RELEASED 是终态,不能再自动恢复执行。
已构建原交易的重试,必须确认链上失败且无委托副作用,或原交易有效期已过并通过可信链上查询证明未执行。查询返回一次“未找到”、节点离线、worker 租约过期、Agent 本地丢记录都不足以证明。无 txId 的 UNKNOWN 同样由任务扫描处理,保留占用直至有足够证据。
### 4.2 链上成功与交付成功
`rent_transaction.CONFIRMED` 表示链上操作已执行,不表示套餐交付合格。将实际资源额度写入 verified_resource_quantity,即便小于目标也保存真实值。task VERIFIED 记录操作已核验,订单 MANUAL_REVIEW 保留资金,原本金进入回收计划。
服务起点为委托交易的可信 block_time;到期时间为起点加 duration_seconds。核验很晚、服务已经到期或无法取得可信历史参数时,不自动扣款或重设起点,转人工按实际交付和合同处理。已确认委托无论订单是否成功都要持久化回收计划。
异常 HELD 订单回收完毕后,按审核处置释放资金并终结 FAILED;没有确认供应商收入时不凭空创建应收。若要对异常实际服务收费,须新增明确补偿审批和流水业务,不能绕过本版成功条件直接修改余额。
### 4.3 回收不等于瞬间可再次出租
RECLAIM.source_transaction_id 只能引用本订单已确认的 DELEGATE 交易,网络、owner、receiver、资源类型和 SUN 全部一致。回收不能重新按资源量换算,不撤销其他来源,不自动部分回收。
撤销确认后状态可进入 RECOVERING;按可信可委托上限及资源恢复证据判定本单恢复,不要求数值回到旧快照(会受其他订单和全网参数影响)。无法归属或恢复债务持续异常时保留关系占位并人工核对。资源恢复判定标准须在 NILE 实测后固定,不能仅靠数据库状态宣称恢复。
## 5. 资金、退款和结算
### 5.1 统一锁顺序与原子性
所有流程统一锁序:账户按 ID 升序 → 已有结算单按 ID 升序 → 订单按 ID 升序 → 退款单按 ID 升序 → 钱包按 ID 升序 → 任务按 ID 升序 → 交易记录。只锁本操作涉及的层级,可跳过但不能逆序回锁。先读取候选 ID,再开启事务按顺序重查状态和归属;发现归属已变则回滚重试,禁止持有订单锁后补锁账户。
套餐版本商业字段不可变;下单在账户之后锁套餐再插入新订单。节点审核/连接改变用状态条件、版本和 Agent 再验证保护,不在钱包锁后反向锁账户。所有外部调用在短事务外执行。
结算创建和退款审批共同锁定供应商账户及来源订单,因此不能在检查完“无结算占用”后又被并发结算抢走。结算不扣审批阶段余额,但有效明细占住来源。退款提交时 PENDING 不预留金额,审批时必须再次校验累计,多个审批由订单行锁裁决。
余额、流水、订单累计、退款 APPLIED、回调队列和审计同事务;唯一键冲突必须回滚整个余额变更,不得捕获后继续提交。重试用固定业务键查既有结果。
### 5.2 退款计算和逐次回调
设本次商户退款 M、供应商原净额冲正 S、平台手续费退回 F:
- M > 0;M 加累计 refunded_amount 不超过售价。
- S >= 0;S 加 supplier_reversed_amount 不超过原 supplier_net_amount。
- F >= 0;F 加 supplier_fee_reversed_amount 不超过原 supplier_fee_amount。
- F=0 时 fee_return_to 必须 NONE;F>0 时只能 MERCHANT 或 SUPPLIER。
- MERCHANT 时 F<=M,F 已包含在 M 中,不能再增加 F 可用余额。
- SUPPLIER 时增加待结算 F,并增加订单 supplier_fee_returned_amount;它是 supplier_fee_reversed_amount 的子集,不能再冲正第二次。
- 涉及 S 或 F 的审批,若来源已结算或存在有效结算明细,拒绝应用;回到人工协调,不能修改已付记录。S=F=0 的平台承担退款可独立审批。
- 最终各账户余额不能为负。商户和供应商是同一账户时仍分别追加业务流水,按单次变化顺序计算 after 值。
退款流水建议使用 `REFUND:<refund_no>:MERCHANT`、`:SUPPLIER_REVERSE`、`:FEE_RETURN` 等独立 business_key,全部关联 refund_id。MERCHANT 退费可拆为基础退款 M-F 与手续费退款 F,后者 delta_platform_fee=-F;F=M 时不必写零额基础流水。SUPPLIER 方向的商户退款为 +M,供应商手续费返还为待结算 +F、平台手续费 -F,供应商原净额冲正另为 -S。
每次 APPLIED 产生 event_key=`REFUND:<refund_no>`,payload 保存本次金额及该时点累计。锁订单行后,以当前读查询该订单最高序号(例如按序号倒序 LIMIT 1 FOR UPDATE),分配 `order_event_sequence=max(已有序号)+1`;不能使用事务旧快照中的 MAX。普通成功等事件仍使用稳定 ORDER:id:type 键。没有回调地址时不创建发送任务。重试不修改内容和序号;消费者按 event_no 去重,不用到达顺序覆盖较新累计。
### 5.3 手续费返还与结算来源一致
```text
本单净可结算 = supplier_net_amount
- supplier_reversed_amount
+ supplier_fee_returned_amount
```
例:原供应商净应收 9.5 USDT、平台手续费 0.5 USDT;审核给商户退 1 USDT,同时将 0.2 USDT 手续费返供应商。商户 +1,供应商待结算 +0.2,平台手续费 -0.2;本单可结算变 9.7,而不是仍为 9.5。若另冲正原净应收 0.3,则变 9.4。此来源金额在结算创建时快照,结算占用期间禁止再改变供应商/手续费来源。
### 5.4 人工付款恢复
```text
PENDING → APPROVED → PAYING → PAID
↘ UNKNOWN → PAID
PENDING / APPROVED → REJECTED(尚未授权付款)
PAYING / UNKNOWN → REJECTED(独立证明未付款且授权已作废,特殊审核)
```
出款前必须持久化 payout_no 并提交 PAYING。付款页面和操作规程以 payout_no 为核对依据,结果未确认不得提供“重新付款”入口。进程崩溃后查询原付款证据;数据库授权只能防应用重复发起,人工操作和外部付款平台也必须遵守单一授权,不声称数据库能保证外部资金绝对只支付一次。
付款凭据按 network:txid:eventIndex 等规范化并独立核验金额、币种、网络、实际收款人与授权一致;payment_reference 唯一不能代替真实性核验。付款确认时原子减少待结算、追加 SETTLE、标记 PAID。PAID 明细占位保留。
### 5.5 充值与对账
TOPUP 的 business_key 以已核验的全局充值事件构造,不含账户 ID;其他流水键可以包含账户。键长度扩为 160 ASCII,为不同事件编号及账户组合留足空间,所有写入仍检查长度并拒绝截断。evidence_ref 仍是依据描述,不是唯一约束。
每日按网络核对:冻结余额 = HELD 订单售价合计;供应商待结算 = 已确认且未支付来源净额合计(包括退回供应商手续费);账户各余额 = 对应流水增量合计;平台手续费收入 = delta_platform_fee 合计;钱包预留 = HELD 委托任务本金合计。退款拒绝、结算拒绝和未知都保留历史,不手改差额。
## 6. SQL 与文档修正清单
| 表 | V2.2 变化 |
| --- | --- |
| rent_wallet | 快照高度、最低区块屏障 |
| rent_package | delegate_lock,首版只允许非锁定 |
| rent_order | 供应商账户、关系占位、执行截止、手续费返还累计、关系唯一键及扫描索引;修正服务起点 |
| rent_task | network、原委托交易引用、钱包执行占位及唯一键;回收预留 NONE |
| rent_transaction | block_time;实际资源不足不篡改链上事实 |
| rent_ledger | business_key 扩容及 ASCII、refund_id,修正手续费方向说明 |
| rent_settlement | PAYING、唯一 payout_no、付款授权时间 |
| rent_settlement_item | 净结算来源加入返还供应商手续费 |
| rent_refund | 新表,审批、幂等、退款与各方费用承担 |
| rent_webhook | event_key、订单事件序号及唯一键,删除按事件类型唯一限制 |
| rent_event | 编号长度与 ASCII、REFUND 审计类型 |
其余表保留原身份、凭证、防重放和资金账户职责。金额和状态检查仍须服务端执行,不能把 COMMENT 当数据库约束。
## 7. 已有数据库的迁移要求
本次只修订初始化 DDL,不提供盲目执行的 ALTER,因为目前没有实际已部署表结构和历史数据证据。重跑 IF NOT EXISTS 不会增加字段、修改索引或回填数据。
1. 暂停新单和新出款,备份结构及数据,核对实际版本;历史链上交易继续独立核对。
2. 先增可空字段并建退款表,再从可信来源回填;不要直接给历史在途单填一个“当前时间”或虚构的 block_time。
3. 同钱包同接收者同类型的历史重复在租订单,以及同钱包同类型多在途任务,先隔离核对,不能直接全部赋占位 1 后强建唯一键,也不能把 UNKNOWN 随意置 NULL。
4. 回填 supplier_account_id,检查用户/网络归属;历史手续费返还从不可变流水及审核依据重建,没有事实证明时不能猜测。
5. 回填 dispatch_deadline;历史已投递任务保持恢复路径,不因回填截止被自动取消或重派。
6. 原委托 block_time 从链上核验;RECLAIM.source_transaction_id 按真实原交易回填。旧任务 intent 和 HMAC 不原地修改,新字段仅用于新任务协议,旧在途沿旧版验证至完结。
7. 历史已锁定委托不改写为非锁定;保留原授权和真实锁期,专门回收。新套餐使用新版本和 delegate_lock=0。
8. 历史结算 APPROVED 需逐笔核对是否已付款或已开始人工付款,未知先隔离为 UNKNOWN;不能默认未付。历史付款凭据规范化去重后再建唯一索引。
9. 已有回调在保留原 payload、event_no 前提下按可信业务来源分配 event_key 和订单序号;历史缺失的部分退款需核对后补独立记录,不能重发造成再次退款。
10. 快照全部失效,初始化最低区块为已确认相关交易高度,可信重查后才恢复出租;验证新唯一键及逻辑约束,再上线服务。
## 8. 验收场景与边界
| 场景 | 必须满足的结果 |
| --- | --- |
| 同订单并发两次同退款请求 | 只一条退款单、一次余额变化和一次业务回调 |
| 同订单两次不同部分退款 | 两条退款来源和回调均可保存,累计不超过售价 |
| 两个退款审批累计超限 | 订单行锁裁决,第二个重新检查后拒绝,不改余额 |
| 同地址对同类型两单并发调度 | 关系唯一键只允许一个占位;失败事务不能遗留预留 |
| 同钱包同类型两个链上任务 | 执行唯一键拒绝第二个;不同类型独立占位 |
| 原任务 UNKNOWN | 预留及占位保留,不新签、不改派;无 txId 仍被恢复扫描 |
| 老快照请求在新确认事务之后返回 | 版本或高度不匹配,丢弃,不恢复出租额度 |
| 委托确认后扣掉预留但尚无新快照 | 快照失效,调度拒绝 |
| 已上链却未覆盖冗余目标 | 交易 CONFIRMED,订单人工核对,仍追踪本金回收,不重复委托 |
| 可重试失败 | 保留商户冻结资金,无终态失败回调 |
| 最终失败 | 一次解冻,不再自动新执行 |
| 核验晚于原租期 | 不延长起点或自动扣款,人工处理真实交付 |
| 回收任务 | 绑定原委托、原 SUN、同类型,reservation_status=NONE |
| 回收后资源尚未恢复 | RECOVERING,不按旧快照重租,不释放关系占位 |
| 手续费返供应商后结算 | 返还额同时存在账户、流水和来源订单,可结算金额一致 |
| 退款与结算并发 | 同账户/订单锁序决定唯一有效来源,不能既付款又冲掉来源 |
| PAYING 后崩溃或失联 | 查原 payout_no,不能普通拒绝或重新出款 |
| 重复充值凭据给不同账户 | TOPUP 全局业务键冲突,整个事务回滚 |
| 重复回调与乱序 | 余额不受影响,商户按 event_no 去重及事件序号识别旧事件 |
静态 DDL 与模型验证结果记录在 [validation-v2.2.md](validation-v2.2.md)。静态检查不能替代真实 MySQL 5.7/8.0 并发事务、Agent 故障恢复、HMAC 跨语言向量和 NILE 资源恢复实测。
+169
View File
@@ -0,0 +1,169 @@
"""离线验证租赁 DDL 的索引语义、文档覆盖及资金算例。
运行:python docs/rental/check_schema.py
仅使用标准库。SQLite 内存库只映射实际 DDL 的列名和唯一键,
用于验证冲突/NULL 占位语义,不替代 MySQL 方言、类型或并发事务测试。
"""
from decimal import Decimal
from pathlib import Path
import re
import sqlite3
import unittest
ROOT = Path(__file__).resolve().parents[2]
DDL = (ROOT / "sql/rent_init.sql").read_text(encoding="utf-8")
TABLES = {}
for match in re.finditer(
r"CREATE TABLE IF NOT EXISTS `([^`]+)` \((.*?)\n\) ENGINE=.*?;",
DDL,
re.S,
):
name, body = match.groups()
columns = re.findall(r"^ `([^`]+)` (.+?)(?:,)?$", body, re.M)
unique = [
(key, re.findall(r"`([^`]+)`", fields))
for key, fields in re.findall(
r"UNIQUE KEY `([^`]+)` \(([^)]+)\)", body
)
]
TABLES[name] = (columns, unique)
class RentalDesignChecks(unittest.TestCase):
def setUp(self):
self.db = sqlite3.connect(":memory:")
self.serial = 0
for table, (columns, unique) in TABLES.items():
definitions = [
'"id" INTEGER PRIMARY KEY' if field == "id" else f'"{field}" TEXT'
for field, _ in columns
]
definitions.extend(
"UNIQUE (" + ",".join(f'"{field}"' for field in fields) + ")"
for _, fields in unique
)
self.db.execute(f'CREATE TABLE "{table}" ({",".join(definitions)})')
self.addCleanup(self.db.close)
def insert(self, table, **values):
self.serial += 1
# 为与本用例无关的唯一列使用独立值,避免错误命中其他唯一键。
row = {
field: f"row-{self.serial}-{field}"
for field, _ in TABLES[table][0]
if field != "id"
}
row.update(values)
self.db.execute(
f'INSERT INTO "{table}" ({",".join(row)}) '
f'VALUES ({",".join("?" for _ in row)})',
tuple(row.values()),
)
def conflict(self, table, **values):
with self.assertRaises(sqlite3.IntegrityError):
self.insert(table, **values)
def test_table_and_document_coverage(self):
self.assertEqual(len(TABLES), 16)
self.assertEqual(len(re.findall(r"CREATE TABLE", DDL)), 16)
doc = (ROOT / "docs/rental/table-functional-flows.md").read_text("utf-8")
sections = set(re.findall(r"### 2\.\d+ (rent_\w+):", doc))
self.assertEqual(sections, set(TABLES))
for table, (columns, unique) in TABLES.items():
fields = {name for name, _ in columns}
self.assertEqual(len(fields), len(columns), table)
self.assertTrue({"id", "version", "created_at", "updated_at"} <= fields)
for name, definition in columns:
self.assertIn("COMMENT '", definition, f"{table}.{name}")
for key, parts in unique:
self.assertTrue(set(parts) <= fields, f"{table}.{key}")
executable = re.sub(r"--[^\n]*", "", DDL)
self.assertNotRegex(executable, r"(?i)\b(DROP|ALTER|DELETE|TRUNCATE)\b")
def test_document_local_links(self):
for path in (ROOT / "docs/rental").glob("*.md"):
for target in re.findall(r"\]\(([^)]+)\)", path.read_text("utf-8")):
if "://" not in target and not target.startswith("#"):
self.assertTrue((path.parent / target.split("#")[0]).exists(), target)
def test_order_relation_exclusion_and_null_release(self):
key = dict(wallet_id=7, receiver_address="receiver-A", resource_type="ENERGY")
self.insert("rent_order", **key, relation_slot=1)
self.conflict("rent_order", **key, relation_slot=1)
self.insert("rent_order", **key, relation_slot=None)
self.insert("rent_order", **key, relation_slot=None)
self.insert("rent_order", **{**key, "resource_type": "BANDWIDTH"}, relation_slot=1)
self.insert("rent_order", **{**key, "receiver_address": "receiver-B"}, relation_slot=1)
def test_wallet_execution_shared_by_delegate_and_reclaim(self):
key = dict(wallet_id=7, resource_type="ENERGY", wallet_execution_slot=1)
self.insert("rent_task", **key, task_type="DELEGATE")
self.conflict("rent_task", **key, task_type="RECLAIM")
self.insert("rent_task", **{**key, "resource_type": "BANDWIDTH"})
self.insert("rent_task", **{**key, "wallet_execution_slot": None})
self.insert("rent_task", **{**key, "wallet_execution_slot": None})
def test_task_attempt_active_slot(self):
key = dict(order_id=11, task_type="DELEGATE", active_slot=1)
self.insert("rent_task", **key, attempt_no=1)
self.conflict("rent_task", **key, attempt_no=2)
self.insert("rent_task", **{**key, "active_slot": None}, attempt_no=2)
self.conflict("rent_task", **{**key, "active_slot": None}, attempt_no=2)
def test_refund_request_deduplication(self):
self.insert("rent_refund", order_id=11, request_no="request-A")
self.conflict("rent_refund", order_id=11, request_no="request-A")
self.insert("rent_refund", order_id=11, request_no="request-B")
def test_multiple_partial_refund_webhooks(self):
self.insert("rent_webhook", order_id=11, event_type="REFUNDED",
event_key="REFUND:R1", order_event_sequence=2)
self.insert("rent_webhook", order_id=11, event_type="REFUNDED",
event_key="REFUND:R2", order_event_sequence=3)
self.conflict("rent_webhook", order_id=11, event_type="REFUNDED",
event_key="REFUND:R1", order_event_sequence=4)
self.conflict("rent_webhook", order_id=11, event_type="REFUNDED",
event_key="REFUND:R3", order_event_sequence=3)
def test_payout_and_payment_reference_uniqueness(self):
self.insert("rent_settlement", payout_no="P1", payment_reference="MAINNET:tx:0")
self.conflict("rent_settlement", payout_no="P1", payment_reference=None)
self.conflict("rent_settlement", payout_no="P2", payment_reference="MAINNET:tx:0")
self.insert("rent_settlement", payout_no=None, payment_reference=None)
self.insert("rent_settlement", payout_no=None, payment_reference=None)
def test_settlement_order_source_not_reusable_after_paid(self):
self.insert("rent_settlement_item", order_id=11, active_slot=1)
self.conflict("rent_settlement_item", order_id=11, active_slot=1)
self.insert("rent_settlement_item", order_id=11, active_slot=None)
def test_topup_global_business_key(self):
key = "TOPUP:MAINNET:" + "a" * 64 + ":2147483647"
self.assertLessEqual(len(key), 160)
self.insert("rent_ledger", account_id=1, business_key=key)
self.conflict("rent_ledger", account_id=2, business_key=key)
def test_one_transaction_per_task_and_hash(self):
self.insert("rent_transaction", task_id=11, network="NILE", tx_id="tx1")
self.conflict("rent_transaction", task_id=11, network="NILE", tx_id="tx2")
self.conflict("rent_transaction", task_id=12, network="NILE", tx_id="tx1")
def test_supplier_fee_return_example(self):
# 精确金额算例:账户待结算增量必须与来源订单可结算额一致。
gross, fee = Decimal("10"), Decimal("0.5")
returned, reversed_net = Decimal("0.2"), Decimal("0.3")
ledger_pending = gross - fee + returned - reversed_net
order_source = Decimal("9.5") - reversed_net + returned
self.assertEqual(ledger_pending, order_source)
self.assertEqual(order_source, Decimal("9.4"))
# 退商户的手续费已包含于M:基础退款+手续费退款=M,不能M+F。
merchant_refund, merchant_fee_part = Decimal("1"), Decimal("0.2")
self.assertEqual((merchant_refund - merchant_fee_part) + merchant_fee_part,
merchant_refund)
if __name__ == "__main__":
unittest.main(verbosity=2)
+305
View File
@@ -0,0 +1,305 @@
# 能量/带宽出租表结构与业务流程 V2.2
状态:设计稿,未执行现有数据库变更、未实现租赁业务服务。当前权威 DDL 为 [rent_init.sql](../../sql/rent_init.sql),共 16 张 rent_ 表。V2.2 复核结果、事务协议、迁移要求和验收场景见 [业务复核与修正说明](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自动执行。
保留供应商本地密钥、默认禁止广播、链上独立核验、订单幂等、原交易恢复、未知状态隔离、资金冻结、资源预留、到期回收、回调持久队列和不可变流水。
## 2. 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. 请求提交package_id、merchant_order_no、receiver_address(resource_type由套餐决定,如请求携带则必须一致),可指定回调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或修改数据库数据。
+520
View File
@@ -0,0 +1,520 @@
# 能量与带宽租赁:逐表功能流程及协同关系
## 1. 文档依据与业务范围
本文依据 [rent_init.sql](../../sql/rent_init.sql) 及 [schema-design.md](schema-design.md) 的 V2.2 设计整理,覆盖全部 16 张 `rent_` 表。复核发现、并发协议和迁移要求见 [business-review-v2.2.md](business-review-v2.2.md)。本文描述设计约定,不代表数据库迁移、业务服务或链上执行已经完成。
业务范围:商户通过内部 USDT 余额购买固定能量或带宽套餐,平台选择供应商钱包,由供应商本地 Agent 签名广播,云端独立核验后扣款、确认供应商应收;租期结束再回收资源。充值和供应商付款由人工审核处理。
共享若依 `sys_user`、登录及 RBAC 权限;租赁应用、订单和资金独立,不复用支付业务的 `apps`、`orders`、`wallet_address`。平台不保存供应商私钥或助记词。
### 1.1 通用字段与一致性约定
- `id` 为表内主键;业务编号和唯一键另行承担幂等职责。
- `version` 用于 CAS 乐观锁,更新时带原版本条件并递增;追加记录保持 0。
- `created_at / updated_at` 为应用显式写入的 UTC `DATETIME(3)`。
- USDT 金额使用 `DECIMAL(30,6)`,业务计算使用精确十进制。
- 表间采用逻辑外键;归属、网络、状态机、金额非负及跨表一致性由应用落实。
- `ENERGY` 数量单位为 Energy,`BANDWIDTH` 为 bytes;本金单位为 SUN,1 TRX = 1,000,000 SUN。
## 2. 逐表功能与流程
### 2.1 rent_app:商户应用
**设计功能:** 区分不同商户应用,确定订单归属、API 主体及默认回调地址。
| 关键字段 | 功能 |
| --- | --- |
| `user_id` | 应用所属 `sys_user.user_id` |
| `name` | 应用名称 |
| `status` | `ACTIVE` 启用、`DISABLED` 禁用 |
| `notify_url` | 默认 HTTPS 回调地址,需要 SSRF 校验 |
**功能流程:** 用户登录并获得权限 → 创建应用 → 签发应用凭证 → 商户认证下单 → 订单保存应用 ID 和回调地址快照。查询、取消等操作检查应用归属,不能仅凭传入 ID 操作。
**协同关系:** 一个用户可以创建多个应用,一个应用有多版 `rent_credential` 和多笔 `rent_order`。应用不保存余额,通过所属用户和订单网络定位 `rent_account`。
### 2.2 rent_credential:商户与节点统一凭证
**设计功能:** 管理 HMAC 身份、加密 Secret、密钥轮换及历史在途消息验证。
| 关键字段 | 功能 |
| --- | --- |
| `owner_type / owner_id` | `APP` 指向应用,`NODE` 指向节点 |
| `api_key` | 全局唯一公开标识 |
| `api_secret / master_key_version` | AES-GCM 密文及外部主密钥版本 |
| `status` | `ACTIVE` 可签发新消息;`VERIFY_ONLY` 仅验历史在途;`REVOKED` 吊销 |
| `expires_at / revoked_at` | 到期和吊销时间 |
**功能流程:** 创建主体 → 生成凭证 → 受认证通道一次性展示 Secret → 请求签名与服务端验证 → 轮换时新增凭证行并保留历史 → 必要时吊销。Secret 不随请求传输,也不写日志。
**协同关系:** 与 `rent_nonce` 协作防重放;`rent_task.credential_id` 固定节点授权版本;`rent_webhook.credential_id` 记录最近发送使用的应用凭证。主体归属是多态关联,需根据 `owner_type` 校验。
### 2.3 rent_nonce:认证消息防重放
**设计功能:** 阻止合法签名消息被重复使用。
| 关键字段 | 功能 |
| --- | --- |
| `api_key` | 对应凭证 |
| `scope` | API、NODE、TASK、WEBHOOK 认证域 |
| `nonce` | 高熵随机数 |
| `expires_at` | 安全清理时间,必须晚于消息有效期 |
**功能流程:** 验签并检查时效 → 原子插入 `(api_key, scope, nonce)` → 唯一键冲突则拒绝重放 → 超出有效窗口后清理。各方向的接收方落实防重放;Agent 和商户接收端同样需要相应机制,不能仅依赖云端此表。
**协同关系:** 关联 `rent_credential.api_key`。消息防重放与业务幂等分开:重试请求使用新 nonce,但保留原商户订单号。
### 2.4 rent_node:供应商本地执行节点
**设计功能:** 管理供应商 Agent 的审核、接单资格、在线状态、会话和心跳。
| 关键字段 | 功能 |
| --- | --- |
| `user_id / node_no` | 供应商及全局节点编号 |
| `status` | PENDING、ACTIVE、PAUSED、REVOKED |
| `connection_status` | OFFLINE、SYNCING、ONLINE |
| `session_id / session_epoch` | 当前会话及连接代次,隔离旧连接 |
| `server_instance_id` | 当前连接所在云端实例 |
| `heartbeat_at / heartbeat_expires_at` | 最近有效心跳及在线租约 |
| `last_client_sequence` | 当前会话上行认证帧去重序号 |
**功能流程:** 供应商注册 → 运营审核 → Agent 主动建立 WSS → 节点凭证认证 → 原子更新会话代次 → SYNCING 同步历史任务 → ONLINE → 持续心跳。默认心跳周期 15 秒、超时 45 秒,按云端接收时间判定。
**协同关系:** 一个节点绑定多个 `rent_wallet`,执行多个 `rent_task`,并持有节点凭证。仅审核允许接单、连接在线且租约有效的节点可获新单。PAUSED 可核对在途任务;离线不能作为交易失败依据。旧会话断开事件必须带 epoch 条件,避免覆盖新会话。
### 2.5 rent_wallet:供应钱包与两类资源池
**设计功能:** 保存公开钱包、控制权证明、可信资源快照、本金保留及在途预留。首版一个钱包只绑定一个执行节点。
| 字段组 | 功能 |
| --- | --- |
| `node_id / network / address` | 执行节点、网络、资源所有者地址 |
| `ownership_challenge / ownership_message` | 平台保存的一次性挑战和完整待签原文 |
| `ownership_signature / ownership_verified_address` | TronLink 消息签名及后端恢复地址 |
| `challenge_* / ownership_verified_at` | 挑战期限、消费及验证时间 |
| `energy_enabled / bandwidth_enabled` | 两类资源独立出租开关,默认关闭 |
| `*_delegatable_sun / *_reserved_sun / *_retain_sun` | 各类可委托本金、在途预留、供应商保留本金 |
| `energy_available / bandwidth_available` | 查询投影;带宽只含可出租质押带宽 |
| `total_*_limit / total_*_weight` | 两类全网换算参数 |
| `snapshot_at / snapshot_expires_at` | 可信快照有效期 |
| `snapshot_block_height / snapshot_min_block_height` | 当前快照高度及允许应用快照的最低确认区块 |
**功能流程:** 绑定钱包 → 平台签发挑战 → 用户通过 TronLink `signMessageV2` 签署原文 → 后端恢复地址、验证归属和有效期并原子消费挑战 → 检查链上执行权限及运营审核 → 启用出租 → 刷新可信快照 → 调度时锁钱包行并预留对应类型本金 → 委托成功后转换预留并刷新链上状态 → 回收且资源恢复后重新出租。
```text
对应类型可调度本金 = delegatable_sun - retain_sun - reserved_sun
```
**协同关系:** 节点决定供应商归属;订单记录选定钱包,任务记录预留明细,交易表提供实际委托和回收证据。能量与带宽本金不互借,免费带宽、普通 TRX 余额和收到的代理资源不能直接视为可出租本金。验证地址控制权不等于审核通过或 Agent 已具备委托权限。
异步刷新必须先读取 version,再查询可信节点,最后 CAS 更新;确认交易时原子提升最低区块、失效旧快照并处理预留,再释放钱包执行占位。新快照必须覆盖屏障区块,才能再调度;可委托本金取对应类型 `getCanDelegatedMaxSize`,不能简单用总质押减已委托。
### 2.6 rent_package:固定套餐与价格版本
**设计功能:** 定义资源数量、租期、售价、供应商毛收入、手续费及执行规则。
| 关键字段 | 功能 |
| --- | --- |
| `package_code / revision` | 套餐代码与递增版本 |
| `network / resource_type / resource_quantity` | 网络、资源类型、购买数量 |
| `redundancy_percent` | 正冗余比例,默认 20%,订单创建时锁定 |
| `duration_seconds / sale_amount` | 租期与商户售价 |
| `supplier_amount / supplier_fee_percent` | 供应商毛收入与平台手续费率 |
| `fee_limit_sun / rules` | 单笔链上费用上限及锁定、偏差、退款规则 |
| `delegate_lock` | 首版固定 0 非锁定,1 拒绝上架 |
| `status` | ACTIVE 上架、DISABLED 下架 |
**功能流程:** 运营配置 → 校验数量、价格、毛收入、正手续费及完整规则 → 上架 → 商户下单保存快照 → 改价或调整商业规则时新增 revision,历史订单不变。
**协同关系:** 一个套餐版本关联多笔订单;同一代码各版本不能改变资源类型。供应商金额已包含约定链上操作成本;费用上限为零时不能广播。
### 2.7 rent_account:租赁内部资金账户
**设计功能:** 按用户和网络隔离 USDT 可用、冻结和供应商待结算余额。
| 关键字段 | 功能 |
| --- | --- |
| `user_id / network` | 唯一账户归属 |
| `available_amount` | 商户可消费余额 |
| `frozen_amount` | 订单资金冻结余额 |
| `supplier_pending_amount` | 供应商扣手续费后的待结算余额 |
| `status` | ACTIVE 可操作、FROZEN 冻结业务 |
**功能流程:** 人工充值核验后增加可用余额 → 下单由可用转冻结 → 成功扣冻结;明确失败或取消则冻结转回可用 → 供应商成功履约增加净待结算 → 人工付款核验后减少待结算。成功订单退款按审核规则返还内部余额。
**协同关系:** 所有余额变化必须与 `rent_ledger` 同事务;订单引用付款账户,结算单引用供应商账户。同一用户可同时是商户和供应商,同网络仍只有一个账户。三类余额均不得为负。
### 2.8 rent_order:租赁业务主订单
**设计功能:** 汇总下单、资源交付、价格快照、资金、退款、租期及回收计划。
| 字段组 | 功能 |
| --- | --- |
| `order_no / app_id / merchant_order_no / request_hash` | 平台编号、商户归属和业务幂等 |
| `package_id / package_snapshot` | 套餐版本及规则快照 |
| `resource_* / redundancy_percent / target_resource_quantity` | 购买量及含冗余目标 |
| `sale_amount / supplier_*` | 售价、毛收入、手续费、净应收及累计冲正 |
| `wallet_id / supplier_user_id` | 选定供应钱包与供应商快照 |
| `supplier_account_id / relation_slot` | 固定供应商账户及同钱包、接收者、资源类型的持久占位 |
| `dispatch_deadline` | 下单时锁定最晚新任务执行时间,不能用于推定已投递任务失败 |
| `supplier_fee_returned_amount` | 退回供应商的手续费累计,增加结算来源金额 |
| `payer_account_id / fund_status / refunded_amount` | 付款账户、资金状态和退款累计 |
| `status` | 履约状态 |
| `service_* / reclaim_status / next_reclaim_at` | 租期及独立回收调度 |
| `notify_url` | 本单回调地址快照 |
**功能流程:** 请求校验与幂等 → 同事务创建 WAITING 订单和冻结资金 → 选择钱包并创建委托任务,进入 EXECUTING → VERIFYING 独立核验 → 成功则 SUCCESS 并扣款、确认应收、回调入队 → 到期推进回收。明确未执行失败可解冻,结果不确定进入核对流程。
| 状态维度 | 主路径 |
| --- | --- |
| 履约 `status` | WAITING → EXECUTING → VERIFYING → SUCCESS;另有 FAILED、CANCELLED、MANUAL_REVIEW |
| 资金 `fund_status` | HELD → CHARGED 或 RELEASED |
| 回收 `reclaim_status` | NOT_STARTED → WAITING → RUNNING → RECOVERING → DONE;异常 MANUAL_REVIEW |
**协同关系:** 连接应用、套餐、账户、钱包、任务、交易、流水、结算明细、回调和审计。一单一种资源、一个供应钱包。未知执行结果不能改派;用户只能取消尚未生成任务的 WAITING 订单。无供应方时有明确等待上限,避免无限冻结。
同钱包同接收地址同资源类型只允许一个 relation_slot=1,直到明确未执行释放或本金回收且资源恢复;下一单排队或改选其他钱包。服务起点采用核验交易的区块时间,不能使用核验完成时间;延迟核验时已到期转人工。退款不覆盖 CHARGED 事实。
### 2.9 rent_task:委托与回收任务
**设计功能:** 兼任持久执行队列、授权意图、尝试历史和资源预留明细。
| 字段组 | 功能 |
| --- | --- |
| `order_id / wallet_id / node_id` | 订单及执行归属 |
| `network / source_transaction_id` | 显式网络;回收任务绑定原确认委托交易 |
| `wallet_execution_slot` | 同钱包同资源类型最多一个在途操作,未知保留 |
| `task_type` | DELEGATE 委托、RECLAIM 回收,不支持转账 |
| `conversion_* / estimated_resource_quantity / delegate_sun` | 换算证据、预计交付量和授权本金 |
| `attempt_no / active_slot` | 尝试序号及有效占位 |
| `credential_id / intent / signature / deadline` | 固定凭证、HMAC 意图和执行期限 |
| `status / reservation_status` | 执行状态及 HELD、COMMITTED、RELEASED 资源状态 |
| `lease_owner / lease_until` | worker 处理租约 |
| `delivery_* / last_sent_at` | 稳定消息编号、投递代次、次数及持久接收 ACK |
**功能流程:** 查询可信全网参数 → 锁订单与钱包 → 预留本金并创建任务 → 提交后 WSS 推送 → Agent 持久化后 TASK_ACK → 策略与资源检查后 ACCEPTED → 原交易广播 BROADCASTED → 云端核验 VERIFIED。明确拒绝或失败才可释放相应占用;UNKNOWN 保留隔离并查原交易。
**协同关系:** 一个订单可以保留多个历史尝试,但同类型有效或成功任务由 `(order_id, task_type, active_slot)` 限制。MySQL 唯一键允许多个 NULL,因此明确未执行失败后可置空占位并创建新尝试。任务最多对应一笔 `rent_transaction`。成功委托占位保留以追溯原本金,回收任务另行占位。
委托的 reservation_status 使用 HELD、COMMITTED、RELEASED;回收固定 NONE,不再次预留委托本金。钱包执行占位在终结并写入快照屏障后置 NULL,订单关系占位继续保留。可重试失败保留订单资金 HELD;最终失败才解冻,不能既解冻又重试。
投递 ACK 不表示接受或成功;发送次数不是链上执行次数。丢 ACK 重发同任务及 message_id,不能重构授权意图或重签另一笔交易。
### 2.10 rent_transaction:链上事实与核验证据
**设计功能:** 保存任务唯一交易及云端独立核验结果。
| 关键字段 | 功能 |
| --- | --- |
| `task_id / network / tx_id` | 任务与链上交易身份 |
| `owner_address / receiver_address / transaction_type / resource_type` | 实际交易参数 |
| `amount_sun` | 实际委托或回收本金 |
| `verified_total_* / verified_resource_quantity` | 确认区块参数及本单资源额度 |
| `baseline_sun / after_sun` | 同地址对同资源类型的前后关系证据 |
| `block_height / evidence / confirmed_at` | 确认高度、证据和时间 |
| `block_time` | 独立查询交易所在区块的 UTC 时间,作为服务起点 |
| `status / next_check_at` | REPORTED、CONFIRMED、FAILED、UNKNOWN 及核对计划 |
**功能流程:** Agent 上报原 txId → 云端查询交易、回执和委托关系 → 校验网络、地址、类型、金额及确认规则 → 委托额覆盖冗余目标才可认定交付成功 → 更新任务和订单。未知则继续查询原 txId。
**协同关系:** `task_id` 唯一,每任务最多一笔交易;`(network, tx_id)` 唯一,防止同笔交易重复归属。节点自报、HTTP 成功或接收方瞬时可用余额变化不能直接作为本单交付依据。
链上 CONFIRMED 与订单 SUCCESS 分开:实际已委托但资源不足也应确认链上事实、转换本金预留并安排回收,订单转 MANUAL_REVIEW,不能谎报链上失败或提前扣款。
### 2.11 rent_ledger:不可变资金流水
**设计功能:** 记录余额变化及平台供应商手续费,提供幂等、追溯和对账依据。
| 字段组 | 功能 |
| --- | --- |
| `account_id / business_key / event_type` | 账户、全局唯一记账键和业务事件 |
| `delta_available / delta_frozen / delta_supplier_pending` | 三类余额增量 |
| `after_available / after_frozen / after_supplier_pending` | 变更后余额 |
| `delta_platform_fee` | 平台供应商手续费收入变化,不是用户可提款余额 |
| `order_id / settlement_id / reversal_of_id` | 来源订单、结算单及冲正对象 |
| `refund_id` | 本次退款和相关冲正来源,关联 rent_refund |
| `operator_user_id / evidence_ref / reason` | 操作者及核验依据 |
**功能流程:** 锁账户 → 校验业务状态和记账键 → 修改余额并追加流水 → 同事务更新业务状态和审计。纠错通过追加 REVERSAL 等流水,不覆盖旧记录。
| 事件 | 典型余额变化 |
| --- | --- |
| TOPUP | 可用 +金额 |
| HOLD | 可用 -售价,冻结 +售价 |
| CHARGE | 冻结 -售价 |
| RELEASE | 冻结 -售价,可用 +售价 |
| SUPPLIER_EARN | 待结算 +毛收入 |
| SUPPLIER_FEE | 待结算 -手续费,平台手续费 +手续费 |
| SETTLE | 待结算 -结算额 |
| REFUND / REVERSAL | 按审核规则追加退款或冲正增量 |
**协同关系:** 关联账户、订单、结算及原流水。账户是余额投影,流水是变更历史。充值必须通过规范化全局唯一凭据构造 business_key;`evidence_ref` 自身没有唯一索引,不能单靠该字段防重复入账。
### 2.12 rent_settlement:人工结算单
**设计功能:** 管理供应商净应收的审核、人工付款和付款核验。
| 关键字段 | 功能 |
| --- | --- |
| `settlement_no / account_id / amount` | 结算编号、供应商账户及总额 |
| `status` | PENDING、APPROVED、PAYING、PAID、REJECTED、UNKNOWN |
| `payout_no / payment_started_at` | 出款前持久化的唯一付款授权及时间 |
| `payment_reference / payment_evidence` | 全局唯一标准化付款凭据和核验结果 |
| `created_by / approved_by / paid_at` | 发起、审批及核验时间 |
**功能流程:** 锁账户和来源订单 → 检查可结算净应收 → 创建结算单及明细 → 独立人员审批 → 先提交 PAYING 和唯一 payout_no → 人工付款 → 核验唯一付款凭据 → 同事务扣待结算余额、写 SETTLE 流水、标记 PAID 并审计。
**协同关系:** 账户确定付款对象,明细确定来源订单,流水记录实际扣减。审批不提前扣余额。UNKNOWN 保留来源占用,不得重付;仅明确未付并拒绝时释放。
PAYING 同样禁止普通拒绝和重复出款;必须先核验原授权明确未付且作废,才能拒绝释放。超时不能自动认定未付款。
### 2.13 rent_settlement_item:结算来源明细
**设计功能:** 关联结算单和订单,防止同一来源重复结算。
| 关键字段 | 功能 |
| --- | --- |
| `settlement_id / order_id` | 结算单及来源订单 |
| `amount` | 本单净可结算额 |
| `active_slot` | 占用或已付款取 1,明确拒绝且未付款才置 NULL |
**功能流程:** 锁定成功且核验通过的订单 → 计算 `supplier_net_amount - supplier_reversed_amount + supplier_fee_returned_amount` → 插入明细占位 → 汇总结算总额 → 付款后永久保留有效占位。唯一键 `(order_id, active_slot)` 防止重复占用和重复付款。
**协同关系:** 一张结算单包含多笔订单;首版每笔订单只全额结算一次,不能拆到多个批次。结算按净应收计算,不再次扣手续费。
### 2.14 rent_webhook:商户回调持久队列
**设计功能:** 可靠通知商户订单 SUCCESS、FAILED、CANCELLED、REFUNDED、RECLAIMED 事件。
| 关键字段 | 功能 |
| --- | --- |
| `event_no / order_id / event_type` | 稳定事件编号及订单事件类型 |
| `event_key / order_event_sequence` | 业务事件去重键及订单内递增序号,支持逐次部分退款 |
| `payload` | 固定业务内容,不暴露内部成本或 Secret |
| `status` | PENDING、SENDING、ACKED、DEAD |
| `attempt_count / next_attempt_at` | 重试次数与退避计划 |
| `credential_id` | 最近使用的商户凭证 |
| `lock_owner / lock_until / last_error` | worker 租约及脱敏失败信息 |
**功能流程:** 订单状态变更同事务入队 → worker 抢占 → 校验地址、DNS、重定向等 SSRF 风险 → 使用所属 APP 的有效凭证签名发送 → HTTP 200 且正文 ok 才 ACKED → 失败退避重试 → 超限 DEAD 并告警。
**协同关系:** 订单提供应用归属和回调地址快照,凭证表提供认证。重试保持同一 event_no、event_key、序号和业务内容,重新生成时间戳和 nonce。普通事件键为 ORDER:id:type,退款为 REFUND:refund_no;移除旧的 `(order_id,event_type)` 唯一限制,改用 event_key 和 `(order_id,order_event_sequence)` 唯一。锁订单后分配序号,商户按 event_no 去重并按序号识别乱序。
### 2.15 rent_event:追加业务审计
**设计功能:** 记录关键操作、状态变化及节点结果事件去重。
| 关键字段 | 功能 |
| --- | --- |
| `event_no` | 全局唯一事件编号,节点来源使用 nodeId:eventId |
| `object_type / object_id` | APP、NODE、WALLET、PACKAGE、ORDER、TASK、ACCOUNT、SETTLEMENT 等对象 |
| `action / actor_user_id / node_id` | 动作、用户和节点来源 |
| `detail / reason` | 脱敏前后状态、证据和操作依据 |
**功能流程:** 关键操作产生事件 → 与业务状态同事务写入 → 节点重复回报按唯一事件去重,相同编号不同内容拒绝 → 提交成功才返回 RESULT_ACK → 按对象查询完整操作历史。
**协同关系:** 横向关联各业务表,记录操作依据;资金以 `rent_ledger` 为准,链上事实以 `rent_transaction` 为准。普通心跳不逐条写审计,避免无效膨胀。
### 2.16 rent_refund:内部余额退款与费用调整
**设计功能:** 让每次部分退款具有独立审批、稳定幂等编号及对应流水和回调,避免重复点击重复退款。
| 关键字段 | 功能 |
| --- | --- |
| `refund_no / order_id / request_no / request_hash` | 平台编号、原订单和同订单请求幂等 |
| `refund_amount` | 商户内部余额返还额,大于 0,含退商户手续费部分 |
| `supplier_reverse_amount` | 供应商原净应收冲正额 |
| `platform_fee_reverse_amount / fee_return_to` | 平台退费金额及 NONE、MERCHANT、SUPPLIER 方向 |
| `status / created_by / approved_by / applied_at` | PENDING、APPLIED、REJECTED;独立审批及生效时间 |
**功能流程:** 创建请求 → 同编号同摘要返回原单,不同摘要拒绝 → 独立审批 → 重新锁定校验订单、账户、结算来源和累计上限 → 同事务返还余额、调整应收及平台手续费、写流水、更新订单累计和退款 APPLIED、创建独立 REFUNDED 回调并审计。
**协同关系:** 仅处理已 CHARGED 且已记收入订单;HELD 走解冻。PENDING 不改余额也不占用退款额度,审批时竞争同一订单行重新核验。退供应商手续费增加订单 supplier_fee_returned_amount 和待结算,纳入结算来源;退商户的手续费已包含在 refund_amount,不能另加一次。涉及供应商或手续费变化且来源已结算/被占用时拒绝应用,转人工处置。
## 3. 主要表间协同关系
```mermaid
flowchart TD
U["共享 sys_user"] --> A["rent_app 商户应用"]
U --> N["rent_node 供应节点"]
U --> AC["rent_account 资金账户"]
A --> C["rent_credential 凭证"]
N --> C
C --> NO["rent_nonce 防重放"]
N --> W["rent_wallet 供应钱包"]
A --> O["rent_order 订单"]
P["rent_package 套餐版本"] --> O
AC --> O
W --> O
O --> T["rent_task 委托与回收任务"]
W --> T
N --> T
T --> TX["rent_transaction 链上证据"]
AC --> L["rent_ledger 资金流水"]
O --> L
AC --> S["rent_settlement 结算单"]
S --> SI["rent_settlement_item 结算明细"]
O --> SI
S --> L
O --> WH["rent_webhook 回调队列"]
O --> R["rent_refund 退款单"]
R --> L
R --> WH
E["rent_event 关键审计"] -.-> O
E -.-> T
E -.-> AC
E -.-> S
```
图中为主要业务关联,不表示数据库已声明物理外键;审计还覆盖应用、节点、钱包和套餐。
| 关联 | 基数及用途 |
| --- | --- |
| sys_user → rent_app / rent_node | 一对多,分别为商户应用及供应节点归属 |
| sys_user → rent_account | 一对多,按网络唯一 |
| rent_app / rent_node → rent_credential | 一对多,通过 owner_type、owner_id 区分 |
| rent_credential → rent_nonce | 一对多,通过 api_key 关联认证记录 |
| rent_node → rent_wallet | 一对多;钱包首版只绑定一个节点 |
| rent_app / rent_package → rent_order | 一对多,保存订单归属和套餐来源 |
| rent_account → rent_order | 一对多,payer_account_id 指定商户付款账户 |
| rent_wallet → rent_order | 一对多,调度前订单钱包可为空 |
| rent_order → rent_task | 一对多,委托、回收及历史尝试 |
| rent_task → rent_transaction | 一对零或一,每任务最多一笔链上交易 |
| rent_account / rent_order → rent_ledger | 一对多,余额与订单资金变动 |
| rent_account → rent_settlement | 一对多,供应商结算批次 |
| rent_settlement → rent_settlement_item | 一对多,批次订单来源 |
| rent_order → rent_settlement_item | 可有历史拒绝明细,最多一个有效或已付占位 |
| rent_order → rent_webhook | 一对多,按业务事件去重,退款逐次独立 |
| rent_order → rent_refund | 一对多,每次部分退款保留独立记录 |
| rent_refund → rent_ledger | 一对多,商户退款、应收冲正和手续费调整分别记账 |
| 各业务对象 → rent_event | 一对多,通过 object_type、object_id 审计 |
## 4. 完整业务协同流程
### 4.1 开通和人工充值
1. 共用系统登录和权限授予;商户创建应用、供应商注册节点及钱包。
2. 为 APP 和 NODE 分别签发凭证;钱包完成消息签名验证、链上权限核验及审核。
3. Agent 配置本地钱包、保留本金和费用限制;广播默认关闭,只能供应商本地明确允许。
4. 运营独立核验 USDT 充值凭据,锁账户后增加可用余额,同事务写 TOPUP 流水及审计。
5. 充值凭据规范化并构造全局唯一 business_key,阻止同凭据给不同账户重复入账。本版无待审核充值单表。
### 4.2 下单与资金冻结
1. 校验应用凭证、签名、消息时效及 nonce,或使用系统登录身份和权限。
2. 按 `(app_id, merchant_order_no)` 查重;相同摘要返回原订单,不同内容拒绝。
3. 锁套餐和账户,检查上架、网络、地址、资源、规则、费用及余额。
4. 同事务创建订单并锁定快照,扣可用、加冻结,追加 HOLD 流水和审计。
5. 订单进入 WAITING,资金 HELD,回收 NOT_STARTED,保存 dispatch_deadline。
### 4.3 冗余换算与资源预留
设请求数量为 Q,正冗余百分数为 R,该资源全网总额度为 L、TRX 权重为 W:
```text
目标资源量 T = max(Q + 1, ceil(Q × (1 + R / 100)))
委托本金 TRX = ceil(T × W / L)
委托本金 SUN = 委托本金 TRX × 1,000,000
预计资源量 E = floor(SUN × L / (W × 1,000,000))
要求:Q > 0,R > 0,L > 0,W > 0,E >= T > Q
```
1. 选择已审核、在线、快照有效且对应资源开启的钱包。
2. 使用对应资源的当前参数精确换算,不能用固定 TRX 汇率。
3. 锁订单和钱包,检查截止、地址对占位、钱包执行占位、可信快照屏障及可调度本金,增加该类型 reserved_sun,固定供应商账户。
4. 创建包含完整授权意图及换算证据的 DELEGATE 任务,订单进入 EXECUTING。
5. 事务提交后推送任务。链上调用不作为数据库原子事务的一部分,通过持久状态恢复衔接。
### 4.4 Agent 执行与云端核验
1. Agent 持久化原任务后回 ACK,再验证 HMAC、期限、本地授权、费用及实时资源。
2. 如原授权本金已不足且明确未构建或广播,可拒绝任务,由云端释放旧占位并重新换算新尝试;Agent 不能擅自放大本金。
3. 一次构建签名交易,先持久化原交易及 txId 再广播;重试查原交易,不重签另一笔。
4. 云端独立核验网络、地址、资源类型、SUN、回执、确认区块及关系变化。
5. 实际确认资源量覆盖冗余目标,才能成功记账。
6. 链上已委托但交付不足时进入人工核对,保留资金及本金记录并安排回收,不自动补委托。
### 4.5 成功扣款与供应商应收
云端核验交付达标且尚未到期后,同事务完成:交易 CONFIRMED、任务 VERIFIED、订单 SUCCESS、资金 CHARGED、扣冻结、供应商收入和手续费流水、预留转换、钱包快照屏障及执行占位释放、服务起止、回收计划、SUCCESS 回调及审计。服务起点取交易 block_time,核验时间不延长租期。已委托但交付不达标也必须确认链上事实和处理预留、回收,订单保持人工核对。
```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 <= 商户售价
```
先追加 SUPPLIER_EARN:待结算 +G;再追加 SUPPLIER_FEE:待结算 -F、平台手续费 +F。最终供应商待结算净增 N。各流水按顺序保存变更后余额,多账户按 account_id 顺序加锁,同一账户只锁一次。
例如售价 12 USDT、毛收入 10 USDT、示例费率 5%,供应商净应收 9.5 USDT。平台收入统计为售价减毛收入加手续费,即 2.5 USDT(未扣其他成本);不能在售价减净应收后再次加手续费。5% 仅为示例。
### 4.6 明确失败、取消及未知结果
| 情况 | 协同处理 |
| --- | --- |
| WAITING 且未生成执行任务的取消 | 锁订单裁决,解冻资金,写 RELEASE、CANCELLED 回调及审计 |
| 明确未执行的可重试失败 | 只释放资源及旧任务占位,保留订单 HELD 资金,截止前重试;不发终态 FAILED |
| 明确终结失败 | 释放资金及资源,写 RELEASE 和 FAILED 回调,不再重试该订单 |
| 无供应方等待超时 | 按公开等待上限取消并释放资金 |
| 已广播但结果未知、节点离线 | 保留资金和资源占用,核对原 txId,不盲目重派 |
| 链上已委托但交付不足 | MANUAL_REVIEW,保留事实并追踪回收,经审核处置 |
普通失败释放冻结是解冻;成功扣款后返还内部余额才是退款。
### 4.7 到期回收
1. 扫描订单回收计划,包括已委托但未正常成功的异常订单。
2. 使用原确认交易的资源类型和 SUN 本金创建 RECLAIM 任务并保存 source_transaction_id,不按当前参数重算撤销金额;回收 reservation_status=NONE。
3. 同钱包同类型链上操作串行,同地址对同类型只允许一笔占位订单,避免混入其他订单份额。
4. 未解锁则安排下次检查;结果未知继续隔离;部分可回收或份额异常转人工。
5. 撤销确认后若资源尚未恢复,回收状态 RECOVERING。
6. 撤销确认时先写快照屏障、失效旧快照再释放执行占位;本金回收且资源恢复后应用可信新快照,回收 DONE,释放订单 relation_slot,写 RECLAIMED 回调及审计。
回收不改变原履约成功事实,也不自动退款。
### 4.8 人工结算与退款
**结算:** 锁供应商账户及来源订单 → 选择已核验且未被占用的净应收 → 创建结算单及明细 → 独立审批 → 提交 PAYING、唯一 payout_no → 人工付款 → 独立核验唯一付款凭据 → 同事务扣待结算、写 SETTLE、标记 PAID 并审计。PAYING 或付款未知不得重付或释放来源。
**退款:** 创建 rent_refund 幂等请求 → 独立审批费用承担 → 按统一顺序锁账户、订单、退款单并检查结算来源及累计上限 → 追加 REFUND / REVERSAL → 更新订单累计和退款 APPLIED → 同事务写本次退款独立回调及审计。供应商或手续费变化遇到已结算、结算占用或应付不足时转人工;单纯平台承担的商户退款可独立审核。不得制造负余额或重复返还手续费。
## 5. 关键事务与幂等边界
| 操作 | 必须原子协同的主要记录 |
| --- | --- |
| 充值 | account + ledger + event |
| 下单冻结 | order + account + ledger + event |
| 分配执行任务 | order + wallet 预留 + task + event |
| 委托核验成功 | transaction + task + order + wallet + account + ledger + webhook + event |
| 明确失败释放 | task / transaction 状态 + order + wallet + account + ledger + webhook + event,按实际发生阶段处理 |
| 创建结算 | settlement + settlement_item + 来源资格及账户余额锁定校验 + event |
| 确认付款 | settlement + account + ledger + event,明细有效占位继续保留 |
| 退款冲正 | refund + order + account + ledger + webhook + event,并锁定校验结算来源状态 |
| 保护层 | 主要唯一约束或机制 |
| --- | --- |
| 消息重放 | nonce(api_key, scope, nonce) |
| 重复下单 | order(app_id, merchant_order_no) + request_hash |
| 重复有效任务 | task(order_id, task_type, active_slot) |
| 重复任务投递 | 稳定 delivery_message_id + Agent 本地持久幂等 |
| 重复交易归属 | transaction(task_id)、transaction(network, tx_id) |
| 重复记账 | ledger(business_key) |
| 重复结算来源 | settlement_item(order_id, active_slot) |
| 重复付款凭据 | settlement(payment_reference) |
| 重复退款请求 | refund(order_id, request_no) + request_hash |
| 重复回调事件 | webhook(event_no)、webhook(event_key)、webhook(order_id, order_event_sequence) |
| 地址对在租互斥 | order(wallet_id, receiver_address, resource_type, relation_slot) |
| 钱包链上操作互斥 | task(wallet_id, resource_type, wallet_execution_slot) |
| 节点重复上报 | event(event_no),相同编号不同内容拒绝 |
| 旧连接覆盖新连接 | node.session_epoch 条件更新 |
## 6. 对账与实现注意事项
1. 每日核对账户冻结余额与 HELD 订单、待结算余额与未结净应收、余额投影与不可变流水;差异记录审计并人工处理。
2. 钱包在途预留与 HELD 任务逐笔对应;确认成功时避免链上已扣减和本地预留重复扣减,保留其他未知任务占用。
3. 资源快照必须可信且未过期;Agent 签名前再次查询。冗余是确认时缓冲,不保证整个租期资源额度恒定。
4. Socket 仅负责传输;任务数据库和 Agent 本地持久化负责恢复。断线重连先同步,再允许新单。
5. 本版不是完整复式会计总账,也不包含自动充值识别、自动出金、动态报价或供应商竞价。
6. 初始化脚本的 `IF NOT EXISTS` 不能升级已有旧表;本文仅说明设计,没有执行建表、迁移或资金操作。
+36
View File
@@ -0,0 +1,36 @@
# V2.2 设计验证记录
## 验证范围
本次验证针对初始化 SQL、逐表文档、唯一索引语义及精确金额算例。没有连接或修改项目现有数据库,没有进行真实链上交易。
## 检查方式
1. 使用 SQLGlot 26.33.0 的 MySQL 方言解析完整 rent_init.sql:16 条 CREATE TABLE,0 条不支持的回退命令。该依赖仅安装于临时工具目录,不加入项目依赖。
2. 运行标准库脚本 `python docs/rental/check_schema.py`:从实际 DDL 提取列名和唯一键,在 SQLite 内存库检查重复插入及 NULL 占位语义;同时核对 16 张表文档覆盖、列注释、索引字段引用、本地文档链接及无破坏性语句。
3. 使用 Decimal 核对供应商手续费返还、净额冲正与结算来源一致,以及商户退款中手续费不重复入账。
## 结果
SQLGlot 严格 MySQL 方言解析通过:16 条 CREATE TABLE,无回退命令。离线脚本 12 项检查全部通过:
- 16 表及逐表文档一一覆盖、字段注释、唯一索引字段、无破坏性语句。
- 本地 Markdown 链接存在。
- 同地址对同资源类型互斥及 NULL 释放,多接收者/不同类型可并存。
- 同钱包同类型的委托与回收共享执行互斥。
- 同订单任务尝试与有效占位去重。
- 退款请求去重,同订单多次部分退款回调可写入且业务键、序号防重复。
- 出款授权与付款凭据唯一,未付款 NULL 可并存。
- 结算来源唯一,已付来源不能再占用。
- 跨账户重复充值业务键冲突。
- 一任务一交易及同网络交易哈希去重。
- Decimal 金额例中供应商返还手续费与结算来源一致,商户退款不重复加手续费。
脚本实际总数为 12。首轮发现验证记录尚未创建,以及一个记账键长度示例断言不成立;均已修正并完整重跑通过。
## 未覆盖内容
- 当前机器 Docker Linux 引擎未启动,也未发现可直接使用的 MySQL/MariaDB 命令。因此没有声称 MySQL 5.7/8.0 真实建表、索引字节限制、事务隔离或死锁测试通过。
- SQLite 映射仅验证实际唯一键的等值冲突及 NULL 语义,未模拟 MySQL 字段类型、字符集、外键或业务状态机。
- 租赁应用服务和 Agent 尚未实现,无法验证真实并发记账、CAS、出款恢复、断线恢复、HMAC 或状态转换;验收要求见 business-review-v2.2.md 第 8 节。
- 未执行 NILE/MAINNET 委托或回收,非锁定委托条件、历史参数取证、资源使用债务及恢复判定仍需真实网络验证。