liufumingren b436b6dd9e feat: 拦截链路全流程完善 — 新增interceptScan + 运单表同步 + 工单通知
新增:
- order.recheckOrder.interceptScan: 拦截扫描接口,入参运单号,查express标记退回,处理工单,更新订单拦截状态
- afterSale.createInterceptWorkOrdersAndNotify: 共享方法,幂等创建工单+通知快递群

修复:
- confirmIntercept: 补运单is_back同步(仅限is_intercept=Y),补工单创建+通知
- batchIntercept: 补运单is_intercept同步,补工单创建+通知
- batchUnintercept: 补运单is_intercept/is_back清除
- Qimen/OpenAPI cancel: 补运单is_intercept同步,补工单创建+通知
- interceptScan: 删除死查询,加空指针兜底

文档:
- methods/system.json: interceptScan + confirmIntercept 完整API文档
- methods/changes/system.json: 变更记录
2026-08-12 20:47:19 +08:00

681 lines
23 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 RECEIVING_EXPORT_TASK_CACHE_KEY_PREFIX = 'receiving_export_task_';
const RECEIVING_EXPORT_TASK_CACHE_TTL_SECONDS = 1800;
/**
* 系统方法层:storage.receiving(收货单相关接口包装层)。
* 主要职责:统一包装系统方法接口,处理权限、日志等公共逻辑,调用底层 service 实现业务功能。
* 注意:当前实现仅为包装层,实际业务逻辑完全依赖底层 service 的方法实现。
*/
class configService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'getReceivingList,getStoreReceivingList,get,addDetail,deleteDetail,detailChange,cancel,completeReceiving,bindStore,bindDetailProduct,rejectReceiving,reviewReceiving,queryReceivingLogs,scanDetail,export,exportTaskProgress,storeExport,storeExportTaskProgress';
const _noNeedLog = '';
const _noNeedAuth = 'getReceivingList,getStoreReceivingList,get,addDetail,deleteDetail,detailChange,cancel,completeReceiving,bindStore,bindDetailProduct,rejectReceiving,reviewReceiving,queryReceivingLogs,scanDetail,export,exportTaskProgress,storeExport,storeExportTaskProgress';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 收货单列表查询(system method 包装层)。
* @param {Object} data 请求体
* @param {Object} [data.pagination] 分页参数
* @param {Object} [data.where] 筛选条件
* @param {boolean} [data.filterDepleted=false] 是否过滤掉无可再用量的收货单(所有明细已被其他入库单 committed 绑定占满)
* @param {number} [data.entry_order_id] 可选,按入库单商品交集过滤:只返回"至少有一条明细的 system_product_id 在入库单明细中"的收货单
* @return {Promise<Object>} 统一成功包装响应
*/
async getReceivingList(data) {
const { service } = this;
const { pagination, sort, filterDepleted = false, entry_order_id: entryOrderId } = data;
const { where } = this.prepareWhereContext(data, {
specialFieldMap: {
quickWhere: {
bucket: 'quick',
},
},
});
const result = await service.systems.storage.receiving.getReceivingList(where, pagination, sort, { filterDepleted, entry_order_id: entryOrderId });
return this.success('ok', result);
}
/**
* 货主侧收货单列表查询(system method 包装层)。
* 以当前平台激活的货主 store_id 为维度查询收货单。
* @param {Object} data 请求体
* @param {Object} [data.pagination] 分页参数
* @param {Object} [data.where] 筛选条件
* @param {Object} [data.sort] 排序参数
* @return {Promise<Object>} 统一成功包装响应
*/
async getStoreReceivingList(data) {
const { ctx, app } = this;
const { pagination, sort } = data;
// 从平台激活上下文获取 store_id(使用原生查询避免 AccountPlatformActive 无 id 列兼容问题)
const platformRows = await app.model.query(
'SELECT apa.employee_id, ase.store_id FROM wms_account_platform_active apa ' +
'INNER JOIN wms_account_store_employee ase ON ase.id = apa.employee_id AND ase.status = 1 ' +
'WHERE apa.account_id = :accountId AND apa.platform_code = :platformCode LIMIT 1',
{
replacements: { accountId: ctx.userId, platformCode: ctx.platformCode || 'web' },
type: app.Sequelize.QueryTypes.SELECT,
}
);
if (!platformRows || platformRows.length === 0 || !platformRows[0].store_id) {
return this.fail('未获取到货主平台激活上下文,请先切换至货主角色');
}
const storeId = platformRows[0].store_id;
const { where } = this.prepareWhereContext(data, {
specialFieldMap: {
quickWhere: {
bucket: 'quick',
},
},
});
const { service } = this;
const result = await service.systems.storage.receiving.getStoreReceivingList(
where,
storeId,
pagination,
sort
);
return this.success('ok', result);
}
/**
* 收货单详情查询(分页返回明细)。
* @param {Object} data 请求体
* @param {number} data.id 收货单ID
* @param {Object} data.pagination 明细分页参数
* @return {Promise<Object>} 统一成功包装响应
*/
async getReceivingDetail(data) {
const { service } = this;
const result = await service.systems.storage.receiving.getReceivingDetail(data);
return this.success('ok', result);
}
/**
* 批量作废收货单。
* @param {Object} data 请求体
* @param {number[]} data.ids 收货单ID数组
* @return {Promise<Object>} 统一成功包装响应
*/
async batchCancelReceiving(data) {
const { service } = this;
const result = await service.systems.storage.receiving.batchCancelReceiving(data);
return this.success('ok', result);
}
/**
* 创建收货单。
* @param {Object} data 请求体
* @return {Promise<Object>} 统一成功包装响应
*/
async create(data) {
const { service } = this;
const result = await service.systems.storage.receiving.create(data);
return this.success('创建失败', result);
}
/**
* 绑定收货单货主。
* @param {Object} data 请求体
* @param {number} data.id 收货单ID
* @param {number} data.store_id 货主ID
* @return {Promise<Object>} 统一成功包装响应
*/
async bindStore(data) {
const { service } = this;
const result = await service.systems.storage.receiving.bindStore(data);
return this.success('ok', result);
}
/**
* 绑定或改绑收货单明细商品。
* @param {Object} data 请求体
* @param {number} data.detail_id 收货单明细ID
* @param {number} data.system_product_id 商品ID
* @return {Promise<Object>} 统一成功包装响应
*/
async bindDetailProduct(data) {
const { service } = this;
const result = await service.systems.storage.receiving.bindDetailProduct(data);
return this.success('ok', result);
}
/**
* 添加收货商品(当前依赖底层 addItem 实现)。
* @param {Object} data 请求体
* @param {number} data.id 收货单ID
* @param {Object} data.item 商品信息
* @return {Promise<Object>} 统一成功包装响应
*/
async addItem(data) {
const { service } = this;
const { id, item } = data;
const result = await service.systems.storage.receiving.addItem(id, item);
return this.success('ok', result);
}
/**
* 删除收货商品(当前依赖底层 removeItem 实现)。
* @param {Object} data 请求体
* @param {number} data.id 收货单ID
* @param {number} data.item_id 商品明细ID
* @return {Promise<Object>} 统一成功包装响应
*/
async removeItem(data) {
const { service } = this;
const { id, item_id } = data;
const result = await service.systems.storage.receiving.removeItem(id, item_id);
return this.success('ok', result);
}
/**
* 保存收货单。
* @param {Object} data 请求体
* @return {Promise<Object>} 统一成功包装响应
*/
async save(data) {
const { service } = this;
const result = await service.systems.storage.receiving.save(data);
return this.success('ok', result);
}
/**
* 查询收货单完整信息(含明细与图片)。
* @param {Object} data 请求体
* @param {number} data.id 收货单ID
* @return {Promise<Object>} 统一成功包装响应
*/
async get(data) {
const { service } = this;
const result = await service.systems.storage.receiving.get(data);
return this.success('ok', result);
}
/**
* 新增一条收货明细(支持可选 item)。
* @param {Object} data 请求体
* @return {Promise<Object>} 统一成功包装响应
*/
async addDetail(data) {
const { service } = this;
const result = await service.systems.storage.receiving.addDetail(data);
return this.success('ok', result);
}
/**
* 删除收货明细。
* @param {Object} data 请求体
* @return {Promise<Object>} 统一成功包装响应
*/
async deleteDetail(data) {
const { service } = this;
const result = await service.systems.storage.receiving.deleteDetail(data);
return this.success('ok', result);
}
/**
* 修改收货明细字段。
* @param {Object} data 请求体
* @return {Promise<Object>} 统一成功包装响应
*/
async detailChange(data) {
const { service } = this;
const result = await service.systems.storage.receiving.detailChange(data);
return this.success('ok', result);
}
/**
* 作废收货单(单条)。
* @param {Object} data 请求体
* @return {Promise<Object>} 统一成功包装响应
*/
async cancel(data) {
const { service } = this;
const result = await service.systems.storage.receiving.invalid(data);
return this.success('ok', result);
}
/**
* 完成收货单并触发入库处理。
* @param {Object} data 请求体
* @param {number} data.id 收货单ID
* @param {string} [data.remark] 完成备注
* @return {Promise<Object>} 统一成功包装响应
*/
async completeReceiving(data) {
const { service } = this;
const result = await service.systems.storage.receiving.completeReceiving(data);
return this.success('ok', result);
}
/**
* 驳回收货单:将已完成收货单恢复为收货中,记录审核人信息与驳回理由。
* @param {Object} data 请求体
* @param {number[]} data.ids 收货单ID数组
* @param {string} [data.remark] 驳回理由(覆盖原备注)
* @return {Promise<Object>} 统一成功包装响应
*/
async rejectReceiving(data) {
const { service } = this;
const result = await service.systems.storage.receiving.rejectReceiving(data);
return this.success('ok', result);
}
/**
* 批量审核收货单。
* @param {Object} data 请求体
* @param {number[]} data.ids 收货单ID数组
* @return {Promise<Object>} 统一成功包装响应
*/
async reviewReceiving(data) {
const { service } = this;
const { ids } = data || {};
const result = await service.systems.storage.receiving.reviewReceiving({ ids });
return this.success('ok', result);
}
/**
* 查询收货单操作日志(分页)。
* @param {Object} data 请求体
* @param {number|string} data.receiving_id 收货单ID
* @param {Object} [data.pagination] 分页对象,支持 page/pageSize
* @return {Promise<Object>} 统一成功包装响应
*/
async queryReceivingLogs(data = {}) {
const { ctx, service } = this;
const requestData = data && typeof data === 'object' ? data : {};
const pagination = requestData.pagination && typeof requestData.pagination === 'object'
? requestData.pagination
: {};
const result = await service.systems.operationLog.queryReceivingLogs({
id: requestData.receiving_id,
page: pagination.page,
pageSize: pagination.pageSize || pagination.page_size,
warehouseId: ctx.user.store_id,
});
return this.success('ok', {
data: result,
code: 200,
});
}
/**
* PDA 扫码定位收货明细(system method 包装层),返回匹配的明细列表。
* 同一条码可能匹配到多条收货明细,以列表形式返回所有匹配结果。
* @param {Object} data 请求体
* @param {number} data.entry_order_id 入库单ID
* @param {string} data.barcode 扫描条码(商品条码/箱唛/托盘唛/明细ID)
* @return {Promise<Object>} 统一成功包装响应,含匹配的收货明细列表 { list, total }
*/
async scanDetail(data) {
const { service } = this;
const { entry_order_id, barcode } = data;
const result = await service.systems.storage.receiving.scanDetail(entry_order_id, barcode);
if (result.code !== 200) {
return this.fail(result.message);
}
return this.success('查询成功', result.data);
}
/**
* 提交收货单导出任务(仓库维度,复用 getReceivingList 的筛选语义与排序规则)。
* 导出分为两个 sheet:Sheet1=收货单列表,Sheet2=收货单明细。
* @param {Object} data 请求体
* @param {Object} [data.where] 筛选条件(与 getReceivingList 一致)
* @param {Object} [data.sort] 排序参数
* @return {Promise<Object>} 统一成功包装响应,data 为导出任务信息
*/
async export(data = {}) {
const { service } = this;
const { sort = {} } = data;
const { where } = this.prepareWhereContext(data, {
specialFieldMap: {
quickWhere: { bucket: 'quick' },
},
});
const taskId = this.generateExportTaskId();
const taskPayload = {
task_id: taskId,
status: 'submitted',
progress: 0,
message: '收货单导出任务已提交',
result: null,
error: '',
};
await this.setExportTaskProgress(taskId, taskPayload);
setImmediate(async () => {
try {
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'running',
progress: 5,
message: '收货单导出任务执行中',
result: null,
error: '',
});
const result = await service.systems.storage.receiving.exportReceivingList({
where,
sort,
onProgress: async progress => {
const safeProgress = this.isPlainObject(progress) ? progress : {};
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: safeProgress.status || 'running',
progress: safeProgress.progress,
message: safeProgress.message || '收货单导出任务执行中',
result: safeProgress.result || null,
error: '',
});
},
});
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'success',
progress: 100,
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(),
});
}
/**
* 查询收货单导出任务进度。
* @param {Object} data 请求体
* @param {string} [data.task_id] 任务ID(下划线写法)
* @param {string} [data.taskId] 任务ID(驼峰写法)
* @return {Promise<Object>} 统一成功包装响应
*/
async exportTaskProgress(data = {}) {
const taskId = this.normalizeExportTaskId(data);
if (!taskId) {
return this.success('ok', {
task_id: '',
status: 'not_found',
progress: 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,
message: '任务不存在',
result: null,
error: '',
download_url: '',
update_time: Date.now(),
});
}
const safeResult = this.isPlainObject(cachedTask.result) ? cachedTask.result : {};
const downloadUrl = String(
safeResult.url
|| safeResult.cdnUrl
|| safeResult.cosUrl
|| safeResult.fileKey
|| ''
);
return this.success('ok', {
task_id: taskId,
...cachedTask,
download_url: downloadUrl,
});
}
/**
* 生成收货单导出任务ID。
* @param {string} [prefix=''] 任务类型前缀(如 'store')
* @return {string} 导出任务ID
*/
generateExportTaskId(prefix = '') {
const storeId = this.ctx?.user?.store_id || 'unknown';
const timestamp = Date.now();
const randomToken = Math.random().toString(36).slice(2, 10);
const typePrefix = prefix ? `${prefix}_` : '';
return `receiving_${typePrefix}export_${storeId}_${timestamp}_${randomToken}`;
}
/**
* 归一化收货单导出任务ID。
* @param {Object} data 请求体
* @param {string} [data.task_id] 任务ID(下划线写法)
* @param {string} [data.taskId] 任务ID(驼峰写法)
* @return {string} 归一化后的任务ID
*/
normalizeExportTaskId(data = {}) {
const normalizedData = this.isPlainObject(data) ? data : {};
return String(normalizedData.task_id || normalizedData.taskId || '').trim();
}
/**
* 获取收货单导出任务缓存键。
* @param {string} taskId 任务ID
* @return {string} 缓存键
*/
getExportTaskCacheKey(taskId = '') {
const normalizedTaskId = String(taskId || '').trim();
if (!normalizedTaskId) {
return '';
}
return `${RECEIVING_EXPORT_TASK_CACHE_KEY_PREFIX}${normalizedTaskId}`;
}
/**
* 写入收货单导出任务进度缓存。
* @param {string} taskId 任务ID
* @param {Object} payload 任务状态载荷
* @return {Promise<void>} 无返回值
*/
async setExportTaskProgress(taskId = '', payload = {}) {
const cacheKey = this.getExportTaskCacheKey(taskId);
if (!cacheKey || typeof this.app.setCacheAsync !== 'function') {
return;
}
const safePayload = this.isPlainObject(payload) ? payload : {};
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,
message: String(safePayload.message || ''),
result: safePayload.result ?? null,
error: String(safePayload.error || ''),
update_time: Date.now(),
};
try {
await this.app.setCacheAsync(cacheKey, progressPayload, RECEIVING_EXPORT_TASK_CACHE_TTL_SECONDS);
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[storage.receiving.export] 写入导出任务缓存失败: ${errorMessage}`);
}
}
/**
* 读取收货单导出任务进度缓存。
* @param {string} taskId 任务ID
* @return {Promise<Object|null>} 任务缓存
*/
async getExportTaskProgress(taskId = '') {
const cacheKey = this.getExportTaskCacheKey(taskId);
if (!cacheKey || typeof this.app.getCacheAsync !== 'function') {
return null;
}
try {
const cached = await this.app.getCacheAsync(cacheKey);
if (!this.isPlainObject(cached)) {
return null;
}
return cached;
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[storage.receiving.export] 读取导出任务缓存失败: ${errorMessage}`);
return null;
}
}
/**
* 提交货主侧收货单导出任务(复用 getStoreReceivingList 的筛选语义与排序规则)。
* 以当前平台激活的货主 store_id 为维度导出。导出分为两个 sheet:Sheet1=收货单列表,Sheet2=收货单明细。
* @param {Object} data 请求体
* @param {Object} [data.where] 筛选条件(与 getStoreReceivingList 一致)
* @param {Object} [data.sort] 排序参数
* @return {Promise<Object>} 统一成功包装响应,data 为导出任务信息
*/
async storeExport(data = {}) {
const { ctx, app, service } = this;
// 从平台激活上下文获取 store_id
const platformRows = await app.model.query(
'SELECT apa.employee_id, ase.store_id FROM wms_account_platform_active apa ' +
'INNER JOIN wms_account_store_employee ase ON ase.id = apa.employee_id AND ase.status = 1 ' +
'WHERE apa.account_id = :accountId AND apa.platform_code = :platformCode LIMIT 1',
{
replacements: { accountId: ctx.userId, platformCode: ctx.platformCode || 'web' },
type: app.Sequelize.QueryTypes.SELECT,
}
);
if (!platformRows || platformRows.length === 0 || !platformRows[0].store_id) {
return this.fail('未获取到货主平台激活上下文,请先切换至货主角色');
}
const storeId = platformRows[0].store_id;
const { sort = {} } = data;
const { where } = this.prepareWhereContext(data, {
specialFieldMap: {
quickWhere: {
bucket: 'quick',
},
},
});
const taskId = this.generateExportTaskId('store');
const taskPayload = {
task_id: taskId,
status: 'submitted',
progress: 0,
message: '货主侧收货单导出任务已提交',
result: null,
error: '',
};
await this.setExportTaskProgress(taskId, taskPayload);
setImmediate(async () => {
try {
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'running',
progress: 5,
message: '货主侧收货单导出任务执行中',
result: null,
error: '',
});
const result = await service.systems.storage.receiving.exportStoreReceivingList({
where,
storeId,
sort,
onProgress: async progress => {
const safeProgress = this.isPlainObject(progress) ? progress : {};
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: safeProgress.status || 'running',
progress: safeProgress.progress,
message: safeProgress.message || '货主侧收货单导出任务执行中',
result: safeProgress.result || null,
error: '',
});
},
});
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: 'success',
progress: 100,
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(),
});
}
/**
* 查询货主侧收货单导出任务进度。
* 复用 exportTaskProgress 的缓存查询逻辑,任务 ID 前缀不同。
* @param {Object} data 请求体
* @param {string} [data.task_id] 任务ID(下划线写法)
* @param {string} [data.taskId] 任务ID(驼峰写法)
* @return {Promise<Object>} 统一成功包装响应
*/
async storeExportTaskProgress(data = {}) {
return this.exportTaskProgress(data);
}
}
module.exports = configService;