'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_'; /** 揽收状态查询所依赖的出站回调 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'; const _noNeedLog = ''; const _noNeedAuth = 'list,detail,export,exportTaskProgress,updateReceive,updateReceiveTaskProgress'; 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} 运单列表与分页信息。 */ 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} 运单详情(含订单/打印/打包信息)。 */ 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} 任务提交结果,含 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} 任务进度信息。 */ 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} 任务提交结果,含 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} 任务进度信息。 */ 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} waybillCodes 原始运单号列表。 * @return {Array} 规范化后的运单号列表。 */ 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} 目标应用 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} 无返回值。 */ 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} 任务状态对象或 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} 无返回值。 */ async setExportTaskProgress(taskId = '', payload = {}) { await this.setTaskProgress(taskId, payload, WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX); } /** * 读取运单导出任务进度缓存。 * @param {string} taskId 任务ID。 * @return {Promise} 任务状态对象或 null。 */ async getExportTaskProgress(taskId = '') { return await this.getTaskProgress(taskId, WAYBILL_EXPORT_TASK_CACHE_KEY_PREFIX); } /** * 写入运单揽收状态更新任务进度缓存。 * @param {string} taskId 任务ID。 * @param {Object} payload 任务状态。 * @return {Promise} 无返回值。 */ async setReceiveTaskProgress(taskId = '', payload = {}) { await this.setTaskProgress(taskId, payload, WAYBILL_RECEIVE_TASK_CACHE_KEY_PREFIX); } /** * 读取运单揽收状态更新任务进度缓存。 * @param {string} taskId 任务ID。 * @return {Promise} 任务状态对象或 null。 */ async getReceiveTaskProgress(taskId = '') { return await this.getTaskProgress(taskId, WAYBILL_RECEIVE_TASK_CACHE_KEY_PREFIX); } } module.exports = WaybillWarehouseService;