From dc2564b1d4f8b0b4096785c7828e92e4cc965bf8 Mon Sep 17 00:00:00 2001 From: luqingjie <544309509@qq.com> Date: Thu, 29 Oct 2026 21:50:00 -0400 Subject: [PATCH] =?UTF-8?q?=E5=B8=AE=E6=88=91=E6=8A=8A=E5=9C=B0=E5=9D=80?= =?UTF-8?q?=E4=B8=8A=E9=93=BE=E6=8E=A5=E5=8F=A3=20=20=E5=8D=95=E7=8B=AC?= =?UTF-8?q?=E5=88=86=E5=87=BA=E6=9D=A5=E4=B8=80=E4=B8=AA=E6=8E=A5=E5=8F=A3?= =?UTF-8?q?=EF=BC=8C=E5=90=8C=E6=97=B6=E4=BF=AE=E6=94=B9=E5=AF=B9=E5=BA=94?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/rental-address-onchain.md | 18 +++--- docs/rental/implementation.md | 2 +- .../system/rental/RentalApiController.java | 20 +++++++ .../system/rental/RentalBusinessTest.java | 59 +++++++++++++++++++ 4 files changed, 90 insertions(+), 9 deletions(-) diff --git a/docs/rental-address-onchain.md b/docs/rental-address-onchain.md index 865fcf8..66c417f 100644 --- a/docs/rental-address-onchain.md +++ b/docs/rental-address-onchain.md @@ -4,7 +4,7 @@ 用户在“我的套餐”或“我的订单”中的“地址上链”卡片输入网络、接收地址及应用凭证,获取报价后确认。即使没有资源套餐,也能创建地址上链订单。供应商通过原有 rent_node 及已证明所有权的 rent_wallet 执行,不需要供应商创建 rent_app。 -订单类型为 `ADDRESS_ONCHAIN`;省略类型继续走原有 `RESOURCE_RENTAL` 资源租赁。两者使用同一签名、应用归属、商户单号幂等、账务、回调和查询机制。 +地址上链使用独立路径 `/api/rental/v1/address-onchain/quote`、`/create`、`/query`,订单类型由路径固定为 `ADDRESS_ONCHAIN`,请求可省略order_type;若提交只能为ADDRESS_ONCHAIN。原 `/api/rental/v1/quote`、`/create`、`/query` 仅处理 `RESOURCE_RENTAL`,拒绝混用订单类型。两者复用签名、应用归属、商户单号幂等、账务及回调机制。原地址上链接入方需同时更新请求URL和HMAC签名中的完整路径,不能用旧路径签名请求新接口;已有订单可通过新的query路径按原商户单号查询。 每笔固定转出 **1 TRX = 1000000 SUN**。USDT 本金折价 = `ceil6(1 × trx-price-usdt)`;固定服务费 = `ceil6(service-fee-usdt)`;总金额为两者之和。示例汇率0.15、固定服务费0.05,总冻结0.200000 USDT。所有运算使用 BigDecimal,不使用浮点数。NILE 和 MAINNET 汇率、服务费分别配置,未配置不允许下单,不自动取另一网络价格。 @@ -31,8 +31,8 @@ ## 流程与失败处理 -1. `/quote` 校验当前网络配置及地址,计算USDT报价,不冻结资金。 -2. `/create` 锁定应用,按 `app_id + merchant_order_no` 幂等,保存价格快照、冻结用户USDT可用余额。重试命中原单不重读价格、不再次冻结;`expected_amount` 不匹配拒绝。网络、接收者、订单类型变化拒绝复用原商户单号。 +1. `/api/rental/v1/address-onchain/quote` 校验当前网络配置及地址,计算USDT报价,不冻结资金。 +2. `/api/rental/v1/address-onchain/create` 锁定应用,按 `app_id + merchant_order_no` 幂等,保存价格快照、冻结用户USDT可用余额。重试命中原单不重读价格、不再次冻结;`expected_amount` 不匹配拒绝。网络、接收者、订单类型变化拒绝复用原商户单号。 3. 云端只选择当前在线、审核通过、钱包所有权已证明、明确声明 `transfer_enabled` 的供应节点。检查候选TRX余额,持有钱包TRX执行槽,签发 `TRANSFER_TRX` 原生任务。旧Agent未声明能力,不会收到转账任务。 4. Agent确认 `RENT_TRANSFER_ENABLED=true`、总广播授权、同网络、本地钱包owner、固定1000000 SUN、接收者、余额、权限、当前带宽费率、未激活地址创建费及留存。构建单个TransferContract,独立检查原始protobuf与授权一致后本地签名,先加密落盘再广播。 5. 云端在订单网络独立查交易与确认回执,核对交易类型、唯一合约、owner、to、1000000 SUN、授权时间及确认深度。节点自报SUCCESS/RESULT不能触发扣款。 @@ -81,22 +81,24 @@ rental: 仅在计划使用的网络配置正汇率、非负服务费。供应商Agent新增 `RENT_TRANSFER_ENABLED=false`,明确同意转账后改为true并重新连接。`RENT_MAX_SUN`至少1000000;`RENT_MAX_FEE_SUN`不小于订单fee-limit-sun;余额覆盖转出本金、保守链上费用与`RENT_TRX_RETAIN_SUN`。这两个限额单位均为SUN。JavaFX每次启动仍默认关闭总广播,必须手动开启。 -原有应用签名下单API即可使用,无需额外菜单权限。网页公开API文档访问 `/rental-api`,已经加入该类型示例。 +使用原有应用凭证调用新的地址上链独立API,无需额外菜单权限。网页公开API文档访问 `/rental-api`,所有独立接口及示例统一列在接口列表中。 ## API 示例 -`POST /api/rental/v1/quote`,请求头及HMAC签名与资源租赁一致: +`POST /api/rental/v1/address-onchain/quote`,请求头及HMAC签名与资源租赁一致: ```json -{"order_type":"ADDRESS_ONCHAIN","network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"} +{"network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"} ``` -`POST /api/rental/v1/create`: +`POST /api/rental/v1/address-onchain/create`: ```json -{"order_type":"ADDRESS_ONCHAIN","network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","merchant_order_no":"ADDR-DEMO-001","expected_amount":"0.200000"} +{"network":"NILE","receiver_address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","merchant_order_no":"ADDR-DEMO-001","expected_amount":"0.200000"} ``` +查询:`POST /api/rental/v1/address-onchain/query`,请求 `{"merchant_order_no":"ADDR-DEMO-001"}`。 + 不得传入package_id、resource_type、resource_quantity、duration_seconds、transfer_sun。金额示例不是实际配置价格。query按merchant_order_no查询;响应及回调增加order_type、transfer_sun、principal_usdt、service_fee_usdt、transaction_id,金额单位USDT。transaction_id仅在云端独立确认转账后提供,确认前为空。回调接收方照旧验签、按event_no去重、仅在业务落库成功后返回正文ok。 ## 日志排查 diff --git a/docs/rental/implementation.md b/docs/rental/implementation.md index b7eddc3..e2aec08 100644 --- a/docs/rental/implementation.md +++ b/docs/rental/implementation.md @@ -110,7 +110,7 @@ node --env-file=.env src/index.js ## 6. 外部商户签名接口 -`POST /api/rental/v1/create`、`query`、`packages`,仅JSON,最多512KiB(524,288字节),不允许查询串。请求头为 `X-Rent-Key`、`X-Rent-Timestamp`(Unix毫秒)、`X-Rent-Nonce`、`X-Rent-Signature`。认证窗口前后60秒,nonce保留180秒后可清理。 +资源租赁:`POST /api/rental/v1/quote`、`create`、`query`、`packages`。地址上链:`POST /api/rental/v1/address-onchain/quote`、`create`、`query`;独立路径确定ADDRESS_ONCHAIN类型,无需提交order_type,原资源接口不再接收地址上链订单。仅JSON,最多512KiB(524,288字节),不允许查询串。请求头为 `X-Rent-Key`、`X-Rent-Timestamp`(Unix毫秒)、`X-Rent-Nonce`、`X-Rent-Signature`。认证窗口前后60秒,nonce保留180秒后可清理。签名必须使用服务端实际完整路径,包含address-onchain子路径,不能沿用资源接口签名。 签名原文用换行连接,末尾不加换行: diff --git a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalApiController.java b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalApiController.java index bd667e6..cef4bc1 100644 --- a/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalApiController.java +++ b/ruoyi-system/src/main/java/com/ruoyi/system/rental/RentalApiController.java @@ -41,6 +41,20 @@ public class RentalApiController { @PostMapping(value = "/{operation}", consumes = "application/json") public AjaxResult execute(@PathVariable String operation, HttpServletRequest request) throws Exception { + return executeOperation(operation, request, false); + } + + /** 地址上链独立入口;认证仍覆盖实际请求URI,不能使用资源租赁路径的签名。 */ + @PostMapping(value = "/address-onchain/{operation}", consumes = "application/json") + public AjaxResult executeOnchain(@PathVariable String operation, HttpServletRequest request) + throws Exception { + require(Arrays.asList("quote", "create", "query").contains(operation), "不支持的地址上链接口"); + return executeOperation(operation, request, true); + } + + /** 复用原始请求读取、凭证校验和订单服务,按入口强制隔离订单类型。 */ + private AjaxResult executeOperation(String operation, HttpServletRequest request, boolean addressOnchain) + throws Exception { require( Arrays.asList("create", "query", "packages", "quote").contains(operation) && request.getQueryString() == null, @@ -77,6 +91,11 @@ public class RentalApiController { Map data = json.readValue(body, new TypeReference>() { }); + String expectedType = addressOnchain ? RentalOnchain.ORDER_TYPE : "RESOURCE_RENTAL"; + require(text(data, "order_type").isEmpty() || expectedType.equals(text(data, "order_type")), + addressOnchain ? "地址上链接口仅支持ADDRESS_ONCHAIN" : "地址上链请使用/api/rental/v1/address-onchain接口"); + // 类型由路由确定;无需客户端通过通用接口选择转账业务。 + data.put("order_type", expectedType); if ("packages".equals(operation)) { List> products = store.rows( @@ -125,6 +144,7 @@ public class RentalApiController { app.get("id"), input(data, "merchant_order_no", 64)); require(order != null, "订单不存在"); + require(addressOnchain == RentalOnchain.isOrder(order), "订单类型与接口不匹配"); } return AjaxResult.success( map( diff --git a/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalBusinessTest.java b/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalBusinessTest.java index cd9efa2..43d3e1d 100644 --- a/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalBusinessTest.java +++ b/ruoyi-system/src/test/java/com/ruoyi/system/rental/RentalBusinessTest.java @@ -576,6 +576,65 @@ public class RentalBusinessTest { assertEquals(money("80"), amount(store.get("account", payer, false), "available_amount")); } + /** 独立接口沿用真实APP验签与账务事务,拒绝跨订单类型调用。 */ + @Test + @SuppressWarnings("unchecked") + public void independentOnchainApiAuthenticatesActualPathAndIsolatesTypes() throws Exception { + Map credential = tx.execute(status -> identity.issue("APP", app, 10)); + String key = text(credential, "api_key"), secret = text(credential, "api_secret"); + RentalApiController controller = new RentalApiController(identity, store, orders, json); + java.lang.reflect.Field field = RentalApiController.class.getDeclaredField("onchain"); + field.setAccessible(true); + java.lang.reflect.Field serviceField = RentalOrders.class.getDeclaredField("onchain"); + serviceField.setAccessible(true); + field.set(controller, serviceField.get(orders)); + String prefix = "/api/rental/v1/address-onchain/"; + Map data = onchainRequest("API-ONCHAIN"); + data.remove("order_type"); + String body = json.writeValueAsString(data); + Map quote = (Map) controller.executeOnchain("quote", + signedRequest(prefix + "quote", body, key, secret, "API")).get("data"); + assertEquals("0.173457", quote.get("amount")); + assertFalse(quote.containsKey("supplier_fee_amount")); + javax.servlet.http.HttpServletRequest oldSignature = signedRequest( + "/api/rental/v1/quote", body, key, secret, "API"); + javax.servlet.http.HttpServletRequest newPathWithOldSignature = + (javax.servlet.http.HttpServletRequest) java.lang.reflect.Proxy.newProxyInstance( + getClass().getClassLoader(), new Class[] {javax.servlet.http.HttpServletRequest.class}, + (proxy, method, args) -> "getRequestURI".equals(method.getName()) + ? prefix + "quote" : method.invoke(oldSignature, args)); + try { + controller.executeOnchain("quote", newPathWithOldSignature); + fail("新路由不能复用旧路径签名"); + } catch (IllegalArgumentException expected) { /* HMAC包含实际完整URI */ } + Map created = (Map) tx.execute(status -> { + try { + return controller.executeOnchain("create", signedRequest(prefix + "create", body, key, secret, "API")); + } catch (Exception ex) { + throw new IllegalArgumentException(ex); + } + }).get("data"); + assertEquals("ADDRESS_ONCHAIN", text(created, "order_type")); + String queryBody = json.writeValueAsString(map("merchant_order_no", "API-ONCHAIN")); + Map queried = (Map) controller.executeOnchain("query", + signedRequest(prefix + "query", queryBody, key, secret, "API")).get("data"); + assertEquals(text(created, "order_no"), text(queried, "order_no")); + try { + controller.execute("query", signedRequest("/api/rental/v1/query", queryBody, key, secret, "API")); + fail("资源接口不能查询地址上链订单"); + } catch (IllegalArgumentException expected) { /* 类型隔离 */ } + data.put("order_type", "ADDRESS_ONCHAIN"); + try { + controller.execute("create", signedRequest("/api/rental/v1/create", json.writeValueAsString(data), key, secret, "API")); + fail("旧资源接口不得创建地址上链订单"); + } catch (IllegalArgumentException expected) { /* 不保留混用入口 */ } + data.put("order_type", "RESOURCE_RENTAL"); + try { + controller.executeOnchain("create", signedRequest(prefix + "create", json.writeValueAsString(data), key, secret, "API")); + fail("地址上链接口不得创建资源订单"); + } catch (IllegalArgumentException expected) { /* 类型不允许覆盖 */ } + } + /** Servlet代理保留原始字节,无需启动真实HTTP端口。 */ private javax.servlet.http.HttpServletRequest demoRequest(String operation, String body, String secret) { return signedRequest("/api/rental/v1/demo/callback/" + operation, body, "RKdemo", secret, "WEBHOOK");