基础代码生成
This commit is contained in:
1 parent
352d7d023f
commit
1c0544afe0
122 files changed
+21475
No files matched your search
@@ -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` 不能升级已有旧表;本文仅说明设计,没有执行建表、迁移或资金操作。
|
||||
Reference in new issue
Block a user