fix(docs): warehouse 文档作为外部 API 隔离,不暴露内部文档导航;修正签名算法描述为 MD5

This commit is contained in:
liufumingren 2026-08-03 01:08:36 +08:00
parent da4208707d
commit b5b631f20d
3 changed files with 35 additions and 19 deletions

View File

@ -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&timestamp=1700000000'
: isOpenapi
: isExternalApi
? `app_key=&method=${methodName}&v=1.0&timestamp=1700000000`
: `method=${methodName}&v=1.0&timestamp=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 `<section class="method-card" id="${escapeHtml(methodName)}" data-method="${escapeHtml(methodName)}" data-desc="${escapeHtml(description)}" data-module="${escapeHtml(moduleName || '')}" data-endpoint="${escapeHtml(entryPath)}" data-login-required="${item.isNeedLogin ? 'true' : 'false'}">
<div class="method-header">
@ -614,7 +616,7 @@ function renderMethodCard(item, entryPath, moduleName) {
<label>${queryLabel}</label>
<input class="req-query" type="text" placeholder="${escapeHtml(queryHint)}"${queryReadonlyAttr} />
${isOpenapi ? `<label>app_key(仅 openapi 页面本地保存)</label>
${isExternalApi ? `<label>app_key(仅外部 API 页面本地保存)</label>
<input class="req-app-key" type="text" placeholder="请输入 app_key" autocomplete="off" />
<label>self_app_secret(仅本地签名计算,不会发送)</label>
<input class="req-self-app-secret" type="password" placeholder="请输入 self_app_secret" autocomplete="off" />` : ''}
@ -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 `<a class="tab ${activeClass}" href="/api/docs/${encodeURIComponent(name)}">${escapeHtml(name)}</a>`;
}).join('');
@ -1076,7 +1080,7 @@ function renderHtmlPage({
<a class="tab" href="${escapeHtml(changesUrl)}">查看变更记录</a>
<a class="tab" href="${escapeHtml(rawUrl)}">查看 JSON</a>
</div>
${isOpenapi ? '' : `<div class="global-auth">
${isExternalApi ? '' : `<div class="global-auth">
<h3>全局 Authorization</h3>
<div class="row">
<input id="globalAuth" type="text" placeholder="Bearer xxxxx" />
@ -1087,7 +1091,7 @@ function renderHtmlPage({
${globalHeadersControls}
<p class="muted">来自 JSON 的 headers 定义;带 * 的字段为必填,支持下拉 list 选择。</p>
</div>`}
${isOpenapi ? '' : `<div class="doc-tools">
${isExternalApi ? '' : `<div class="doc-tools">
<h3>文档资源</h3>
<div class="doc-tools-actions">
${renderWindowElement('打开变更记录', changesUrl, 'doc-resource-link')}
@ -1097,9 +1101,9 @@ function renderHtmlPage({
</div>
<pre id="docResourcePreview" class="req-result muted">点击上方按钮后,可直接预览当前文档的变更记录或原文 JSON。</pre>
</div>`}
${isOpenapi ? `<div class="openapi-guide">
${isExternalApi ? `<div class="openapi-guide">
<h3>请求方式</h3>
<pre class="guide-code">POST /openapi?method={方法名}&v=1.0&timestamp={时间戳}&app_key={app_key}&sign={签名}
<pre class="guide-code">POST ${isOpenapi ? '/openapi' : '/warehouse'}?method={方法名}&v=1.0&timestamp={时间戳}&app_key={app_key}&sign={签名}
Content-Type: application/json
{请求体 JSON}</pre>
@ -1138,10 +1142,10 @@ Content-Type: application/json
<li>时间戳 <strong>timestamp</strong> 时效校验:与服务器时间差不得超过 ±10 分钟(600 秒),超时返回 400</li>
<li>签名结果为 32 位小写十六进制字符串</li>
</ul>
<p style="margin-top:12px;font-size:13px;">
${isOpenapi ? `<p style="margin-top:12px;font-size:13px;">
<a href="/docs/api/openapi/callback-test" style="color:#1565c0;">→ 回调测试工具</a>
<span class="muted">(模拟接收回调通知,验证回调链路)</span>
</p>
</p>` : ''}
</div>` : ''}
</section>
@ -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=&timestamp=' + nowTimestamp();
}
if (moduleName === 'openapi') {
if (moduleName === 'openapi' || moduleName === 'warehouse') {
return buildOpenapiQuery(card, '');
}
return 'method=' + encodeURIComponent(methodName) + '&v=1.0&timestamp=' + 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<void>} 无返回值。
*/
async warehouse() {
await this.renderDoc('warehouse');
}
async detail() {
const { ctx } = this;
const docName = ctx.params.docName;

View File

@ -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);

View File

@ -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": {