WMS_MAIN/app/lib/jd_client.js
liufumingren 9af7dcf8fb feat(storeWarehouse): 签约关系接口配置按货主开放接口落库且回调地址统一取配置
- storeWarehouse.store.saveApiConfig:新增 resolveContractApiInterfaceType,
  interface_type_id=3(OPEN_API_WAREHOUSE 仓库开放接口)自动映射为 2(OPEN_API 货主开放接口)落库,
  不再要求当前主体为仓库(货主可维护自身签约关系下的接口配置)
- callback_url 不再取入参(含 callbackUrl 别名),统一写入 config.openapi.defaultCallbackUrl(新增配置项,默认空)
- storeWarehouse.store.listApiConfig:interface_type_id 过滤同步映射(传 3 按 2 查询)
- 文档:methods/system.json 升级 0.3.350、methods/changes/system.json 变更记录、docs/openapi-callback-events.md 回调地址来源说明
- 测试:saveApiConfig 新增 4 条用例(3→2 落库、忽略入参回调地址、默认值未配置、货主主体可保存、缺失类型 404),listApiConfig 新增 1 条过滤映射用例

同时提交工作区其余在制品改动:
- waybill:移除 wms_order_express_trace 模型并新增 drop 迁移,轨迹查询/取号/打印链路调整
- order:订单 SN 编码(order_item_sn / order_item_sn_log / sn_code_rule、has_sn_item 回填迁移),pendingOrder/recheckOrder/wave/base 调整
- express_platform、order_async、order_export、order_storage_allocation、storage.report、stock_store 配套修复
- lib:新增 jd_client,调整 qimen_client、callback_functions 及配套测试

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-14 17:14:04 +08:00

523 lines
18 KiB
JavaScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

'use strict';
const crypto = require('node:crypto');
const http = require('node:http');
const https = require('node:https');
/** 京东物流开放平台默认网关 */
const DEFAULT_BASE_URI = 'https://api.jdl.com';
/** 京东物流开放平台协议版本 */
const DEFAULT_VERSION = '2.0';
/** 默认签名算法(md5(content) 小写十六进制) */
const DEFAULT_ALGORITHM = 'md5-salt';
/** 单次请求默认超时时间(毫秒) */
const DEFAULT_TIMEOUT = 15000;
/** 标识调用方 HTTP 客户端(与京东示例一致,仅作统计用途) */
const DEFAULT_USER_AGENT = 'lop-http/nodejs';
/** HMac 系列算法名 → node:crypto 摘要名 */
const HMAC_ALGORITHMS = {
HMacMD5: 'md5',
HMacSHA1: 'sha1',
HMacSHA256: 'sha256',
HMacSHA512: 'sha512',
};
/** 只能在 request() 传入的请求级参数(init 里传会被忽略,因此显式报错) */
const REQUEST_ONLY_KEYS = [ 'path', 'method', 'body', 'query', 'headers', 'timestamp', 'now', 'raw' ];
/**
* 判断输入是否为普通对象。
* @param {*} value 任意输入值。
* @return {boolean} 是否为普通对象。
*/
function isPlainObject(value) {
return Object.prototype.toString.call(value) === '[object Object]';
}
/**
* 按京东开放平台规则生成签名。
* @param {string} algorithm 算法名:md5-salt / HMacMD5 / HMacSHA1 / HMacSHA256 / HMacSHA512。
* @param {string} data 待签名原文(见 buildSignContent)。
* @param {string} [secret] 密钥(仅 HMac 系列使用)。
* @return {string} 签名值:md5-salt 为小写十六进制,HMac 系列为 base64。
* @throws {Error} 算法不支持时抛出。
*/
function sign(algorithm, data, secret) {
const name = String(algorithm || DEFAULT_ALGORITHM);
const text = String(data === undefined || data === null ? '' : data);
if (name === 'md5-salt') {
return crypto.createHash('md5').update(text, 'utf8').digest('hex');
}
const hmacName = HMAC_ALGORITHMS[name];
if (!hmacName) {
throw new Error(`Algorithm ${name} not supported yet`);
}
return crypto.createHmac(hmacName, String(secret === undefined || secret === null ? '' : secret))
.update(text, 'utf8')
.digest('base64');
}
/**
* 格式化签名为 `YYYY-MM-DD HH:mm:ss`(服务器本地时区,与京东 PHP 示例 date() 口径一致)。
* @param {Date} [date] 时间对象,默认当前时间。
* @return {string} 格式化后的时间戳。
*/
function formatTimestamp(date = new Date()) {
const pad = num => String(num).padStart(2, '0');
return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} `
+ `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
}
/**
* 格式化当前时区相对 UTC 的小时数,用于 lop-tz 请求头(东八区为 '8')。
* @param {Date} [date] 时间对象,默认当前时间。
* @return {string} 时区小时数(如 '8'、'5.5'、'-5')。
*/
function formatTimezoneOffset(date = new Date()) {
return String(-date.getTimezoneOffset() / 60);
}
/**
* 拼接签名原文。
*
* 与京东 PHP 示例完全一致:
* `secret + 'access_token' + token + 'app_key' + key + 'method' + path +
* 'param_json' + body + 'timestamp' + ts + 'v' + version + secret`
*
* @param {Object} options 签名要素。
* @param {string} options.appSecret 应用密钥。
* @param {string} [options.accessToken] 访问令牌。
* @param {string} options.appKey 应用 AppKey。
* @param {string} options.method 接口路径(京东协议中 method 即 path)。
* @param {string} [options.paramJson] 业务报文原文。
* @param {string} options.timestamp 请求时间戳。
* @param {string} options.version 协议版本。
* @return {string} 签名原文。
*/
function buildSignContent({ appSecret, accessToken, appKey, method, paramJson, timestamp, version }) {
const toString = value => String(value === undefined || value === null ? '' : value);
return [
toString(appSecret),
'access_token', toString(accessToken),
'app_key', toString(appKey),
'method', toString(method),
'param_json', toString(paramJson),
'timestamp', toString(timestamp),
'v', toString(version),
toString(appSecret),
].join('');
}
/**
* 京东物流开放平台客户端(api.jdl.com)。
*
* 使用方式:
* ```js
* const jdClient = require('./jd_client');
* jdClient.init(appKey, appSecret, { accessToken });
* const res = await jdClient.request({
* path: '/jd/tracking/query',
* domain: 'Tracking_JD',
* body: [{ referenceNumber: 'JDAP20626092313', referenceType: '20000', phone: '7068' }],
* });
* ```
*/
class JdClient {
/**
* @param {Object} [options={}] 默认配置。
*/
constructor(options = {}) {
this.options = {
baseUri: DEFAULT_BASE_URI,
version: DEFAULT_VERSION,
algorithm: DEFAULT_ALGORITHM,
timeout: DEFAULT_TIMEOUT,
userAgent: DEFAULT_USER_AGENT,
appKey: '',
appSecret: '',
accessToken: '',
domain: '',
logger: null,
...options,
};
}
/**
* 初始化凭据与默认配置(可重复调用覆盖)。
*
* 只能传「请求之间不变」的配置;`path` / `body` / `method` / `query` / `headers` /
* `timestamp` 等请求级参数请传给 request(),误传到这里会直接报错。
*
* @param {string} appKey 应用 AppKey。
* @param {string} appSecret 应用 AppSecret。
* @param {Object} [options={}] 可选默认配置。
* @param {string} [options.accessToken] 访问令牌,也可后续用 setAccessToken 设置。
* @param {string} [options.domain] 接口域(LOP-DN),如 Tracking_JD。
* @param {string} [options.baseUri] 网关地址,默认 https://api.jdl.com。
* @param {string} [options.version] 协议版本,默认 2.0。
* @param {string} [options.algorithm] 签名算法,默认 md5-salt。
* @param {number} [options.timeout] 超时毫秒数,默认 15000。
* @param {string} [options.userAgent] UA,默认 lop-http/nodejs。
* @param {Object} [options.logger] 可选日志器(需实现 warn)。
* @return {JdClient} 当前实例(便于链式调用)。
* @throws {Error} options 里出现请求级参数时抛出。
*/
init(appKey, appSecret, options = {}) {
const safeOptions = isPlainObject(options) ? options : {};
const invalidKeys = Object.keys(safeOptions).filter(key => REQUEST_ONLY_KEYS.includes(key));
if (invalidKeys.length > 0) {
throw new Error(
`init 不支持请求级参数:${invalidKeys.join(', ')},请在 request() 中传入`
);
}
this.options = {
...this.options,
...safeOptions,
appKey: String(appKey || '').trim(),
appSecret: String(appSecret || '').trim(),
};
return this;
}
/**
* 更新访问令牌。
* @param {string} accessToken 访问令牌。
* @return {JdClient} 当前实例。
*/
setAccessToken(accessToken) {
this.options.accessToken = String(accessToken || '').trim();
return this;
}
/**
* 解析本次请求的凭据与配置(请求级参数优先于 init 默认值)。
* @param {Object} [options={}] 请求参数。
* @return {Object} 解析后的配置。
*/
resolveOptions(options = {}) {
const source = isPlainObject(options) ? options : {};
const pick = key => (source[key] === undefined || source[key] === null
? this.options[key]
: source[key]);
const appKey = String(pick('appKey') || '').trim();
const appSecret = String(pick('appSecret') || '').trim();
if (!appKey || !appSecret) {
throw new Error('京东开放平台 appKey / appSecret 未配置');
}
return {
appKey,
appSecret,
accessToken: String(pick('accessToken') || '').trim(),
domain: String(pick('domain') || '').trim(),
baseUri: String(pick('baseUri') || DEFAULT_BASE_URI).replace(/\/+$/, ''),
version: String(pick('version') || DEFAULT_VERSION),
algorithm: String(pick('algorithm') || DEFAULT_ALGORITHM),
timeout: Number(pick('timeout')) || DEFAULT_TIMEOUT,
userAgent: String(pick('userAgent') || DEFAULT_USER_AGENT),
logger: pick('logger') || null,
};
}
/**
* 序列化业务报文:字符串原样使用(签名与发送必须完全一致),其余按 JSON 序列化。
* @param {*} body 业务报文。
* @return {string} param_json 原文。
*/
normalizeParamJson(body) {
if (body === undefined || body === null) return '';
if (typeof body === 'string') return body;
return JSON.stringify(body);
}
/**
* 构建已签名的请求参数(不发请求,便于日志与单测)。
* @param {Object} [options={}] 请求参数。
* @param {string} options.path 接口路径(如 /jd/tracking/query),京东协议中同时作为签名 method。
* @param {string} [options.method='POST'] HTTP 方法。
* @param {*} [options.body] 业务报文(对象/数组/字符串),序列化后作为 param_json。
* @param {Object} [options.query={}] 额外查询参数(如京东要求的业务 query 参数)。
* @param {Object} [options.headers={}] 额外请求头。
* @param {string} [options.timestamp] 指定时间戳(默认当前本地时间),便于复现。
* @param {Date} [options.now] 指定当前时间对象(影响时间戳与 lop-tz)。
* @return {Object} { url, method, headers, body, paramJson, sign, timestamp, content, query }。
*/
buildRequestOptions(options = {}) {
const {
path: apiPath,
method = 'POST',
body,
query: extraQuery = {},
headers: extraHeaders = {},
timestamp,
now,
} = options;
const config = this.resolveOptions(options);
const path = String(apiPath || '').trim();
if (!path) {
throw new Error('京东接口 path 不能为空');
}
const httpMethod = String(method || 'POST').toUpperCase();
const paramJson = this.normalizeParamJson(body);
const nowDate = now instanceof Date ? now : new Date();
const requestTimestamp = timestamp ? String(timestamp) : formatTimestamp(nowDate);
const content = buildSignContent({
appSecret: config.appSecret,
accessToken: config.accessToken,
appKey: config.appKey,
method: path,
paramJson,
timestamp: requestTimestamp,
version: config.version,
});
const signValue = sign(config.algorithm, content, config.appSecret);
const queryPairs = [];
if (config.domain) queryPairs.push([ 'LOP-DN', config.domain ]);
queryPairs.push([ 'app_key', config.appKey ]);
queryPairs.push([ 'access_token', config.accessToken ]);
queryPairs.push([ 'timestamp', requestTimestamp ]);
queryPairs.push([ 'v', config.version ]);
queryPairs.push([ 'sign', signValue ]);
queryPairs.push([ 'algorithm', config.algorithm ]);
if (httpMethod === 'GET' && paramJson) {
queryPairs.push([ 'param_json', paramJson ]);
}
for (const [ key, value ] of Object.entries(isPlainObject(extraQuery) ? extraQuery : {})) {
if (value === undefined || value === null) continue;
queryPairs.push([ key, String(value) ]);
}
const search = new URLSearchParams();
for (const [ key, value ] of queryPairs) {
search.append(key, value);
}
const url = `${config.baseUri}${path}${search.toString() ? `?${search.toString()}` : ''}`;
const headers = {
'content-type': 'application/json;charset=utf-8',
'lop-tz': formatTimezoneOffset(nowDate),
'user-agent': config.userAgent,
...(isPlainObject(extraHeaders) ? extraHeaders : {}),
};
const requestBody = httpMethod === 'GET' ? null : paramJson;
if (requestBody !== null && headers['content-length'] === undefined) {
headers['content-length'] = String(Buffer.byteLength(requestBody, 'utf8'));
}
return {
url,
method: httpMethod,
headers,
body: requestBody,
paramJson,
sign: signValue,
timestamp: requestTimestamp,
content,
query: Object.fromEntries(queryPairs),
timeout: config.timeout,
};
}
/**
* 调用京东开放平台接口。
* @param {Object} [options={}] 请求参数,见 buildRequestOptions。
* @param {boolean} [options.raw=false] 为 true 时返回 { status, headers, text } 原始响应。
* @return {Promise<Object>} 默认返回 { success, status, headers, data, text, url }。
*/
async request(options = {}) {
const prepared = this.buildRequestOptions(options);
const response = await this.send(prepared);
const text = response.text;
let data = null;
try {
data = text ? JSON.parse(text) : null;
} catch (_e) {
data = text;
}
const result = {
success: response.status >= 200 && response.status < 300,
status: response.status,
headers: response.headers,
data,
text,
url: prepared.url,
};
if (options && options.raw === true) {
return { status: response.status, headers: response.headers, text, url: prepared.url };
}
return result;
}
/**
* 发送 HTTP 请求(内置 http/https,不依赖第三方请求库)。
* @param {Object} prepared buildRequestOptions 的返回值。
* @return {Promise<{status: number, headers: Object, text: string}>} 响应。
*/
send(prepared) {
return new Promise((resolve, reject) => {
const target = new URL(prepared.url);
const transport = target.protocol === 'http:' ? http : https;
const req = transport.request({
protocol: target.protocol,
hostname: target.hostname,
port: target.port || (target.protocol === 'http:' ? 80 : 443),
path: `${target.pathname}${target.search}`,
method: prepared.method,
headers: prepared.headers,
timeout: prepared.timeout,
}, res => {
const chunks = [];
res.on('data', chunk => chunks.push(chunk));
res.on('end', () => {
resolve({
status: Number(res.statusCode) || 0,
headers: res.headers,
text: Buffer.concat(chunks).toString('utf8'),
});
});
res.on('error', reject);
});
req.on('timeout', () => {
req.destroy(new Error(`京东接口请求超时(${prepared.timeout}ms)`));
});
req.on('error', reject);
if (prepared.body !== null && prepared.body !== undefined) {
req.write(prepared.body);
}
req.end();
});
}
/**
* 驱动式调用:兼容 `execute({ url, body })` 写法(与其它快递驱动保持一致)。
*
* - `url` 可传完整地址(自动拆成 baseUri + path + query),也可只传 path;
* - `body` 为对象/数组时自动 JSON.stringify,字符串原样使用(签名与发送同一份);
* - 返回类 fetch 响应对象,支持 `await res.text()` / `await res.json()`。
*
* @param {Object} [request={}] 请求参数。
* @param {string} request.url 接口地址(完整 URL 或 path)。
* @param {*} [request.body] 业务报文。
* @param {string} [request.method='POST'] HTTP 方法。
* @param {Object} [request.query] 额外 query 参数。
* @param {Object} [request.headers] 额外请求头。
* @param {string} [request.domain] 接口域(LOP-DN)。
* @param {string} [request.accessToken] 覆盖默认 access_token。
* @return {Promise<Object>} { ok, status, statusText, headers, url, data, text(), json() }。
*/
async execute(request = {}) {
const safeRequest = isPlainObject(request) ? request : {};
const targetUrl = String(safeRequest.url || '').trim();
if (!targetUrl) {
throw new Error('京东接口 url 不能为空');
}
const isAbsolute = /^https?:\/\//i.test(targetUrl);
const parsed = isAbsolute ? new URL(targetUrl) : null;
const urlQuery = {};
if (parsed) {
for (const [ key, value ] of parsed.searchParams.entries()) {
urlQuery[key] = value;
}
}
const result = await this.request({
...safeRequest,
baseUri: parsed ? `${parsed.protocol}//${parsed.host}` : safeRequest.baseUri,
path: parsed ? parsed.pathname : targetUrl,
query: { ...urlQuery, ...(isPlainObject(safeRequest.query) ? safeRequest.query : {}) },
});
const text = result.text === undefined || result.text === null ? '' : String(result.text);
return {
ok: result.success,
status: result.status,
statusText: result.success ? 'OK' : 'ERROR',
headers: result.headers || {},
url: result.url,
data: result.data,
text: async () => text,
json: async () => {
if (text) return JSON.parse(text);
return null;
},
};
}
}
const defaultClient = new JdClient();
module.exports = {
JdClient,
buildSignContent,
formatTimestamp,
formatTimezoneOffset,
sign,
/**
* 初始化默认客户端。
* @param {string} appKey 应用 AppKey。
* @param {string} appSecret 应用 AppSecret。
* @param {Object} [options={}] 默认配置。
* @return {JdClient} 默认客户端实例。
*/
init(appKey, appSecret, options) {
return defaultClient.init(appKey, appSecret, options);
},
/**
* 更新默认客户端的访问令牌。
* @param {string} accessToken 访问令牌。
* @return {JdClient} 默认客户端实例。
*/
setAccessToken(accessToken) {
return defaultClient.setAccessToken(accessToken);
},
/**
* 用默认客户端构建签名请求参数。
* @param {Object} [options={}] 请求参数。
* @return {Object} 已签名请求参数。
*/
buildRequestOptions(options) {
return defaultClient.buildRequestOptions(options);
},
/**
* 用默认客户端调用接口。
* @param {Object} [options={}] 请求参数。
* @return {Promise<Object>} 响应。
*/
request(options) {
return defaultClient.request(options);
},
/**
* 用默认客户端做驱动式调用(兼容 execute({ url, body }))。
* @param {Object} [request={}] 请求参数。
* @return {Promise<Object>} 类 fetch 响应(支持 text() / json())。
*/
execute(request) {
return defaultClient.execute(request);
},
/**
* 默认客户端实例。
* @return {JdClient} 实例。
*/
get client() {
return defaultClient;
},
};