diff --git a/docs/rental-api-debugger.md b/docs/rental-api-debugger.md new file mode 100644 index 0000000..3335a61 --- /dev/null +++ b/docs/rental-api-debugger.md @@ -0,0 +1,27 @@ +# 管理员租赁接口调试台 + +## 安装与入口 + +先执行已有租赁菜单脚本,再执行 `sql/rent_api_debugger_menu.sql`。新菜单为“资源租赁 / 租赁API调试”,组件 `rental/apiDebugger`,权限 `rent:api:debug`,默认只授予admin角色;其他管理员需显式分配菜单。当前目录路径为rental时访问 `/rental/api-debugger`,已安装目录使用proxyRent时为 `/proxyRent/api-debugger`。刷新登录权限后显示菜单,不需要后端新增配置或存储凭证。 + +## 使用流程 + +1. 输入API基地址、租赁应用的API Key与API Secret。基地址默认取当前后台代理前缀,例如 `/prod-api`,最终调用 `/prod-api/api/rental/v1/packages`;直连API域名时填写 `https://租赁域名`,也支持包含实际代理前缀。 +2. 左侧选择7个商户接入接口之一:套餐、资源报价/下单/查询、地址上链报价/下单/查询。编辑器保留每个接口本次页面内的草稿,可格式化或恢复文档示例。 +3. 查询套餐后点击“使用此套餐报价”,填写真实资源接收地址,发送报价。 +4. 报价成功后点击“使用此报价准备下单”,自动沿用参数、报价原始金额字符串并生成商户单号。确认接收地址、网络、费用和回调地址,再发送下单请求。 +5. 下单成功后点击“查询此商户订单”跟踪状态。创建成功不代表履约成功;超时/停止等待不会取消服务端业务,请用原商户单号查询,不要贸然生成新单号重试。 + +## 调试信息 + +页面展示HTTP状态、业务原始响应、耗时、可见响应头、完整请求URL、JSON原文、请求体SHA256和脱敏签名原文。API Key与签名脱敏,Secret不展示、不写日志、不持久化。签名与发送共用同一原始UTF-8请求体,时间戳和nonce每次更新;反向代理前缀不参与签名。 + +页面使用独立浏览器请求,不携带后台Token或Cookie,不使用后端代发代理。签名依赖Web Crypto,需要HTTPS或localhost。跨域API必须允许当前后台来源、POST、Content-Type和X-Rent-*认证头;响应头受浏览器CORS可见范围限制。证书不可信、网络错误、跨域或重定向均需按实际部署修复,页面不会关闭证书校验。 + +初版仅调试当前服务已提供的7个用户接入接口,不提供不存在的余额、取消或退款API。回调地址通过下单JSON的notify_url填写;Webhook接收和验签示例参见 `/rental-api` 文档页面。 + +## 验证 + +已校验Vue模板与脚本解析;使用Node Web Crypto及独立HMAC计算交叉核对签名、JSON原文字节、代理前缀、地址上链子路径和随机nonce。未用真实凭证创建订单或冻结资金。 + +前端staging打包通过,保留项目已有3个API导出缺失告警及资源体积告警。本次无后端业务或数据库结构变更;菜单SQL尚未执行。 diff --git a/sql/rent_api_debugger_menu.sql b/sql/rent_api_debugger_menu.sql new file mode 100644 index 0000000..21b7568 --- /dev/null +++ b/sql/rent_api_debugger_menu.sql @@ -0,0 +1,12 @@ +-- 管理员租赁API调试台;幂等新增,不授予租赁业务角色,不存储API凭证。 +START TRANSACTION; +SET @debug_parent=COALESCE( + (SELECT parent_id FROM sys_menu WHERE perms='rent:portal:view' AND parent_id<>0 ORDER BY menu_id LIMIT 1), + (SELECT menu_id FROM sys_menu WHERE parent_id=0 AND path IN ('rental','proxyRent') ORDER BY menu_id LIMIT 1)); +INSERT INTO sys_menu(menu_name,parent_id,order_num,path,component,is_frame,is_cache,menu_type,visible,status,perms,icon,create_by,create_time) +SELECT '租赁API调试',@debug_parent,40,'api-debugger','rental/apiDebugger',1,1,'C','0','0','rent:api:debug','code','admin',NOW() +WHERE @debug_parent IS NOT NULL AND NOT EXISTS(SELECT 1 FROM sys_menu WHERE perms='rent:api:debug'); +INSERT INTO sys_role_menu(role_id,menu_id) +SELECT r.role_id,m.menu_id FROM sys_role r JOIN sys_menu m ON m.perms='rent:api:debug' +WHERE r.role_key='admin' AND NOT EXISTS(SELECT 1 FROM sys_role_menu x WHERE x.role_id=r.role_id AND x.menu_id=m.menu_id); +COMMIT;