帮我把地址上链接口 单独分出来一个接口,同时修改对应文档

This commit is contained in:
lu7213 committed 2026-10-29 21:50:00 -04:00
1 parent fbc72b5b57
commit dc2564b1d4
4 files changed
+90 -9

No files matched your search

+10 -8
View File
@@ -4,7 +4,7 @@
用户在“我的套餐”或“我的订单”中的“地址上链”卡片输入网络、接收地址及应用凭证,获取报价后确认。即使没有资源套餐,也能创建地址上链订单。供应商通过原有 rent_node 及已证明所有权的 rent_wallet 执行,不需要供应商创建 rent_app。 用户在“我的套餐”或“我的订单”中的“地址上链”卡片输入网络、接收地址及应用凭证,获取报价后确认。即使没有资源套餐,也能创建地址上链订单。供应商通过原有 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 汇率、服务费分别配置,未配置不允许下单,不自动取另一网络价格。 每笔固定转出 **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报价,不冻结资金。 1. `/api/rental/v1/address-onchain/quote` 校验当前网络配置及地址,计算USDT报价,不冻结资金。
2. `/create` 锁定应用,按 `app_id + merchant_order_no` 幂等,保存价格快照、冻结用户USDT可用余额。重试命中原单不重读价格、不再次冻结;`expected_amount` 不匹配拒绝。网络、接收者、订单类型变化拒绝复用原商户单号。 2. `/api/rental/v1/address-onchain/create` 锁定应用,按 `app_id + merchant_order_no` 幂等,保存价格快照、冻结用户USDT可用余额。重试命中原单不重读价格、不再次冻结;`expected_amount` 不匹配拒绝。网络、接收者、订单类型变化拒绝复用原商户单号。
3. 云端只选择当前在线、审核通过、钱包所有权已证明、明确声明 `transfer_enabled` 的供应节点。检查候选TRX余额,持有钱包TRX执行槽,签发 `TRANSFER_TRX` 原生任务。旧Agent未声明能力,不会收到转账任务。 3. 云端只选择当前在线、审核通过、钱包所有权已证明、明确声明 `transfer_enabled` 的供应节点。检查候选TRX余额,持有钱包TRX执行槽,签发 `TRANSFER_TRX` 原生任务。旧Agent未声明能力,不会收到转账任务。
4. Agent确认 `RENT_TRANSFER_ENABLED=true`、总广播授权、同网络、本地钱包owner、固定1000000 SUN、接收者、余额、权限、当前带宽费率、未激活地址创建费及留存。构建单个TransferContract,独立检查原始protobuf与授权一致后本地签名,先加密落盘再广播。 4. Agent确认 `RENT_TRANSFER_ENABLED=true`、总广播授权、同网络、本地钱包owner、固定1000000 SUN、接收者、余额、权限、当前带宽费率、未激活地址创建费及留存。构建单个TransferContract,独立检查原始protobuf与授权一致后本地签名,先加密落盘再广播。
5. 云端在订单网络独立查交易与确认回执,核对交易类型、唯一合约、owner、to、1000000 SUN、授权时间及确认深度。节点自报SUCCESS/RESULT不能触发扣款。 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每次启动仍默认关闭总广播,必须手动开启。 仅在计划使用的网络配置正汇率、非负服务费。供应商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 示例 ## API 示例
`POST /api/rental/v1/quote`,请求头及HMAC签名与资源租赁一致: `POST /api/rental/v1/address-onchain/quote`,请求头及HMAC签名与资源租赁一致:
```json ```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 ```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。 不得传入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。
## 日志排查 ## 日志排查
+1 -1
View File
@@ -110,7 +110,7 @@ node --env-file=.env src/index.js
## 6. 外部商户签名接口 ## 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子路径,不能沿用资源接口签名。
签名原文用换行连接,末尾不加换行: 签名原文用换行连接,末尾不加换行:
@@ -41,6 +41,20 @@ public class RentalApiController {
@PostMapping(value = "/{operation}", consumes = "application/json") @PostMapping(value = "/{operation}", consumes = "application/json")
public AjaxResult execute(@PathVariable String operation, HttpServletRequest request) public AjaxResult execute(@PathVariable String operation, HttpServletRequest request)
throws Exception { 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( require(
Arrays.asList("create", "query", "packages", "quote").contains(operation) Arrays.asList("create", "query", "packages", "quote").contains(operation)
&& request.getQueryString() == null, && request.getQueryString() == null,
@@ -77,6 +91,11 @@ public class RentalApiController {
Map<String, Object> data = Map<String, Object> data =
json.readValue(body, new TypeReference<Map<String, Object>>() { json.readValue(body, new TypeReference<Map<String, Object>>() {
}); });
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)) { if ("packages".equals(operation)) {
List<Map<String, Object>> products = List<Map<String, Object>> products =
store.rows( store.rows(
@@ -125,6 +144,7 @@ public class RentalApiController {
app.get("id"), app.get("id"),
input(data, "merchant_order_no", 64)); input(data, "merchant_order_no", 64));
require(order != null, "订单不存在"); require(order != null, "订单不存在");
require(addressOnchain == RentalOnchain.isOrder(order), "订单类型与接口不匹配");
} }
return AjaxResult.success( return AjaxResult.success(
map( map(
@@ -576,6 +576,65 @@ public class RentalBusinessTest {
assertEquals(money("80"), amount(store.get("account", payer, false), "available_amount")); assertEquals(money("80"), amount(store.get("account", payer, false), "available_amount"));
} }
/** 独立接口沿用真实APP验签与账务事务,拒绝跨订单类型调用。 */
@Test
@SuppressWarnings("unchecked")
public void independentOnchainApiAuthenticatesActualPathAndIsolatesTypes() throws Exception {
Map<String, Object> 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<String, Object> data = onchainRequest("API-ONCHAIN");
data.remove("order_type");
String body = json.writeValueAsString(data);
Map<String, Object> quote = (Map<String, Object>) 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<String, Object> created = (Map<String, Object>) 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<String, Object> queried = (Map<String, Object>) 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端口。 */ /** Servlet代理保留原始字节,无需启动真实HTTP端口。 */
private javax.servlet.http.HttpServletRequest demoRequest(String operation, String body, String secret) { private javax.servlet.http.HttpServletRequest demoRequest(String operation, String body, String secret) {
return signedRequest("/api/rental/v1/demo/callback/" + operation, body, "RKdemo", secret, "WEBHOOK"); return signedRequest("/api/rental/v1/demo/callback/" + operation, body, "RKdemo", secret, "WEBHOOK");