- 新增 wms_order_express_trace(1 运单 : N 轨迹):express_id 关联主表,
冗余 waybill_code / order_id,warehouse_id 隔离,raw_data 存原始报文;
uk_express_op_scan(express_id, op_time, scan_type) 幂等;字符集与主表一致
- 新增出站回调 waybill.getTrace(注册到 callback_functions,管理端可勾选):
入参与 waybill.getreceive 一致({ request: { waybill_codes: [...] } },单批 10 单,
signMode=simple);响应 [{ waybillNo, trace: {...} }],兼容 trace 数组与 {code,data} 包装
- 新增 waybill.warehouse.updateTrace / updateTraceTaskProgress:
复用导出任务的异步任务ID与进度模式(前缀 waybill_trace_),
支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选(上限 5000);
轨迹按 (express_id, op_time, scan_type) upsert,未匹配运单计入 not_found
- 文档:methods/system.json(0.3.325)、变更记录、设计文档 2.2.1/3.9、出站回调说明 3.7
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
851 lines
29 KiB
JavaScript
851 lines
29 KiB
JavaScript
'use strict';
|
||
|
||
const MainService = require('../../main');
|
||
|
||
const WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX = 'waybill_export_task_';
|
||
const WAYBILL_RECEIVE_TASK_CACHE_KEY_PREFIX = 'waybill_receive_task_';
|
||
const WAYBILL_TRACE_TASK_CACHE_KEY_PREFIX = 'waybill_trace_task_';
|
||
/** 物流轨迹查询所依赖的出站回调 method */
|
||
const WAYBILL_TRACE_EVENT = 'waybill.getTrace';
|
||
/** 仓库未配置轨迹查询外部接口时的失败提示(直接失败,不进入任务流程) */
|
||
const WAYBILL_TRACE_NOT_CONFIGURED_MESSAGE =
|
||
'如需更新运单物流轨迹信息,到【设置】->【基础设置】->【API开放接口】配置相应的外部访问接口';
|
||
/** 揽收状态查询所依赖的出站回调 method */
|
||
const WAYBILL_RECEIVE_EVENT = 'waybill.getreceive';
|
||
/** 仓库未配置外部接口时的失败提示(直接失败,不进入任务流程) */
|
||
const WAYBILL_RECEIVE_NOT_CONFIGURED_MESSAGE =
|
||
'如需更新运单是否揽收信息,到【设置】->【基础设置】->【API开放接口】配置相应的外部访问接口';
|
||
|
||
/** 按 where 筛选解析运单号时允许的最大条数(超出要求缩小范围) */
|
||
const WAYBILL_RECEIVE_MAX_CODES = 5000;
|
||
|
||
/**
|
||
* 运单号仓库侧入口层。
|
||
* 负责鉴权声明、参数校验,委托 systems/waybill.js 执行业务逻辑。
|
||
*
|
||
* 所有方法均需登录但无需细粒度鉴权(与订单列表保持一致)。
|
||
*/
|
||
class WaybillWarehouseService extends MainService {
|
||
constructor(ctx) {
|
||
super(ctx);
|
||
const _noNeedLogin = '';
|
||
const _noNeedRight = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress,updateTrace,updateTraceTaskProgress';
|
||
const _noNeedLog = '';
|
||
const _noNeedAuth = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress,updateTrace,updateTraceTaskProgress';
|
||
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
|
||
}
|
||
|
||
/**
|
||
* 运单列表查询(仓库侧)。
|
||
* 支持分页、多条件筛选、排序。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {Object} [data.where] 筛选条件。
|
||
* @param {Object} [data.pagination] 分页参数 { page, pageSize }。
|
||
* @param {Object} [data.sort] 排序参数 { field, order }。
|
||
* @return {Promise<Object>} 运单列表与分页信息。
|
||
*/
|
||
async list(data) {
|
||
try {
|
||
const { where, pagination, sort } = data || {};
|
||
const result = await this.service.systems.waybill.list({
|
||
where: where || {},
|
||
pagination: pagination || {},
|
||
sort: sort || {},
|
||
});
|
||
return this.success('获取成功', result);
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 运单详情查询(仓库侧)。
|
||
* 支持按运单ID或运单号查询。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {number} [data.id] 运单记录ID。
|
||
* @param {string} [data.waybillCode] 运单号(与 id 二选一,waybillCode 优先)。
|
||
* @return {Promise<Object>} 运单详情(含订单/打印/打包信息)。
|
||
*/
|
||
async detail(data) {
|
||
try {
|
||
const { id, waybillCode } = data || {};
|
||
if (!id && !waybillCode) {
|
||
return this.fail('运单ID或运单号不能为空');
|
||
}
|
||
const result = await this.service.systems.waybill.detail({
|
||
id,
|
||
waybillCode,
|
||
});
|
||
return this.success('获取成功', result);
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 运单导出(仓库侧)。异步任务模式,提交后通过 exportTaskProgress 查询进度。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {Object} [data.where] 筛选条件(同 list)。
|
||
* @param {Object} [data.sort] 排序参数(同 list)。
|
||
* @param {string[]} [data.exportFields] 需要导出的字段列表。
|
||
* @return {Promise<Object>} 任务提交结果,含 task_id。
|
||
*/
|
||
async export(data) {
|
||
try {
|
||
const { where, sort, exportFields } = data || {};
|
||
const taskId = this.generateExportTaskId();
|
||
|
||
const taskPayload = {
|
||
task_id: taskId,
|
||
status: 'submitted',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: 0,
|
||
message: '导出任务已提交',
|
||
result: null,
|
||
error: '',
|
||
};
|
||
await this.setExportTaskProgress(taskId, taskPayload);
|
||
|
||
setImmediate(async () => {
|
||
try {
|
||
await this.setExportTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'running',
|
||
progress: 5,
|
||
current_count: 0,
|
||
total_count: 0,
|
||
message: '导出任务执行中',
|
||
result: null,
|
||
error: '',
|
||
});
|
||
|
||
const result = await this.service.systems.waybill.export({
|
||
where: where || {},
|
||
sort: sort || {},
|
||
exportFields,
|
||
onProgress: async progress => {
|
||
const safeProgress = this.isPlainObject(progress) ? progress : {};
|
||
await this.setExportTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: safeProgress.status || 'running',
|
||
progress: safeProgress.progress || 0,
|
||
current_count: safeProgress.currentCount || safeProgress.current_count || 0,
|
||
total_count: safeProgress.totalCount || safeProgress.total_count || 0,
|
||
message: safeProgress.message || '导出任务执行中',
|
||
result: safeProgress.result || null,
|
||
error: '',
|
||
});
|
||
},
|
||
});
|
||
|
||
await this.setExportTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'success',
|
||
progress: 100,
|
||
current_count: result.current_count || 0,
|
||
total_count: result.total_count || 0,
|
||
message: '导出任务完成',
|
||
result,
|
||
error: '',
|
||
});
|
||
} catch (error) {
|
||
const errorMessage = error && error.message ? error.message : `${error}`;
|
||
await this.setExportTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'failed',
|
||
progress: 100,
|
||
message: '导出任务失败',
|
||
result: null,
|
||
error: errorMessage,
|
||
});
|
||
}
|
||
});
|
||
|
||
return this.success('ok', {
|
||
...taskPayload,
|
||
update_time: Date.now(),
|
||
});
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 查询运单导出任务进度。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {string} [data.task_id] 任务ID(下划线写法)。
|
||
* @param {string} [data.taskId] 任务ID(驼峰写法)。
|
||
* @return {Promise<Object>} 任务进度信息。
|
||
*/
|
||
async exportTaskProgress(data = {}) {
|
||
try {
|
||
const taskId = this.normalizeExportTaskId(data);
|
||
if (!taskId) {
|
||
return this.success('ok', {
|
||
task_id: '',
|
||
status: 'not_found',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: 0,
|
||
message: '任务不存在',
|
||
result: null,
|
||
error: '',
|
||
download_url: '',
|
||
update_time: Date.now(),
|
||
});
|
||
}
|
||
|
||
const cachedTask = await this.getExportTaskProgress(taskId);
|
||
if (!cachedTask) {
|
||
return this.success('ok', {
|
||
task_id: taskId,
|
||
status: 'not_found',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: 0,
|
||
message: '任务不存在',
|
||
result: null,
|
||
error: '',
|
||
download_url: '',
|
||
update_time: Date.now(),
|
||
});
|
||
}
|
||
|
||
const safeResult = this.isPlainObject(cachedTask.result) ? cachedTask.result : {};
|
||
const downloadUrl = String(
|
||
safeResult.url
|
||
|| safeResult.cndUrl
|
||
|| safeResult.cdnUrl
|
||
|| safeResult.cosUrl
|
||
|| safeResult.fileKey
|
||
|| ''
|
||
);
|
||
|
||
return this.success('ok', {
|
||
task_id: taskId,
|
||
...cachedTask,
|
||
download_url: downloadUrl,
|
||
});
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 批量更新运单是否揽收(仓库侧)。
|
||
*
|
||
* 链路走 OpenAPI 出站回调 `waybill.getreceive`(单批最多 10 单,自动切批),
|
||
* 不读取本地库的揽收标记;返回结果按 waybill_code + warehouse_id 回写
|
||
* `wms_order_express.is_galaxy_receive`。
|
||
* 异步任务模式:提交后通过 `updateReceiveTaskProgress` 查询进度。
|
||
* 仓库未配置承接该 method 的 API 应用时直接失败(不创建任务)。
|
||
*
|
||
* 入参二选一:
|
||
* - `waybillCodes`:显式运单号列表(优先);
|
||
* - `where`:与 `waybill.warehouse.list` 完全一致的筛选条件(不含分页/排序),
|
||
* 服务端先按条件解析运单号再走同一任务链路。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {string[]} [data.waybillCodes] 运单号列表(兼容 waybill_codes)。
|
||
* @param {Object} [data.where] 筛选条件(同 waybill.warehouse.list 的 where)。
|
||
* @return {Promise<Object>} 任务提交结果,含 task_id。
|
||
*/
|
||
async updateReceive(data = {}) {
|
||
try {
|
||
const safeData = this.isPlainObject(data) ? data : {};
|
||
let waybillCodes = this.normalizeReceiveWaybillCodes(safeData.waybillCodes || safeData.waybill_codes);
|
||
const rawWhere = this.isPlainObject(safeData.where) ? safeData.where : null;
|
||
|
||
if (waybillCodes.length === 0 && !rawWhere) {
|
||
return this.fail('运单号不能为空,或传入 where 筛选条件');
|
||
}
|
||
|
||
const warehouseId = Number(this.ctx?.user?.store_id || 0);
|
||
if (!warehouseId) {
|
||
return this.fail('无法获取当前仓库ID');
|
||
}
|
||
|
||
// 未配置外部访问接口:直接失败,不进入任务流程
|
||
const appKey = await this.resolveReceiveAppKey(warehouseId);
|
||
if (!appKey) {
|
||
return this.fail(WAYBILL_RECEIVE_NOT_CONFIGURED_MESSAGE);
|
||
}
|
||
|
||
// 仅传 where 时:按与列表一致的筛选口径解析运单号(带数量上限,避免一次任务过大)
|
||
if (waybillCodes.length === 0) {
|
||
const resolved = await this.service.systems.waybill.resolveWaybillCodesByWhere({
|
||
where: rawWhere,
|
||
warehouseId,
|
||
limit: WAYBILL_RECEIVE_MAX_CODES,
|
||
});
|
||
if (resolved.exceeded) {
|
||
return this.fail(
|
||
`符合条件的运单超过 ${WAYBILL_RECEIVE_MAX_CODES} 条,请缩小筛选范围或直接传 waybillCodes`
|
||
);
|
||
}
|
||
waybillCodes = this.normalizeReceiveWaybillCodes(resolved.codes);
|
||
if (waybillCodes.length === 0) {
|
||
return this.fail('未匹配到符合条件的运单');
|
||
}
|
||
}
|
||
|
||
const taskId = this.generateReceiveTaskId();
|
||
const taskPayload = {
|
||
task_id: taskId,
|
||
status: 'submitted',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: waybillCodes.length,
|
||
message: '更新揽收状态任务已提交',
|
||
result: null,
|
||
error: '',
|
||
};
|
||
await this.setReceiveTaskProgress(taskId, taskPayload);
|
||
|
||
setImmediate(async () => {
|
||
try {
|
||
await this.setReceiveTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'running',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: waybillCodes.length,
|
||
message: '正在查询运单揽收状态',
|
||
result: null,
|
||
error: '',
|
||
});
|
||
|
||
const result = await this.service.systems.waybill.queryReceiveStatus({
|
||
warehouseId,
|
||
waybillCodes,
|
||
appKey,
|
||
onProgress: async progress => {
|
||
const safeProgress = this.isPlainObject(progress) ? progress : {};
|
||
await this.setReceiveTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'running',
|
||
progress: safeProgress.progress || 0,
|
||
current_count: safeProgress.currentCount || 0,
|
||
total_count: safeProgress.totalCount || waybillCodes.length,
|
||
message: safeProgress.message || '正在查询运单揽收状态',
|
||
result: null,
|
||
error: '',
|
||
});
|
||
},
|
||
});
|
||
|
||
if (!result || result.success !== true) {
|
||
await this.setReceiveTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'failed',
|
||
progress: 100,
|
||
current_count: 0,
|
||
total_count: waybillCodes.length,
|
||
message: '更新揽收状态失败',
|
||
result: null,
|
||
error: String(result && result.reason || '运单揽收状态查询失败'),
|
||
});
|
||
return;
|
||
}
|
||
|
||
const failedList = Array.isArray(result.failed) ? result.failed : [];
|
||
await this.setReceiveTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'success',
|
||
progress: 100,
|
||
current_count: waybillCodes.length,
|
||
total_count: waybillCodes.length,
|
||
message: `更新完成:更新 ${result.updated} 单,未变化 ${result.unchanged} 单,失败 ${failedList.length} 单`,
|
||
result: {
|
||
total: result.total,
|
||
updated: result.updated,
|
||
unchanged: result.unchanged,
|
||
not_found: Array.isArray(result.not_found) ? result.not_found : [],
|
||
failed: failedList,
|
||
},
|
||
error: '',
|
||
});
|
||
} catch (error) {
|
||
const errorMessage = error && error.message ? error.message : `${error}`;
|
||
await this.setReceiveTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'failed',
|
||
progress: 100,
|
||
message: '更新揽收状态失败',
|
||
result: null,
|
||
error: errorMessage,
|
||
});
|
||
}
|
||
});
|
||
|
||
return this.success('ok', {
|
||
...taskPayload,
|
||
update_time: Date.now(),
|
||
});
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 查询运单揽收状态更新任务进度。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {string} [data.task_id] 任务ID(下划线写法)。
|
||
* @param {string} [data.taskId] 任务ID(驼峰写法)。
|
||
* @return {Promise<Object>} 任务进度信息。
|
||
*/
|
||
async updateReceiveTaskProgress(data = {}) {
|
||
try {
|
||
const safeData = this.isPlainObject(data) ? data : {};
|
||
const taskId = String(safeData.task_id || safeData.taskId || '').trim();
|
||
const notFoundPayload = {
|
||
task_id: taskId,
|
||
status: 'not_found',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: 0,
|
||
message: '任务不存在',
|
||
result: null,
|
||
error: '',
|
||
update_time: Date.now(),
|
||
};
|
||
|
||
if (!taskId) {
|
||
return this.success('ok', notFoundPayload);
|
||
}
|
||
|
||
const cachedTask = await this.getReceiveTaskProgress(taskId);
|
||
if (!cachedTask) {
|
||
return this.success('ok', notFoundPayload);
|
||
}
|
||
|
||
return this.success('ok', {
|
||
task_id: taskId,
|
||
...cachedTask,
|
||
update_time: Date.now(),
|
||
});
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
// ==================== 任务辅助方法 ====================
|
||
|
||
/**
|
||
* 生成运单导出任务ID。
|
||
* @return {string} 任务ID。
|
||
*/
|
||
generateExportTaskId() {
|
||
const warehouseId = this.ctx?.user?.store_id || 'unknown';
|
||
const timestamp = Date.now();
|
||
const randomToken = Math.random().toString(36).slice(2, 10);
|
||
return `waybill_export_${warehouseId}_${timestamp}_${randomToken}`;
|
||
}
|
||
|
||
/**
|
||
* 生成运单揽收状态更新任务ID。
|
||
* @return {string} 任务ID。
|
||
*/
|
||
generateReceiveTaskId() {
|
||
const warehouseId = this.ctx?.user?.store_id || 'unknown';
|
||
const timestamp = Date.now();
|
||
const randomToken = Math.random().toString(36).slice(2, 10);
|
||
return `waybill_receive_${warehouseId}_${timestamp}_${randomToken}`;
|
||
}
|
||
|
||
/**
|
||
* 规范化运单号:转字符串、去空格、去空、去重。
|
||
* @param {Array<string>} waybillCodes 原始运单号列表。
|
||
* @return {Array<string>} 规范化后的运单号列表。
|
||
*/
|
||
normalizeReceiveWaybillCodes(waybillCodes) {
|
||
if (!Array.isArray(waybillCodes)) return [];
|
||
return [ ...new Set(waybillCodes.map(code => String(code || '').trim()).filter(Boolean)) ];
|
||
}
|
||
|
||
/**
|
||
* 解析仓库承接 waybill.getreceive 的 API 应用 AppKey(按 id 升序取首个)。
|
||
* 返回空字符串表示仓库未配置该外部访问接口。
|
||
* @param {number} warehouseId 仓库ID。
|
||
* @return {Promise<string>} 目标应用 AppKey。
|
||
*/
|
||
async resolveReceiveAppKey(warehouseId) {
|
||
const warehouseNotify = this.service.systems && this.service.systems.warehouseNotify;
|
||
if (!warehouseNotify || typeof warehouseNotify.listCallbackConfigs !== 'function') {
|
||
return '';
|
||
}
|
||
|
||
const candidates = await warehouseNotify.listCallbackConfigs(
|
||
Number(warehouseId) || 0,
|
||
WAYBILL_RECEIVE_EVENT
|
||
);
|
||
const first = Array.isArray(candidates) ? candidates[0] : null;
|
||
return String(first && first.appKey || '').trim();
|
||
}
|
||
|
||
/**
|
||
* 规范导出任务ID。
|
||
* @param {Object} data 请求体。
|
||
* @return {string} 规范后的任务ID。
|
||
*/
|
||
normalizeExportTaskId(data = {}) {
|
||
const normalizedData = this.isPlainObject(data) ? data : {};
|
||
return String(normalizedData.task_id || normalizedData.taskId || '').trim();
|
||
}
|
||
|
||
/**
|
||
* 获取运单任务缓存键。
|
||
* @param {string} taskId 任务ID。
|
||
* @param {string} [prefix] 缓存键前缀,区分导出/揽收状态更新等任务类型。
|
||
* @return {string} 缓存键。
|
||
*/
|
||
getTaskCacheKey(taskId = '', prefix = WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX) {
|
||
const normalizedTaskId = String(taskId || '').trim();
|
||
if (!normalizedTaskId) {
|
||
return '';
|
||
}
|
||
return `${prefix}${normalizedTaskId}`;
|
||
}
|
||
|
||
/**
|
||
* 写入运单任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @param {Object} payload 任务状态。
|
||
* @param {string} [prefix] 缓存键前缀。
|
||
* @return {Promise<void>} 无返回值。
|
||
*/
|
||
async setTaskProgress(taskId = '', payload = {}, prefix = WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX) {
|
||
const cacheKey = this.getTaskCacheKey(taskId, prefix);
|
||
if (!cacheKey || typeof this.app.setCacheAsync !== 'function') {
|
||
return;
|
||
}
|
||
|
||
const safePayload = this.isPlainObject(payload) ? payload : {};
|
||
const normalizeCount = value => {
|
||
const numericValue = Number(value);
|
||
return Number.isFinite(numericValue) && numericValue >= 0 ? Math.round(numericValue) : 0;
|
||
};
|
||
const progressPayload = {
|
||
task_id: String(taskId || '').trim(),
|
||
status: String(safePayload.status || 'submitted').trim() || 'submitted',
|
||
progress: Number.isFinite(Number(safePayload.progress))
|
||
? Math.min(100, Math.max(0, Math.round(Number(safePayload.progress))))
|
||
: 0,
|
||
current_count: normalizeCount(safePayload.current_count),
|
||
total_count: normalizeCount(safePayload.total_count),
|
||
message: String(safePayload.message || ''),
|
||
result: safePayload.result ?? null,
|
||
error: String(safePayload.error || ''),
|
||
};
|
||
|
||
await this.app.setCacheAsync(cacheKey, progressPayload);
|
||
}
|
||
|
||
/**
|
||
* 读取运单任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @param {string} [prefix] 缓存键前缀。
|
||
* @return {Promise<Object|null>} 任务状态对象或 null。
|
||
*/
|
||
async getTaskProgress(taskId = '', prefix = WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX) {
|
||
const cacheKey = this.getTaskCacheKey(taskId, prefix);
|
||
if (!cacheKey || typeof this.app.getCacheAsync !== 'function') {
|
||
return null;
|
||
}
|
||
return await this.app.getCacheAsync(cacheKey);
|
||
}
|
||
|
||
/**
|
||
* 写入运单导出任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @param {Object} payload 任务状态。
|
||
* @return {Promise<void>} 无返回值。
|
||
*/
|
||
async setExportTaskProgress(taskId = '', payload = {}) {
|
||
await this.setTaskProgress(taskId, payload, WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX);
|
||
}
|
||
|
||
/**
|
||
* 读取运单导出任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @return {Promise<Object|null>} 任务状态对象或 null。
|
||
*/
|
||
async getExportTaskProgress(taskId = '') {
|
||
return await this.getTaskProgress(taskId, WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX);
|
||
}
|
||
|
||
/**
|
||
* 写入运单揽收状态更新任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @param {Object} payload 任务状态。
|
||
* @return {Promise<void>} 无返回值。
|
||
*/
|
||
async setReceiveTaskProgress(taskId = '', payload = {}) {
|
||
await this.setTaskProgress(taskId, payload, WAYBILL_RECEIVE_TASK_CACHE_KEY_PREFIX);
|
||
}
|
||
|
||
/**
|
||
* 读取运单揽收状态更新任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @return {Promise<Object|null>} 任务状态对象或 null。
|
||
*/
|
||
async getReceiveTaskProgress(taskId = '') {
|
||
return await this.getTaskProgress(taskId, WAYBILL_RECEIVE_TASK_CACHE_KEY_PREFIX);
|
||
}
|
||
|
||
/**
|
||
* 批量更新运单物流轨迹(仓库侧)。
|
||
*
|
||
* 链路走 OpenAPI 出站回调 `waybill.getTrace`(单批最多 10 单,自动切批),
|
||
* 请求与 `waybill.getreceive` 一致(`{ request: { waybill_codes: [...] } }`),
|
||
* 查询结果按 (express_id, op_time, scan_type) 幂等落库到 `wms_order_express_trace`。
|
||
* 异步任务模式:提交后通过 `updateTraceTaskProgress` 查询进度。
|
||
* 仓库未配置承接该 method 的 API 应用时直接失败(不创建任务)。
|
||
*
|
||
* 入参二选一:
|
||
* - `waybillCodes`:显式运单号列表(优先);
|
||
* - `where`:与 `waybill.warehouse.list` 完全一致的筛选条件(不含分页/排序)。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {string[]} [data.waybillCodes] 运单号列表(兼容 waybill_codes)。
|
||
* @param {Object} [data.where] 筛选条件(同 waybill.warehouse.list 的 where)。
|
||
* @return {Promise<Object>} 任务提交结果,含 task_id。
|
||
*/
|
||
async updateTrace(data = {}) {
|
||
try {
|
||
const safeData = this.isPlainObject(data) ? data : {};
|
||
let waybillCodes = this.normalizeReceiveWaybillCodes(safeData.waybillCodes || safeData.waybill_codes);
|
||
const rawWhere = this.isPlainObject(safeData.where) ? safeData.where : null;
|
||
|
||
if (waybillCodes.length === 0 && !rawWhere) {
|
||
return this.fail('运单号不能为空,或传入 where 筛选条件');
|
||
}
|
||
|
||
const warehouseId = Number(this.ctx?.user?.store_id || 0);
|
||
if (!warehouseId) {
|
||
return this.fail('无法获取当前仓库ID');
|
||
}
|
||
|
||
// 未配置外部访问接口:直接失败,不进入任务流程
|
||
const appKey = await this.resolveTraceAppKey(warehouseId);
|
||
if (!appKey) {
|
||
return this.fail(WAYBILL_TRACE_NOT_CONFIGURED_MESSAGE);
|
||
}
|
||
|
||
if (waybillCodes.length === 0) {
|
||
const resolved = await this.service.systems.waybill.resolveWaybillCodesByWhere({
|
||
where: rawWhere,
|
||
warehouseId,
|
||
limit: WAYBILL_RECEIVE_MAX_CODES,
|
||
});
|
||
if (resolved.exceeded) {
|
||
return this.fail(
|
||
`符合条件的运单超过 ${WAYBILL_RECEIVE_MAX_CODES} 条,请缩小筛选范围或直接传 waybillCodes`
|
||
);
|
||
}
|
||
waybillCodes = this.normalizeReceiveWaybillCodes(resolved.codes);
|
||
if (waybillCodes.length === 0) {
|
||
return this.fail('未匹配到符合条件的运单');
|
||
}
|
||
}
|
||
|
||
const taskId = this.generateTraceTaskId();
|
||
const taskPayload = {
|
||
task_id: taskId,
|
||
status: 'submitted',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: waybillCodes.length,
|
||
message: '更新物流轨迹任务已提交',
|
||
result: null,
|
||
error: '',
|
||
};
|
||
await this.setTraceTaskProgress(taskId, taskPayload);
|
||
|
||
setImmediate(async () => {
|
||
try {
|
||
await this.setTraceTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'running',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: waybillCodes.length,
|
||
message: '正在查询运单物流轨迹',
|
||
result: null,
|
||
error: '',
|
||
});
|
||
|
||
const result = await this.service.systems.waybill.queryTraces({
|
||
warehouseId,
|
||
waybillCodes,
|
||
appKey,
|
||
onProgress: async progress => {
|
||
const safeProgress = this.isPlainObject(progress) ? progress : {};
|
||
await this.setTraceTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'running',
|
||
progress: safeProgress.progress || 0,
|
||
current_count: safeProgress.currentCount || 0,
|
||
total_count: safeProgress.totalCount || waybillCodes.length,
|
||
message: safeProgress.message || '正在查询运单物流轨迹',
|
||
result: null,
|
||
error: '',
|
||
});
|
||
},
|
||
});
|
||
|
||
if (!result || result.success !== true) {
|
||
await this.setTraceTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'failed',
|
||
progress: 100,
|
||
current_count: 0,
|
||
total_count: waybillCodes.length,
|
||
message: '更新物流轨迹失败',
|
||
result: null,
|
||
error: String(result && result.reason || '运单物流轨迹查询失败'),
|
||
});
|
||
return;
|
||
}
|
||
|
||
const failedList = Array.isArray(result.failed) ? result.failed : [];
|
||
await this.setTraceTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'success',
|
||
progress: 100,
|
||
current_count: waybillCodes.length,
|
||
total_count: waybillCodes.length,
|
||
message: `更新完成:新增 ${result.inserted} 条轨迹,更新 ${result.updated} 条,失败 ${failedList.length} 单`,
|
||
result: {
|
||
total: result.total,
|
||
matched: result.matched,
|
||
inserted: result.inserted,
|
||
updated: result.updated,
|
||
not_found: Array.isArray(result.not_found) ? result.not_found : [],
|
||
failed: failedList,
|
||
},
|
||
error: '',
|
||
});
|
||
} catch (error) {
|
||
const errorMessage = error && error.message ? error.message : `${error}`;
|
||
await this.setTraceTaskProgress(taskId, {
|
||
task_id: taskId,
|
||
status: 'failed',
|
||
progress: 100,
|
||
message: '更新物流轨迹失败',
|
||
result: null,
|
||
error: errorMessage,
|
||
});
|
||
}
|
||
});
|
||
|
||
return this.success('ok', {
|
||
...taskPayload,
|
||
update_time: Date.now(),
|
||
});
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 查询运单物流轨迹更新任务进度。
|
||
*
|
||
* @param {Object} data 请求参数。
|
||
* @param {string} [data.task_id] 任务ID(下划线写法)。
|
||
* @param {string} [data.taskId] 任务ID(驼峰写法)。
|
||
* @return {Promise<Object>} 任务进度信息。
|
||
*/
|
||
async updateTraceTaskProgress(data = {}) {
|
||
try {
|
||
const safeData = this.isPlainObject(data) ? data : {};
|
||
const taskId = String(safeData.task_id || safeData.taskId || '').trim();
|
||
const notFoundPayload = {
|
||
task_id: taskId,
|
||
status: 'not_found',
|
||
progress: 0,
|
||
current_count: 0,
|
||
total_count: 0,
|
||
message: '任务不存在',
|
||
result: null,
|
||
error: '',
|
||
update_time: Date.now(),
|
||
};
|
||
|
||
if (!taskId) {
|
||
return this.success('ok', notFoundPayload);
|
||
}
|
||
|
||
const cachedTask = await this.getTraceTaskProgress(taskId);
|
||
if (!cachedTask) {
|
||
return this.success('ok', notFoundPayload);
|
||
}
|
||
|
||
return this.success('ok', {
|
||
task_id: taskId,
|
||
...cachedTask,
|
||
update_time: Date.now(),
|
||
});
|
||
} catch (e) {
|
||
return this.fail(e.message);
|
||
}
|
||
}
|
||
|
||
/**
|
||
* 生成运单物流轨迹更新任务ID。
|
||
* @return {string} 任务ID。
|
||
*/
|
||
generateTraceTaskId() {
|
||
const warehouseId = this.ctx?.user?.store_id || 'unknown';
|
||
const timestamp = Date.now();
|
||
const randomToken = Math.random().toString(36).slice(2, 10);
|
||
return `waybill_trace_${warehouseId}_${timestamp}_${randomToken}`;
|
||
}
|
||
|
||
/**
|
||
* 解析仓库承接 waybill.getTrace 的 API 应用 AppKey(按 id 升序取首个)。
|
||
* @param {number} warehouseId 仓库ID。
|
||
* @return {Promise<string>} 目标应用 AppKey,未配置时返回空字符串。
|
||
*/
|
||
async resolveTraceAppKey(warehouseId) {
|
||
const warehouseNotify = this.service.systems && this.service.systems.warehouseNotify;
|
||
if (!warehouseNotify || typeof warehouseNotify.listCallbackConfigs !== 'function') {
|
||
return '';
|
||
}
|
||
|
||
const candidates = await warehouseNotify.listCallbackConfigs(
|
||
Number(warehouseId) || 0,
|
||
WAYBILL_TRACE_EVENT
|
||
);
|
||
const first = Array.isArray(candidates) ? candidates[0] : null;
|
||
return String(first && first.appKey || '').trim();
|
||
}
|
||
|
||
/**
|
||
* 写入运单物流轨迹任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @param {Object} payload 任务状态。
|
||
* @return {Promise<void>} 无返回值。
|
||
*/
|
||
async setTraceTaskProgress(taskId = '', payload = {}) {
|
||
await this.setTaskProgress(taskId, payload, WAYBILL_TRACE_TASK_CACHE_KEY_PREFIX);
|
||
}
|
||
|
||
/**
|
||
* 读取运单物流轨迹任务进度缓存。
|
||
* @param {string} taskId 任务ID。
|
||
* @return {Promise<Object|null>} 任务状态对象或 null。
|
||
*/
|
||
async getTraceTaskProgress(taskId = '') {
|
||
return await this.getTaskProgress(taskId, WAYBILL_TRACE_TASK_CACHE_KEY_PREFIX);
|
||
}
|
||
}
|
||
|
||
module.exports = WaybillWarehouseService;
|