Files
usdt/docs/rental/business-review-v2.2.md
T
2026-10-22 11:09:36 -04:00

236 lines
23 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
## 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 资源恢复实测。