Files
usdt/docs/rental/table-functional-flows.md
T
2026-10-22 19:58:57 -04:00

521 lines
35 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.
# 能量与带宽租赁:逐表功能流程及协同关系
## 1. 文档依据与业务范围
本文依据 [rent_init.sql](../../sql/rent_init.sql) 及 [schema-design.md](schema-design.md) 的 V2.2 设计整理,覆盖全部16张表。复核发现、并发协议和迁移要求见 [business-review-v2.2.md](business-review-v2.2.md)。三端实现已新增,入口、配置及验证边界见[implementation.md](implementation.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` 不能升级已有旧表;本文仅说明设计,没有执行建表、迁移或资金操作。