Files
usdt/docs/rental/user-package-bindings.md

57 lines
5.7 KiB
Markdown
Raw Permalink 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.
# 用户分类套餐绑定与下单
当前规则:一个系统用户在每个“网络 + 资源类型”分类最多一个当前套餐。同一用户最多四个分类:NILE/ENERGY、NILE/BANDWIDTH、MAINNET/ENERGY、MAINNET/BANDWIDTH。所有租赁应用通过 rent_app.user_id 共用绑定。DURATION、PER_ORDER 是计费模式,不增加独立绑定名额;地址上链不需要套餐。
## 数据与业务流程
rent_user_package 保存 user_id、package_id、network、resource_type、status、default_slot、created_by、version、created_at、updated_at。network/resource_type 从服务端套餐记录复制,不接受客户端覆盖。唯一键 (user_id,package_id) 防止重复绑定,(user_id,network,resource_type,default_slot) 保护分类唯一。当前项 ACTIVE/default_slot=1,停用和历史项 DISABLED/default_slot=NULL。
管理员在“租赁套餐”的用户套餐绑定区选择用户及上架套餐。绑定事务锁定用户和套餐,只停用相同网络及资源类型的其他当前项,写入审计和分类日志。其他分类不变。停用不会自动选择其他历史套餐;下架套餐不能下单。已有绑定记录的套餐不能直接修改网络或资源类型,应新建套餐版本后重新绑定。
“我的套餐”切换网络,分别显示能量、带宽卡片及未绑定引导。立即租赁预选所选卡片的网络和资源类型,可在弹窗切换;切换后重置资源数量、租期及报价。请求仅提交network/resource_type,不传套餐ID,先报价,再确认费用创建订单。资金按套餐网络冻结,两个网络余额独立。首页监控也分别显示所选网络的两类套餐状态。
## API 选择规则
POST /api/rental/v1/packages:network 必填,resource_type 可选;只返回本人当前绑定且已上架的套餐,不筛选资源类型时最多两项。不要直接选择返回数组的第一项。
quote 和 create 共用分类解析器:
1. network和resource_type均必填,分别为NILE/MAINNET与ENERGY/BANDWIDTH;服务端从应用归属的user_id解析当前有效绑定。
2. 请求禁止提交package_id,包括空字符串或NULL;响应中的内部套餐编号只用于查询与审计,不能作为下单入参。
3. 多候选、未绑定、绑定停用、套餐下架、网络或资源不匹配均明确拒绝,不回退到任意公开套餐。
4. user_id 来自应用归属,客户端提交不会改变授权。旧客户端必须同步升级为提交network/resource_type并移除package_id。
5. 原商户单号幂等重试保持原套餐和价格快照;绑定更换或增加其他分类不会重复冻结。重试仍必须提交网络和资源,且必须与原订单一致。
分类自动选择示例:
```json
{
"network": "NILE",
"resource_type": "ENERGY",
"receiver_address": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
"merchant_order_no": "RENT-001"
}
```
实际集成应保留报价使用的network、resource_type、资源数量及租期,并将报价amount以expected_amount提交下单;服务端按当前分类绑定重新计价,价格变化则拒绝。订单内部仍保存package_id及不可变快照;原商户单号重试不会重新匹配新套餐。API调试台支持网络、资源类型筛选,并要求从套餐结果中明确选择。
## 部署
新库执行 sql/rent_init.sql。尚无绑定表的旧库先执行 sql/rent_user_package.sql。**已存在绑定表的数据库,备份并停服后执行 sql/rent_user_package_scope.sql,再部署新版后端及前端。** CREATE TABLE IF NOT EXISTS 无法升级旧表。
增量脚本从套餐回填网络、资源类型,先检查孤立引用和分类槽位冲突,再新增分类唯一键并移除 uk_user_default。保留所有历史绑定和订单;不恢复之前已停用的授权。脚本支持重跑,但MySQL DDL隐式提交,发生错误时须修复数据后继续,不能依赖事务回滚全部DDL。执行账户需要建表变更及存储过程权限。
sql/rent_user_package_single.sql 已改为按分类收敛,不再全局停用其他分类。一般升级不需执行;仅在人工核对异常 ACTIVE/NULL 数据后按需使用。
sql/rent_seed_three_packages.sql 仍创建三个NILE示例套餐。指定 @rental_user_id 时,可分别绑定基础65000能量和1500带宽;不同时绑定两个能量套餐,不覆盖已有同分类当前项、历史绑定或价格。示例价格仅用于演示,不自动授权现有用户。
管理接口不变:GET /rental/package/users、GET /rental/package/options、GET /rental/package/bindings/{userId}、POST /rental/package/bind,需要 rent:package:edit;GET /rental/package/bindings 查看本人。is_default 保留兼容,启用即当前分类项,停用清空槽位。
## 验证
隔离测试覆盖四分类共存、同分类替换、停用隔离、越权与不匹配拒绝、多候选拒绝、签名API套餐筛选及报价下单一致性、数据库唯一键、并发绑定串行化、原订单重试与首页网络隔离。使用H2真实事务及行锁,不连接生产数据库或TRON。部署前仍需在目标MySQL版本验证迁移,并做真实登录联调。
本次验证:JDK8 Rental*Test 共115项通过;8个相关前端文件ESLint、Vue模板及分类交互验证、staging完整构建通过。构建保留其他模块已有的3项API导出缺失及包体积警告,产物位于 usdt-ui/dist-rental-package-scope-preview。未执行实际数据库升级或生产部署。
取消套餐ID入参的后续验证:116项Rental*Test、6个相关文件ESLint、分类切换/报价重置/请求不含ID/调试台拒绝旧参数交互检查及最终staging构建通过,保留上述已有构建警告。本次接口调整无新增SQL;前后端及商户调用方应一起升级。