From b5b631f20d88231458eb528a3b5b8b222e700803 Mon Sep 17 00:00:00 2001 From: liufumingren Date: Mon, 3 Aug 2026 01:08:36 +0800 Subject: [PATCH] =?UTF-8?q?fix(docs):=20warehouse=20=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E4=BD=9C=E4=B8=BA=E5=A4=96=E9=83=A8=20API=20=E9=9A=94=E7=A6=BB?= =?UTF-8?q?=EF=BC=8C=E4=B8=8D=E6=9A=B4=E9=9C=B2=E5=86=85=E9=83=A8=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=AF=BC=E8=88=AA=EF=BC=9B=E4=BF=AE=E6=AD=A3=E7=AD=BE?= =?UTF-8?q?=E5=90=8D=E7=AE=97=E6=B3=95=E6=8F=8F=E8=BF=B0=E4=B8=BA=20MD5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/controller/docs.js | 49 ++++++++++++++++++++++++++---------------- app/router.js | 3 +++ methods/warehouse.json | 2 +- 3 files changed, 35 insertions(+), 19 deletions(-) diff --git a/app/controller/docs.js b/app/controller/docs.js index 9996374..319c4b9 100644 --- a/app/controller/docs.js +++ b/app/controller/docs.js @@ -535,13 +535,15 @@ function renderMethodCard(item, entryPath, moduleName) { const description = item.description || ''; const isQimen = moduleName === 'qimen'; const isOpenapi = moduleName === 'openapi'; + const isWarehouse = moduleName === 'warehouse'; + const isExternalApi = isOpenapi || isWarehouse; const queryHint = isQimen ? 'app_key=xxx&method=...&v=2.0&format=json&sign_method=md5&sign=xxx×tamp=1700000000' - : isOpenapi + : isExternalApi ? `app_key=&method=${methodName}&v=1.0×tamp=1700000000` : `method=${methodName}&v=1.0×tamp=1700000000`; - const queryLabel = isOpenapi ? 'Query 参数(自动生成)' : 'Query 参数'; - const queryReadonlyAttr = isOpenapi ? ' readonly data-auto-generated="true" aria-label="自动生成"' : ''; + const queryLabel = isExternalApi ? 'Query 参数(自动生成)' : 'Query 参数'; + const queryReadonlyAttr = isExternalApi ? ' readonly data-auto-generated="true" aria-label="自动生成"' : ''; return `
@@ -614,7 +616,7 @@ function renderMethodCard(item, entryPath, moduleName) { - ${isOpenapi ? ` + ${isExternalApi ? ` ` : ''} @@ -646,12 +648,14 @@ function renderHtmlPage({ entryPath, }) { const isOpenapi = docData.module === 'openapi'; + const isWarehouse = docData.module === 'warehouse'; + const isExternalApi = isOpenapi || isWarehouse; const methodsCount = groups.reduce((sum, group) => sum + toArray(group.list).length, 0); const globalHeaders = toArray(docData.headers); const globalHeadersControls = renderGlobalHeadersControls(globalHeaders); const rawUrl = `/api/docs/${encodeURIComponent(docName)}/raw`; const changesUrl = `/api/docs/${encodeURIComponent(docName)}/changes`; - const navHtml = isOpenapi ? '' : docs.filter(name => name !== 'openapi').map(name => { + const navHtml = isExternalApi ? '' : docs.filter(name => name !== 'openapi' && name !== 'warehouse').map(name => { const activeClass = name === docName ? 'active' : ''; return `${escapeHtml(name)}`; }).join(''); @@ -1076,7 +1080,7 @@ function renderHtmlPage({ 查看变更记录 查看 JSON
- ${isOpenapi ? '' : `
+ ${isExternalApi ? '' : `

全局 Authorization

@@ -1087,7 +1091,7 @@ function renderHtmlPage({ ${globalHeadersControls}

来自 JSON 的 headers 定义;带 * 的字段为必填,支持下拉 list 选择。

`} - ${isOpenapi ? '' : `
+ ${isExternalApi ? '' : `

文档资源

${renderWindowElement('打开变更记录', changesUrl, 'doc-resource-link')} @@ -1097,9 +1101,9 @@ function renderHtmlPage({
点击上方按钮后,可直接预览当前文档的变更记录或原文 JSON。
`} - ${isOpenapi ? `
+ ${isExternalApi ? `

请求方式

-
POST /openapi?method={方法名}&v=1.0×tamp={时间戳}&app_key={app_key}&sign={签名}
+        
POST ${isOpenapi ? '/openapi' : '/warehouse'}?method={方法名}&v=1.0×tamp={时间戳}&app_key={app_key}&sign={签名}
 Content-Type: application/json
 
 {请求体 JSON}
@@ -1138,10 +1142,10 @@ Content-Type: application/json
  • 时间戳 timestamp 时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),超时返回 400
  • 签名结果为 32 位小写十六进制字符串
  • -

    + ${isOpenapi ? `

    → 回调测试工具 (模拟接收回调通知,验证回调链路) -

    +

    ` : ''}
    ` : ''}
    @@ -1167,9 +1171,10 @@ Content-Type: application/json (function() { var DOC_NAME = ${JSON.stringify(docName)}; var IS_OPENAPI_DOC = DOC_NAME === 'openapi'; + var IS_EXTERNAL_API_DOC = DOC_NAME === 'openapi' || DOC_NAME === 'warehouse'; var AUTH_KEY = 'wms_docs_global_auth'; var HEADER_STORE_KEY = 'wms_docs_global_headers_' + ${JSON.stringify(docName)}; - var OPENAPI_APP_KEY_STORE_KEY = 'wms_docs_openapi_app_key'; + var OPENAPI_APP_KEY_STORE_KEY = 'wms_docs_' + DOC_NAME + '_app_key'; var authInput = document.getElementById('globalAuth'); var clearBtn = document.getElementById('clearAuthBtn'); var searchInput = document.getElementById('methodSearch'); @@ -1547,7 +1552,7 @@ Content-Type: application/json return 'app_key=&method=' + encodeURIComponent(methodName) + '&v=2.0&format=json&sign_method=md5&sign=×tamp=' + nowTimestamp(); } - if (moduleName === 'openapi') { + if (moduleName === 'openapi' || moduleName === 'warehouse') { return buildOpenapiQuery(card, ''); } return 'method=' + encodeURIComponent(methodName) + '&v=1.0×tamp=' + nowTimestamp(); @@ -1573,7 +1578,7 @@ Content-Type: application/json var bodyInput = card.querySelector('.req-body'); var moduleName = card.getAttribute('data-module') || ''; if (queryInput) { - if (moduleName === 'openapi') { + if (moduleName === 'openapi' || moduleName === 'warehouse') { var appKeyInput = card.querySelector('.req-app-key'); var openapiAppKey = (appKeyInput && appKeyInput.value.trim()) || ''; queryInput.value = buildOpenapiQuery(card, openapiAppKey); @@ -1593,11 +1598,11 @@ Content-Type: application/json * @return {void} */ function refreshOpenapiQueryDisplays(appKey) { - if (!IS_OPENAPI_DOC) { + if (!IS_EXTERNAL_API_DOC) { return; } - var cards = document.querySelectorAll('.method-card[data-module="openapi"]'); + var cards = document.querySelectorAll('.method-card[data-module="openapi"], .method-card[data-module="warehouse"]'); cards.forEach(function(card) { var queryInput = card.querySelector('.req-query'); if (!queryInput) { @@ -1613,7 +1618,7 @@ Content-Type: application/json * @return {void} */ function initOpenapiAppKeyInputs() { - if (!IS_OPENAPI_DOC) { + if (!IS_EXTERNAL_API_DOC) { return; } @@ -1856,7 +1861,7 @@ Content-Type: application/json return; } - if (moduleName === 'openapi') { + if (moduleName === 'openapi' || moduleName === 'warehouse') { var appKeyInput = card.querySelector('.req-app-key'); var openapiAppKey = (appKeyInput && appKeyInput.value.trim()) || ''; query = buildOpenapiQuery(card, openapiAppKey); @@ -2040,6 +2045,14 @@ class DocsController extends Controller { await this.renderDoc('openapi'); } + /** + * 渲染仓库开放 API 文档独立页面。 + * @return {Promise} 无返回值。 + */ + async warehouse() { + await this.renderDoc('warehouse'); + } + async detail() { const { ctx } = this; const docName = ctx.params.docName; diff --git a/app/router.js b/app/router.js index fb4cd42..b437fe3 100644 --- a/app/router.js +++ b/app/router.js @@ -33,6 +33,9 @@ module.exports = app => { // OpenAPI 文档 — 所有环境均可访问,必须在通配路由之前注册 router.get('/docs/api/openapi', controller.docs.openapi); + // Warehouse 开放 API 文档 — 所有环境均可访问 + router.get('/docs/api/warehouse', controller.docs.warehouse); + // OpenAPI 回调测试 — 所有环境均可访问的独立调试页面 router.get('/docs/api/openapi/callback-test', controller.openapiCallback.testPage); diff --git a/methods/warehouse.json b/methods/warehouse.json index 4c24677..c344f36 100644 --- a/methods/warehouse.json +++ b/methods/warehouse.json @@ -1,6 +1,6 @@ { "module": "warehouse", - "description": "仓库开放 API 统一入口,供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 HMAC-SHA256 签名鉴权(interface_type_id=3)", + "description": "仓库开放 API 统一入口,供仓库级外部适配器(企微/钉钉/飞书/IM 等)调用,HTTP POST /warehouse,使用 MD5 签名鉴权(interface_type_id=3)", "version": "1.0.0", "updatedAt": "2026-08-01", "http": {