liufumingren e3eff20aaa feat(waybill): 批量更新运单揽收状态(waybill.getreceive)与 Y/N 标记列治理
- 新增出站回调 waybill.getreceive(注册到 callback_functions,管理端可勾选):
  请求 { request: { waybill_codes: [...] } },响应裸数组/包装体均兼容,
  1/0 与 Y/N 归一后回写 wms_order_express.is_galaxy_receive(按 warehouse_id 隔离)
- 回调签名新增 signMode=simple(MD5(appSecret+timestamp+bodyJson)),
  waybill.getreceive 使用该口径,与仓库通知协议一致;其它事件默认口径不变
- 新增 waybill.warehouse.updateReceive / updateReceiveTaskProgress:
  复用导出的异步任务ID与进度模式(前缀 waybill_receive_),单批 10 单自动切批;
  支持 waybillCodes 或与 waybill.warehouse.list 一致的 where 条件圈选(上限 5000);
  仓库未配置外部接口时直接失败,不创建任务
- 抽出 buildListQueryWhere / resolveWaybillCodesByWhere,列表与批量更新共用筛选口径
- order_express:is_back / is_intercept / is_galaxy_receive 补默认值 N
- 迁移:存量 NULL 回填为 N(Y 不动);三列分别建立单列索引(INPLACE + LOCK=NONE)
- 文档:methods/system.json(0.3.324)、变更记录、设计文档与出站回调说明同步

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

598 lines
20 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 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<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);
}
}
module.exports = WaybillWarehouseService;