feat(returnReceived): 退回收到列表异步导出,分页拉取流式生成 Excel 上传 COS,复用 list 查询语义并强制仓库隔离

This commit is contained in:
liufumingren 2026-09-03 17:03:40 +08:00
parent bc0d62d297
commit 716af0b9ff
2 changed files with 543 additions and 3 deletions

View File

@ -2,6 +2,9 @@
const MainService = require('../main');
const RETURN_RECEIVED_EXPORT_TASK_CACHE_KEY_PREFIX = 'return_received_export_task_';
const RETURN_RECEIVED_EXPORT_TASK_CACHE_TTL_SECONDS = 1800;
/**
* 系统方法层:returnReceived(退回收到模块接口包装层)。
* 主要职责:统一包装系统方法接口,处理权限、where 解析等公共逻辑,
@ -102,6 +105,263 @@ class ReturnReceivedMethodService extends MainService {
const { id } = data;
return this._call(() => this.service.systems.returnReceived.delete(Number(id)), '删除失败');
}
/**
* 提交退回收到登记列表导出任务(异步任务模式,与 returnUnpack.export 口径一致)。
* 入参 where/sort 与 list 完全一致;提交后立即返回 task_id,
* 后台异步生成单 Sheet Excel(退回收到登记列表)并上传,
* 通过 exportTaskProgress 查询进度与下载链接。
* warehouse_id 由服务端从 ctx.user.store_id 注入,禁止前端传入。
*
* @param {Object} data 请求体。
* @param {Object} [data.where] 筛选条件(与 list 的 where 语义一致)。
* @param {Object} [data.sort] 排序参数(与 list 的 sort 语义一致)。
* @return {Promise<Object>} 统一成功包装响应(含 task_id/status/progress 等任务信息)。
*/
async export(data = {}) {
const { service } = this;
const { sort } = data;
const { where } = this.prepareWhereContext(data, {});
// 仓库隔离:由服务端从当前上下文自动注入,禁止前端传入
const warehouseId = Number(this.ctx.user && this.ctx.user.store_id || 0);
const enforcedWhere = { ...where };
if (warehouseId > 0) {
enforcedWhere.warehouse_id = { operator: 'eq', value: warehouseId };
}
const taskId = this.generateExportTaskId(warehouseId);
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 service.systems.returnReceived.exportList({
where: enforcedWhere,
sort,
warehouseId,
onProgress: async progress => {
const safeProgress = this.isPlainObject(progress) ? progress : {};
await this.setExportTaskProgress(taskId, {
task_id: taskId,
status: safeProgress.status || 'running',
progress: safeProgress.progress,
current_count: safeProgress.currentCount,
total_count: safeProgress.totalCount,
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,
current_count: 0,
total_count: 0,
message: '退回收到导出任务失败',
result: null,
error: errorMessage,
});
}
});
return this.success('ok', {
...taskPayload,
update_time: Date.now(),
});
}
/**
* 查询退回收到导出任务进度(与 order.exportTaskProgress 口径一致)。
*
* @param {Object} data 请求体。
* @param {string} [data.task_id] 任务ID(下划线写法)。
* @param {string} [data.taskId] 任务ID(驼峰写法)。
* @return {Promise<Object>} 统一成功包装响应
* (含 task_id/status/progress/current_count/total_count/message/error/download_url/update_time)。
*/
async exportTaskProgress(data = {}) {
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.cdnUrl
|| safeResult.cosUrl
|| safeResult.fileKey
|| ''
);
return this.success('ok', {
task_id: taskId,
...cachedTask,
download_url: downloadUrl,
});
}
/**
* 生成退回收到导出任务ID。
* @param {number|string} [warehouseId=''] 仓库ID(缺省兜底取当前上下文 store_id)。
* @return {string} 导出任务ID。
*/
generateExportTaskId(warehouseId = '') {
const normalizedWarehouseId = warehouseId || this.ctx?.user?.store_id || 'unknown';
const timestamp = Date.now();
const randomToken = Math.random().toString(36).slice(2, 10);
return `return_received_export_${normalizedWarehouseId}_${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 `${RETURN_RECEIVED_EXPORT_TASK_CACHE_KEY_PREFIX}${normalizedTaskId}`;
}
/**
* 写入退回收到导出任务进度缓存(Redis TTL 30 分钟)。
* @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 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 || ''),
update_time: Date.now(),
};
try {
await this.app.setCacheAsync(cacheKey, progressPayload, RETURN_RECEIVED_EXPORT_TASK_CACHE_TTL_SECONDS);
} catch (error) {
const errorMessage = error && error.message ? error.message : `${error}`;
this.ctx.logger.warn(`[returnReceived.export] 写入导出任务缓存失败: ${errorMessage}`);
}
}
/**
* 读取退回收到导出任务进度缓存。
* @param {string} taskId 任务ID。
* @return {Promise<Object|null>} 任务缓存,未命中返回 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(`[returnReceived.export] 读取导出任务缓存失败: ${errorMessage}`);
return null;
}
}
}
module.exports = ReturnReceivedMethodService;

View File

@ -1,7 +1,16 @@
'use strict';
const crypto = require('node:crypto');
const fs = require('node:fs');
const fsp = require('node:fs/promises');
const os = require('node:os');
const path = require('node:path');
const ExcelJS = require('exceljs');
const Service = require('egg').Service;
/** 退回收到导出分页拉取大小 */
const RETURN_RECEIVED_EXPORT_PAGE_SIZE = 500;
/**
* 退回收到模块业务逻辑层。
* 负责 wms_return_received 的增删查,以及原单反查、货主备注、30 日幂等等核心操作。
@ -22,7 +31,8 @@ class ReturnReceivedService extends Service {
/**
* 扫码登记退回包裹(30 日内同仓库同单号只写一次,以第一次为准)。
* 反查原运单判定是否原单退回,命中则回填关联字段并同步标记 is_back='Y'。
* 反查原运单判定是否原单退回,命中则回填关联字段并同步标记 is_back='Y',
* 并释放订单对应的拦截锁定库存(intercept_locked_quantity 回落到可用数量)。
*
* @param {Object} params 登记参数。
* @param {string} params.waybill_code 退回收件运单号。
@ -156,6 +166,8 @@ class ReturnReceivedService extends Service {
await this._handleInterceptAfterSale(waybillCode, warehouseId, scannerId, scannerName);
if (orderId) {
await this._updateOrderInterceptStatus(orderId, warehouseId, scannerId, scannerName);
// 注意:退货登记不释放拦截锁定数量——拦截锁的回落由退货货物后续入库处理
// (入库平账/差异对账链路)统一接管,避免登记环节直接改动库存口径。
}
}
@ -471,6 +483,229 @@ class ReturnReceivedService extends Service {
};
}
/**
* 导出退回收到登记列表(单 Sheet Excel,异步任务模式,与 returnUnpack.export 口径一致)。
* 复用 list 的 where/sort 语义;仓库隔离由方法层注入 warehouse_id,此处再强制兜底;
* 分页拉取主表全量数据后批量解析货主备注,流式生成 Excel 并上传 COS。
*
* @param {Object} options 导出选项。
* @param {Object} [options.where] 标准化 where 条件(与 list 一致)。
* @param {Object} [options.sort] 排序参数(与 list 一致)。
* @param {number} [options.warehouseId] 仓库ID(由方法层从上下文注入)。
* @param {Function} [options.onProgress] 进度回调。
* @return {Promise<Object>} 上传结果与统计信息(含 filename/fileKey/url/cdnUrl/cosUrl/current_count/total_count)。
*/
async exportList(options = {}) {
const { ctx, app } = this;
const { Op } = app.Sequelize;
const safeOptions = options && typeof options === 'object' && !Array.isArray(options) ? options : {};
const where = safeOptions.where && typeof safeOptions.where === 'object' ? { ...safeOptions.where } : {};
const sort = safeOptions.sort && typeof safeOptions.sort === 'object' ? { ...safeOptions.sort } : {};
const warehouseId = Number(safeOptions.warehouseId || 0);
const progressHandler = typeof safeOptions.onProgress === 'function'
? safeOptions.onProgress
: async () => {};
if (!Number.isFinite(warehouseId) || warehouseId <= 0) {
throw this.createBusinessError('缺少仓库上下文', 400);
}
// 复用 list 的 where/sort 语义,并强制仓库隔离(服务端注入,前端无需传 warehouse_id)
const queryWhere = this._buildListWhere(where, Op);
queryWhere.warehouse_id = warehouseId;
const order = this._buildListOrder(sort);
const totalCount = await ctx.model.ReturnReceived.count({ where: queryWhere });
await progressHandler({
status: 'running',
progress: totalCount > 0 ? 10 : 85,
currentCount: 0,
totalCount,
message: totalCount > 0 ? `已命中 ${totalCount} 条登记记录,开始导出` : '未命中数据,开始生成空文件',
});
// ---- 分页拉取主表全量数据(复用 list 的 pageSize 口径,避免单次内存溢出)----
const pageSize = RETURN_RECEIVED_EXPORT_PAGE_SIZE;
const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
const allRows = [];
for (let page = 1; page <= totalPages; page += 1) {
if (allRows.length >= totalCount) {
break;
}
const { rows } = await ctx.model.ReturnReceived.findAndCountAll({
where: queryWhere,
order,
offset: (page - 1) * pageSize,
limit: pageSize,
raw: true,
});
for (const row of rows) {
allRows.push(row);
}
await progressHandler({
status: 'running',
progress: Math.min(55, 10 + Math.round((allRows.length / Math.max(totalCount, 1)) * 45)),
currentCount: allRows.length,
totalCount,
message: `正在拉取登记列表,已完成 ${allRows.length}/${totalCount}`,
});
// 每页之间稍作让渡,避免长时间阻塞
await new Promise(resolve => setImmediate(resolve));
}
// ---- 批量解析货主备注(避免逐行查询)----
const storeRemarkMap = await this._resolveStoreRemarkMap(allRows, warehouseId, Op);
const enrichedRows = [];
for (const row of allRows) {
enrichedRows.push(await this._enrichReturn(row, storeRemarkMap));
}
await progressHandler({
status: 'running',
progress: 60,
currentCount: allRows.length,
totalCount,
message: '正在生成 Excel 文件...',
});
const exportResult = await this._generateExportExcel(enrichedRows, warehouseId);
await progressHandler({
status: 'success',
progress: 100,
currentCount: allRows.length,
totalCount,
message: '导出任务完成',
result: exportResult,
});
return {
...exportResult,
current_count: allRows.length,
total_count: totalCount,
};
}
/**
* 生成退回收到导出 Excel(单 Sheet)并上传 COS,返回下载信息。
* 流式写入临时文件后通过 upload.uploadFile 上传,上传结果落库通知。
*
* @param {Array<Object>} rows 已组装展示字段的登记记录行。
* @param {number} warehouseId 仓库ID。
* @return {Promise<Object>} { filename, fileKey, url, cdnUrl, cosUrl }。
*/
async _generateExportExcel(rows = [], warehouseId) {
const { ctx, app } = this;
const normalizeCellValue = value => {
if (value === null || value === undefined) return '';
if (value instanceof Date) return app.formatDate ? app.formatDate(value) : value.toISOString();
return value;
};
const tempDir = await fsp.mkdtemp(path.join(os.tmpdir(), 'wms-return-received-export-'));
const now = new Date();
const dateToken = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`;
const filename = `退回收到导出_${dateToken}.xlsx`;
const filePath = path.join(tempDir, filename);
const workbook = new ExcelJS.stream.xlsx.WorkbookWriter({
filename: filePath,
useStyles: false,
useSharedStrings: false,
});
try {
const worksheet = workbook.addWorksheet('退回收到登记列表');
worksheet.columns = [
{ header: '运单号', key: 'waybill_code', width: 22 },
{ header: '扫描日期', key: 'scan_date', width: 14 },
{ header: '扫描人员', key: 'scanner_name', width: 14 },
{ header: '是否原单退回', key: 'is_original_return', width: 12 },
{ header: '订单ID', key: 'order_id', width: 14 },
{ header: '货主备注', key: 'store_remark', width: 20 },
{ header: '备注', key: 'remark', width: 30 },
{ header: '登记时间', key: 'created_at', width: 20 },
{ header: '更新时间', key: 'updated_at', width: 20 },
];
for (const row of rows) {
worksheet.addRow({
waybill_code: normalizeCellValue(row.waybill_code),
scan_date: normalizeCellValue(row.scan_date),
scanner_name: normalizeCellValue(row.scanner_name),
is_original_return: row.is_original_return ? '是' : '否',
order_id: row.order_id || '',
store_remark: normalizeCellValue(row.store_remark),
remark: normalizeCellValue(row.remark),
created_at: normalizeCellValue(row.created_at),
updated_at: normalizeCellValue(row.updated_at),
}).commit();
}
worksheet.commit();
await workbook.commit();
// ---- 上传文件(与 returnUnpack 导出口径一致)----
const uploadService = ctx?.service?.systems?.upload;
if (!uploadService || typeof uploadService.uploadFile !== 'function') {
throw new Error('上传服务不可用');
}
const stat = await fsp.stat(filePath);
const randomToken = crypto.randomBytes(6).toString('hex');
const uploadKey = `exports/return_received/${warehouseId}/${Date.now()}_${randomToken}.xlsx`;
const uploadStream = fs.createReadStream(filePath);
uploadStream.filename = filename;
uploadStream.mimeType = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
uploadStream.fileSize = stat.size;
const uploadResult = await uploadService.uploadFile(uploadStream, {
key: uploadKey,
category: 'document',
mimetype: 'xls,xlsx,csv',
});
let fileRecord = null;
if (typeof uploadService.uploadSuccessNotify === 'function') {
fileRecord = await uploadService.uploadSuccessNotify({
url: uploadResult.fileName,
fileKey: uploadResult.fileName,
fileName: filename,
fileType: 'document',
mimeType: uploadStream.mimeType,
fileSize: stat.size,
userId: ctx.userId,
description: `退回收到登记导出(仓库${warehouseId}),共${rows.length}条登记记录`,
});
}
// 优先取 uploadFile 返回的完整 URL,其次取 uploadSuccessNotify 落库记录(兼容 data 包裹),最后才回退 COS key
const safeUploadResult = typeof uploadResult === 'object' && uploadResult !== null ? uploadResult : {};
const resolvedFileRecord = (fileRecord && (fileRecord.data || fileRecord)) || null;
const fileUrlFromRecord = resolvedFileRecord
? (resolvedFileRecord.file_url || resolvedFileRecord.fileUrl || resolvedFileRecord.url || '')
: '';
const uploadResultUrl = safeUploadResult.url || safeUploadResult.cdnUrl || safeUploadResult.cosUrl || '';
return {
filename,
fileKey: safeUploadResult.fileName || uploadKey,
url: uploadResultUrl || fileUrlFromRecord || safeUploadResult.fileName || uploadKey,
cdnUrl: safeUploadResult.cdnUrl || safeUploadResult.url || '',
cosUrl: safeUploadResult.cosUrl || '',
};
} catch (error) {
const workbookStream = workbook.stream;
if (workbookStream && typeof workbookStream.destroy === 'function') {
workbookStream.destroy();
}
throw error;
} finally {
// 清理临时文件(不存在或删除失败均忽略)
try { await fsp.rm(tempDir, { recursive: true, force: true }); } catch (err) { /* ignore */ }
}
}
/**
* 查询单条退回收到登记详情(含原运单与货主合约备注)。
*
@ -557,13 +792,20 @@ class ReturnReceivedService extends Service {
* 组装登记记录展示字段(是否原单退回、货主备注、时间格式化)。
*
* @param {Object} row 登记记录原始数据。
* @param {Map<string, string>} [remarkMap] 预解析的货主备注映射(key=store_id:warehouse_id),
* 传入时跳过逐行查询直接取映射值;不传时逐行查询。
* @return {Promise<Object>} 组装后的记录。
*/
async _enrichReturn(row) {
async _enrichReturn(row, remarkMap = null) {
const { app } = this;
const record = { ...row };
record.is_original_return = Boolean(record.order_express_id);
record.store_remark = await this._resolveStoreRemark(record);
if (remarkMap instanceof Map) {
const remarkKey = `${Number(record.store_id || 0)}:${Number(record.warehouse_id || 0)}`;
record.store_remark = remarkMap.get(remarkKey) || '';
} else {
record.store_remark = await this._resolveStoreRemark(record);
}
// 时间格式化(与 afterSale._formatAfterSaleRow 一致,直接覆盖为本地时间字符串)
record.scan_date = record.scan_date ? app.formatDate(record.scan_date, 'YYYY-MM-DD') : null;
record.created_at = record.created_at ? app.formatDate(record.created_at) : null;
@ -597,6 +839,44 @@ class ReturnReceivedService extends Service {
}
}
/**
* 批量解析货主备注映射(store_id:warehouse_id → wms_store_warehouse.store_remask)。
* 导出时一次查询全部货主合约,避免逐行查询。
*
* @param {Array<Object>} rows 登记记录行数组。
* @param {number} warehouseId 仓库ID。
* @param {Object} Op Sequelize Op 对象。
* @return {Promise<Map<string, string>>} key=store_id:warehouse_id → 货主备注映射。
*/
async _resolveStoreRemarkMap(rows = [], warehouseId, Op) {
const { ctx } = this;
const normalizedWarehouseId = Number(warehouseId || 0);
const storeIds = [ ...new Set(
(Array.isArray(rows) ? rows : [])
.map(row => Number(row && row.store_id || 0))
.filter(id => Number.isInteger(id) && id > 0)
) ];
/** @type {Map<string, string>} */
const remarkMap = new Map();
if (storeIds.length === 0 || !Number.isFinite(normalizedWarehouseId) || normalizedWarehouseId <= 0) {
return remarkMap;
}
try {
const contracts = await ctx.model.StoreWarehouse.findAll({
where: { store_id: { [Op.in]: storeIds }, warehouse_id: normalizedWarehouseId },
attributes: [ 'store_id', 'store_remask' ],
raw: true,
});
for (const contract of contracts) {
const key = `${Number(contract.store_id)}:${normalizedWarehouseId}`;
remarkMap.set(key, contract.store_remask ? String(contract.store_remask) : '');
}
} catch (err) {
ctx.logger.warn(`[returnReceived.export] 批量解析货主备注失败: ${err.message}`);
}
return remarkMap;
}
/**
* 根据标准化 where 条件构建 Sequelize 查询条件。
*