feat: 新增退回收到模块(returnReceived)

- 新增退回收到登记表 wms_return_received 及模型、建表迁移
- 新增扫码登记/列表/详情/删除接口(systemMethods + systems 分层)
- 退回收到联动:标记运单 is_back、完结拦截工单、订单退回状态、操作记录
- 新增权限 527/528/529 + 菜单 530,授权仓库/客服角色
- 解除拦截不再清除 is_back(由退回收货流程单独管理)
- 同步 API 文档、method 路由速查
This commit is contained in:
liufumingren 2026-08-13 01:58:55 +08:00
parent c84d5ac4ae
commit f4ed985556
12 changed files with 1375 additions and 11 deletions

View File

@ -161,6 +161,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods
- send, sendToComputer, log
- app/service/systemMethods/printer/station.js (1)
- list
- app/service/systemMethods/returnReceived.js (4)
- create, list, detail, delete
- app/service/systemMethods/setting/printTemplate.js (3)
- list, save, listTemplatesByType
- app/service/systemMethods/stock.js (21)
@ -207,6 +209,8 @@ rg "class .*Service|module.exports" app/service/qimenMethods
- sendToComputer, test
- app/service/systems/qimen_query.js (6)
- send, replaceXmlTagsWithString, addSign, getQueryParams, generateUrlWithParams, sendRequest
- app/service/systems/return_received.js (12)
- create, list, detail, delete, createBusinessError, _findByIdChecked, _enrichReturn, _resolveStoreRemark, _buildListWhere, _resolveConditionValue, _extractConditionValue, _buildListOrder
- app/service/systems/setting/print_template.js (14)
- listTemplatesByType, getTree, getTemplatesByType, save, getBusinessTypesAndItem, getGroupedPrintItems, getTableConfigs, clearBusinessTypesCache, getXmlByTemplate, buildXmlFromElements, renderElement, computeItemStyle, computeTableItemStyle, renderTable
- app/service/systems/sign.js (10)

View File

@ -90,6 +90,7 @@ module.exports = {
ORDER_EXPRESS_ALLOCATE_FAILED: '分配快递失败',
ORDER_INTERCEPT_REQUEST: '请求订单拦截',
ORDER_INTERCEPT_CANCEL: '解除订单拦截',
ORDER_RETURN_RECEIVED: '退回收到',
ORDER_LOCK: '订单锁定',
ORDER_UNLOCK: '订单解锁',

View File

@ -0,0 +1,100 @@
'use strict';
/**
* 退回收到登记表模型。
* @param {import('egg').Application} app Egg 应用实例。
* @return {import('sequelize').ModelCtor<import('sequelize').Model>} Sequelize 模型。
*/
module.exports = app => {
const { BIGINT, STRING, DATE } = app.Sequelize;
const ReturnReceived = app.model.define('wms_return_received', {
id: {
type: BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
comment: '主键ID',
},
warehouse_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '仓库ID(数据隔离维度)',
},
waybill_code: {
type: STRING(50),
allowNull: false,
comment: '退回收件运单号(扫描到的退回包裹单号)',
},
scan_date: {
type: DATE,
allowNull: false,
comment: '扫描收到日期',
},
scanner_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '扫描人员工号ID,关联 wms_account_store_employee.id(employees_id)',
},
scanner_name: {
type: STRING(50),
allowNull: false,
comment: '扫描人员工号名称快照(employees_name / real_name)',
},
order_express_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '运单表关联字段,关联 wms_order_express.id;原单退回时回填,非原单退回/非本仓库件时为空',
},
order_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '订单ID,方便快速匹配;非原单退回时为空',
},
store_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '货主ID,原单退回时回填,用于查货主备注 wms_store_warehouse.store_remask',
},
remark: {
type: STRING(500),
allowNull: true,
comment: '备注',
},
}, {
tableName: 'wms_return_received',
comment: '退回收到登记表',
timestamps: true,
createdAt: 'created_at',
updatedAt: 'updated_at',
paranoid: false,
indexes: [
{ name: 'idx_warehouse_waybill_scan_date', fields: [ 'warehouse_id', 'waybill_code', 'scan_date' ] },
{ name: 'idx_warehouse_scan_date', fields: [ 'warehouse_id', 'scan_date' ] },
{ name: 'idx_scanner_id', fields: [ 'scanner_id' ] },
{ name: 'idx_order_express_id', fields: [ 'order_express_id' ] },
{ name: 'idx_store_id', fields: [ 'store_id' ] },
],
});
// 关联定义
ReturnReceived.associate = function() {
const { Store, AccountStoreEmployee, OrderExpress } = app.model;
// 关联仓库(wms_store 主体表)
ReturnReceived.belongsTo(Store, {
foreignKey: 'warehouse_id',
as: 'warehouse',
});
// 关联扫描人员工号
ReturnReceived.belongsTo(AccountStoreEmployee, {
foreignKey: 'scanner_id',
as: 'scanner',
});
// 关联原运单
ReturnReceived.belongsTo(OrderExpress, {
foreignKey: 'order_express_id',
as: 'orderExpress',
});
};
return ReturnReceived;
};

View File

@ -5673,15 +5673,15 @@ class PendingOrderService extends OrderBaseService {
},
});
// 同步清除运单表拦截+退回标记
// 同步清除运单表拦截标记(退回收到标记 is_back 保持不变,由退回收货流程单独管理)
try {
await ctx.model.OrderExpress.update(
{ is_intercept: 'N', is_back: 'N' },
{ is_intercept: 'N' },
{ where: { order_id: { [Op.in]: chunkOrderIds }, warehouse_id: warehouseId } }
);
} catch (expressErr) {
ctx.logger.warn(
`[order.pendingOrder.batchUnintercept] 清除运单标记失败, count=${chunkOrderIds.length}, error=${expressErr.message}`
`[order.pendingOrder.batchUnintercept] 清除运单拦截标记失败, count=${chunkOrderIds.length}, error=${expressErr.message}`
);
}

View File

@ -3613,7 +3613,7 @@ class RecheckOrderService extends OrderBaseService {
throw new Error('拦截状态更新失败,请稍后重试');
}
// 同步更新运单表:标记拦截 + 退回
// 同步更新运单表:标记拦截 + 退回(库内拦截确认,货物在库内需退回)
try {
await ctx.model.OrderExpress.update(
{ is_intercept: 'Y', is_back: 'Y' },
@ -3697,18 +3697,20 @@ class RecheckOrderService extends OrderBaseService {
}
/**
* 拦截扫描:通过运单号查找运单记录,标记退回并处理关联工单与订单拦截状态。
* 拦截扫描:通过运单号查找运单记录,标记退回与拦截并处理关联工单与订单拦截状态。
*
* 处理流程:
* 1. 根据运单号查询 wms_order_express,找到则将 is_back 设为 'Y';未找到则创建新记录补充缺失快递
* 1. 根据运单号查询 wms_order_express,找到则将 is_back、is_intercept 设为 'Y';未找到则创建新记录补充缺失快递
* 2. 检查是否存在关联的未完结售后工单(wms_after_sale),若有则调用 handleWorkOrder 写入
* "库内拦截成功"步骤并将工单置为 completed
* 3. 同步更新 wms_order_delivery 的 intercept_status 为 intercepted_at_warehouse,
* 并释放储位分配与订单锁(与 confirmIntercept 行为一致,订单级拦截覆盖所有面单含子面单)
*
* 注:库内拦截确认需标记退回 is_back='Y';发起拦截链路仅写 is_intercept,不写 is_back。
*
* @param {Object} data 请求体。
* @param {string} data.waybill_code 运单号。
* @return {Promise<Object>} 拦截扫描结果,包含 waybill_code、is_back、after_sale(若有)、order。
* @return {Promise<Object>} 拦截扫描结果,包含 waybill_code、is_back、is_intercept、after_sale(若有)、order。
*/
async interceptScan(data = {}) {
const { ctx, service } = this;
@ -3728,7 +3730,7 @@ class RecheckOrderService extends OrderBaseService {
raw: true,
});
// 1a. 缺失快递补充:运单记录不存在则创建新记录
// 1a. 缺失快递补充:运单记录不存在则创建新记录(库内拦截确认需标记退回)
if (!expressRecord) {
const created = await ctx.model.OrderExpress.create({
waybill_code: normalizedWaybillCode,
@ -3741,7 +3743,7 @@ class RecheckOrderService extends OrderBaseService {
expressRecord = (created && created.toJSON ? created.toJSON() : created) || {};
} else {
// 2. 标记退回
// 2. 标记退回 + 拦截
await ctx.model.OrderExpress.update(
{ is_back: 'Y', is_intercept: 'Y' },
{ where: { id: expressRecord.id } }

View File

@ -0,0 +1,107 @@
'use strict';
const MainService = require('../main');
/**
* 系统方法层:returnReceived(退回收到模块接口包装层)。
* 主要职责:统一包装系统方法接口,处理权限、where 解析等公共逻辑,
* 将具体业务逻辑下沉到 systems.return_received 中。
*/
class ReturnReceivedMethodService extends MainService {
constructor(ctx) {
super(ctx);
// 免登录方法列表:空(全部需要登录)
const _noNeedLogin = '';
// 免权限方法列表:detail 复用列表权限(仅登录 + 仓库隔离校验),其余走 API 权限校验
const _noNeedRight = 'detail';
// 免日志方法列表:空(全部记录日志)
const _noNeedLog = '';
// 免鉴权(仓库有效期检查)方法列表:空(全部检查有效期)
const _noNeedAuth = '';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 统一调用退回收到业务服务,并捕获业务错误码。
*
* @param {Function} fn 业务调用函数。
* @param {string} fallbackMessage 兜底错误文案。
* @return {Promise<Object>} 统一 success/fail 包装。
*/
async _call(fn, fallbackMessage) {
try {
const result = await fn();
return this.success('ok', result);
} catch (error) {
const code = Number(error && error.code);
if (Number.isInteger(code) && code >= 400 && code < 600) {
return this.fail(error.message || fallbackMessage, {}, code);
}
this.ctx.logger.error(`[returnReceived] ${fallbackMessage}: ${error && error.message ? error.message : error}`);
return this.fail('服务器内部错误', {}, 500);
}
}
/**
* 扫码登记退回包裹(增)。
*
* @param {Object} data 请求体。
* @param {string} data.waybill_code 退回收件运单号。
* @param {string} [data.remark] 备注。
* @return {Promise<Object>} 统一 success 包装。
*/
async create(data = {}) {
const { waybill_code, remark } = data;
return this._call(() => this.service.systems.returnReceived.create({ waybill_code, remark }), '扫码登记失败');
}
/**
* 分页查询退回收到登记列表(查,仓库隔离自动注入)。
*
* @param {Object} data 请求体。
* @param {Object} [data.pagination] 分页参数。
* @param {Object} [data.where] 筛选条件。
* @param {Object} [data.sort] 排序参数。
* @return {Promise<Object>} 统一 success 包装。
*/
async list(data = {}) {
const { service } = this;
const { pagination, 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 };
}
return this._call(() => service.systems.returnReceived.list(enforcedWhere, pagination, sort), '查询列表失败');
}
/**
* 查询单条退回收到登记详情(查)。
*
* @param {Object} data 请求体。
* @param {number} data.id 登记记录主键ID。
* @return {Promise<Object>} 统一 success 包装。
*/
async detail(data = {}) {
const { id } = data;
return this._call(() => this.service.systems.returnReceived.detail(Number(id)), '查询详情失败');
}
/**
* 删除单条退回收到登记记录(删)。
*
* @param {Object} data 请求体。
* @param {number} data.id 登记记录主键ID。
* @return {Promise<Object>} 统一 success 包装。
*/
async delete(data = {}) {
const { id } = data;
return this._call(() => this.service.systems.returnReceived.delete(Number(id)), '删除失败');
}
}
module.exports = ReturnReceivedMethodService;

View File

@ -0,0 +1,551 @@
'use strict';
const Service = require('egg').Service;
/**
* 退回收到模块业务逻辑层。
* 负责 wms_return_received 的增删查,以及原单反查、货主备注、30 日幂等等核心操作。
* 所有数据库交互集中在此层,供 systemMethods/returnReceived.js 调用。
*/
class ReturnReceivedService extends Service {
/**
* 创建带业务错误码的异常对象。
* @param {string} message 错误信息。
* @param {number} [code=400] 业务错误码。
* @return {Error} 包含 code 的异常对象。
*/
createBusinessError(message, code = 400) {
const error = new Error(`${message}`);
error.code = code;
return error;
}
/**
* 扫码登记退回包裹(30 日内同仓库同单号只写一次,以第一次为准)。
* 反查原运单判定是否原单退回,命中则回填关联字段并同步标记 is_back='Y'。
*
* @param {Object} params 登记参数。
* @param {string} params.waybill_code 退回收件运单号。
* @param {string} [params.remark] 备注。
* @return {Promise<Object>} 登记结果,含 record、is_original_return、store_remark、duplicated。
*/
async create({ waybill_code, remark }) {
const { ctx, app } = this;
const { Op } = app.Sequelize;
const waybillCode = String(waybill_code || '').trim();
if (!waybillCode) {
throw this.createBusinessError('waybill_code 不能为空', 400);
}
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
if (!Number.isFinite(warehouseId) || warehouseId <= 0) {
throw this.createBusinessError('缺少仓库上下文', 400);
}
const scannerId = ctx.user && ctx.user.employees_id ? Number(ctx.user.employees_id) : 0;
const scannerName = String(
(ctx.user && ctx.user.employees_name) || (ctx.user && ctx.user.real_name) || ''
).trim();
if (!Number.isFinite(scannerId) || scannerId <= 0) {
throw this.createBusinessError('缺少扫描人员工号上下文', 400);
}
// 30 日幂等窗口:同仓库 + 同单号,扫描日期在最近 30 天内则视为重复
const now = new Date();
const thirtyDaysAgo = new Date(now.getTime());
thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
const scanDate = app.formatDate(now, 'YYYY-MM-DD');
const windowStart = app.formatDate(thirtyDaysAgo, 'YYYY-MM-DD');
const existing = await ctx.model.ReturnReceived.findOne({
where: {
warehouse_id: warehouseId,
waybill_code: waybillCode,
scan_date: { [Op.gte]: windowStart },
},
order: [[ 'id', 'ASC' ]],
raw: true,
});
if (existing) {
const enriched = await this._enrichReturn(existing);
return { ...enriched, duplicated: true };
}
// 反查原运单,判定是否原单退回
let orderExpressId = null;
let orderId = null;
let storeId = null;
try {
const orderExpress = await ctx.model.OrderExpress.findOne({
where: { waybill_code: waybillCode },
attributes: [ 'id', 'order_id', 'store_id' ],
raw: true,
});
if (orderExpress) {
orderExpressId = orderExpress.id;
orderId = orderExpress.order_id;
storeId = orderExpress.store_id;
}
} catch (err) {
ctx.logger.warn(`[returnReceived.create] 反查原运单失败: ${err.message}`);
}
const created = await ctx.model.ReturnReceived.create({
warehouse_id: warehouseId,
waybill_code: waybillCode,
scan_date: scanDate,
scanner_id: scannerId,
scanner_name: scannerName || '未命名',
order_express_id: orderExpressId,
order_id: orderId,
store_id: storeId,
remark: remark ? String(remark).slice(0, 500) : null,
});
// 原单退回:同步标记 wms_order_express.is_back = 'Y'
if (orderExpressId) {
try {
await ctx.model.OrderExpress.update(
{ is_back: 'Y' },
{ where: { id: orderExpressId } }
);
} catch (err) {
ctx.logger.warn(`[returnReceived.create] 更新运单退回标记失败: ${err.message}`);
}
}
// 原单退回:处理关联拦截工单 + 更新订单拦截状态(参考库内拦截,不处理库存信息)
if (orderExpressId) {
await this._handleInterceptAfterSale(waybillCode, warehouseId, scannerId, scannerName);
if (orderId) {
await this._updateOrderInterceptStatus(orderId, warehouseId, scannerId, scannerName);
}
}
const createdRow = created && typeof created.toJSON === 'function' ? created.toJSON() : created;
const enriched = await this._enrichReturn(createdRow);
return { ...enriched, duplicated: false };
}
/**
* 处理退回运单关联的未完结拦截工单(写入「退回包裹已收到」并完结)。
* 仅更新工单状态,不处理库存信息(参考库内拦截 interceptScan 的工单处理部分)。
*
* @param {string} waybillCode 退回收件运单号。
* @param {number} warehouseId 仓库ID。
* @param {number} operatorId 操作人工号ID。
* @param {string} operatorName 操作人工号名称。
* @return {Promise<void>} 无返回值。
*/
async _handleInterceptAfterSale(waybillCode, warehouseId, operatorId, operatorName) {
const { ctx } = this;
const { Op } = ctx.app.Sequelize;
try {
const afterSale = await ctx.model.AfterSale.findOne({
where: {
waybill_no: waybillCode,
warehouse_id: warehouseId,
type: 'order',
sub_type: 'intercept',
deleted_at: null,
status: { [Op.notIn]: [ 'completed', 'closed', 'cancelled' ] },
},
order: [[ 'id', 'DESC' ]],
raw: true,
});
if (!afterSale) {
return;
}
const operatorSnapshot = JSON.stringify({
id: String(operatorId || ''),
name: String(operatorName || ''),
});
await ctx.service.systems.afterSale.handleWorkOrder({
id: afterSale.id,
remark: '退回包裹已收到',
targetStatus: 'completed',
resolution: '退回包裹已收到',
attachmentIds: [],
operatorId: Number(operatorId) || 0,
operatorSnapshot,
warehouseId,
});
} catch (err) {
ctx.logger.warn(`[returnReceived._handleInterceptAfterSale] 处理拦截工单失败, waybill=${waybillCode}, error=${err.message}`);
}
}
/**
* 更新退回运单关联订单的退回状态并写入操作记录(不处理库存信息)。
* - current 表(待处理):设置 intercept_status='returned'、step=4、outbound_status='fin' 触发自动转配送表;
* - dispatch 表(配送中):仅更新 intercept_status='returned';
* - 不释放储位分配、不释放订单锁。
* 兼容 current/dispatch 分表:先查 current 表,不存在再查 dispatch 表。
*
* @param {number} orderId 订单ID。
* @param {number} warehouseId 仓库ID。
* @param {number} operatorId 操作人工号ID。
* @param {string} operatorName 操作人工号名称。
* @return {Promise<void>} 无返回值。
*/
async _updateOrderInterceptStatus(orderId, warehouseId, operatorId, operatorName) {
const { ctx } = this;
try {
const factory = ctx.model && ctx.model.OrderDeliveryFactory;
if (!factory || typeof factory.getCurrentModel !== 'function') {
return;
}
const where = { id: orderId, warehouse_id: warehouseId };
const orderAttributes = [ 'id', 'delivery_order_code', 'pre_delivery_order_code', 'intercept_status' ];
// 先查 current 表;不存在再查 dispatch 表
let orderModel = await factory.getCurrentModel(warehouseId);
let order = orderModel && typeof orderModel.findOne === 'function'
? await orderModel.findOne({ where, attributes: orderAttributes, raw: true })
: null;
const isCurrentTable = Boolean(order);
if (!order && typeof factory.getDispatchModel === 'function') {
orderModel = await factory.getDispatchModel(warehouseId);
order = orderModel && typeof orderModel.findOne === 'function'
? await orderModel.findOne({ where, attributes: orderAttributes, raw: true })
: null;
}
if (!order || !orderModel || typeof orderModel.update !== 'function') {
return;
}
const updateFields = {
intercept_status: 'returned',
updated_at: new Date(),
};
// 待处理表(current):设置 step=4 + outbound_status='fin' 触发自动转配送表
if (isCurrentTable) {
updateFields.step = 4;
updateFields.outbound_status = 'fin';
}
await orderModel.update(updateFields, { where });
// 写入订单操作记录
const orderNo = String(order.delivery_order_code || order.pre_delivery_order_code || '').trim();
try {
await ctx.service.systems.operationLog.createOperationLog({
businessType: 'order',
businessId: warehouseId,
operationCode: 'ORDER_RETURN_RECEIVED',
operator: { id: String(operatorId || ''), name: String(operatorName || '') },
extras: {
warehouseId,
orderId,
orderNo,
previousInterceptStatus: String(order.intercept_status || '').trim(),
newInterceptStatus: 'returned',
},
beforeChanges: null,
});
} catch (logErr) {
ctx.logger.warn(`[returnReceived._updateOrderInterceptStatus] 写入订单操作日志失败, orderId=${orderId}, error=${logErr.message}`);
}
} catch (err) {
ctx.logger.warn(`[returnReceived._updateOrderInterceptStatus] 更新订单退回状态失败, orderId=${orderId}, error=${err.message}`);
}
}
/**
* 分页查询退回收到登记列表(仓库隔离由方法层注入 warehouse_id)。
*
* @param {Object} where 标准化 where 条件对象。
* @param {Object} [pagination] 分页参数。
* @param {number} [pagination.page=1] 页码。
* @param {number} [pagination.pageSize=20] 每页数量。
* @param {Object} [sort] 排序参数。
* @param {string} [sort.sortField] 排序字段。
* @param {string} [sort.sortOrder] 排序顺序(asc/desc)。
* @return {Promise<Object>} { list: Array, pagination: Object }。
*/
async list(where = {}, pagination = {}, sort = {}) {
const { ctx, app } = this;
const { Op } = app.Sequelize;
const page = Math.max(1, parseInt(pagination.page) || 1);
const pageSize = Math.min(500, Math.max(1, parseInt(pagination.pageSize) || 20));
const queryWhere = this._buildListWhere(where, Op);
const order = this._buildListOrder(sort);
const { count, rows } = await ctx.model.ReturnReceived.findAndCountAll({
where: queryWhere,
order,
offset: (page - 1) * pageSize,
limit: pageSize,
raw: true,
});
const list = [];
for (const row of rows) {
list.push(await this._enrichReturn(row));
}
return {
list,
pagination: {
page,
pageSize,
total: count,
totalPages: Math.ceil(count / pageSize),
hasPrevious: page > 1,
hasNext: page * pageSize < count,
},
};
}
/**
* 查询单条退回收到登记详情(含原运单与货主合约备注)。
*
* @param {number} id 登记记录主键ID。
* @return {Promise<Object>} { record, order_express, store_contract }。
*/
async detail(id) {
const { ctx } = this;
const record = await this._findByIdChecked(id);
const enriched = await this._enrichReturn(record);
const orderExpress = record.order_express_id
? await ctx.model.OrderExpress.findOne({
where: { id: record.order_express_id },
attributes: [
'id', 'waybill_code', 'order_id', 'store_id', 'warehouse_id',
'is_back', 'is_intercept', 'logistics_name', 'logistics_code',
],
raw: true,
})
: null;
const storeContract = record.store_id
? await ctx.model.StoreWarehouse.findOne({
where: { store_id: record.store_id, warehouse_id: record.warehouse_id },
attributes: [
'id', 'store_id', 'warehouse_id', 'store_remask', 'warehouse_remask',
'store_use_status', 'warehouse_use_status',
],
raw: true,
})
: null;
return {
record: enriched,
order_express: orderExpress,
store_contract: storeContract,
};
}
/**
* 删除单条退回收到登记记录(物理删除)。
*
* @param {number} id 登记记录主键ID。
* @return {Promise<Object>} 删除结果,含被删除记录 id。
*/
async delete(id) {
const { ctx } = this;
const record = await this._findByIdChecked(id);
await ctx.model.ReturnReceived.destroy({ where: { id: record.id } });
return { id: record.id };
}
/**
* 按主键查询登记记录,并校验仓库隔离。
*
* @param {number} id 登记记录主键ID。
* @return {Promise<Object>} 登记记录原始数据。
*/
async _findByIdChecked(id) {
const { ctx } = this;
const normalizedId = Number(id || 0);
if (!Number.isFinite(normalizedId) || normalizedId <= 0) {
throw this.createBusinessError('id 必填且必须为正整数', 400);
}
const record = await ctx.model.ReturnReceived.findOne({
where: { id: normalizedId },
raw: true,
});
if (!record) {
throw this.createBusinessError('登记记录不存在', 404);
}
const warehouseId = Number(ctx.user && ctx.user.store_id || 0);
if (warehouseId > 0 && Number(record.warehouse_id) !== warehouseId) {
throw this.createBusinessError('无权访问该登记记录', 403);
}
return record;
}
/**
* 组装登记记录展示字段(是否原单退回、货主备注、时间格式化)。
*
* @param {Object} row 登记记录原始数据。
* @return {Promise<Object>} 组装后的记录。
*/
async _enrichReturn(row) {
const { app } = this;
const record = { ...row };
record.is_original_return = Boolean(record.order_express_id);
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;
record.updated_at = record.updated_at ? app.formatDate(record.updated_at) : null;
return record;
}
/**
* 查询货主合约备注名称(wms_store_warehouse.store_remask)。
*
* @param {Object} record 登记记录。
* @return {Promise<string>} 货主备注名称,无货主或未命中时返回空字符串。
*/
async _resolveStoreRemark(record) {
const { ctx } = this;
const storeId = Number(record && record.store_id || 0);
const warehouseId = Number(record && record.warehouse_id || 0);
if (!storeId || !warehouseId) {
return '';
}
try {
const sw = await ctx.model.StoreWarehouse.findOne({
where: { store_id: storeId, warehouse_id: warehouseId },
attributes: [ 'store_remask' ],
raw: true,
});
return (sw && sw.store_remask) || '';
} catch (err) {
ctx.logger.warn(`[returnReceived._resolveStoreRemark] 查询货主备注失败: ${err.message}`);
return '';
}
}
/**
* 根据标准化 where 条件构建 Sequelize 查询条件。
*
* @param {Object} where 标准化 where 条件对象。
* @param {Object} Op Sequelize Op 对象。
* @return {Object} Sequelize where 条件。
*/
_buildListWhere(where = {}, Op) {
const queryWhere = {};
const directFields = [
'warehouse_id', 'scanner_id', 'store_id', 'order_express_id', 'order_id',
'waybill_code', 'scan_date', 'scanner_name',
];
for (const field of directFields) {
if (where[field] !== undefined && where[field] !== null) {
queryWhere[field] = this._resolveConditionValue(where[field], Op);
}
}
// 是否原单退回(派生字段):true=有关联运单,false=无关联
if (where.is_original_return !== undefined && where.is_original_return !== null) {
const flag = this._extractConditionValue(where.is_original_return);
if (flag === true || flag === 1 || flag === '1' || flag === 'true') {
queryWhere.order_express_id = { [Op.ne]: null };
} else {
queryWhere.order_express_id = null;
}
}
return queryWhere;
}
/**
* 解析标准化条件值为 Sequelize 可用的条件对象。
*
* @param {*} condition 标准化条件(可能是 {operator, value} 或直接值)。
* @param {Object} Op Sequelize Op 对象。
* @return {*} Sequelize 条件。
*/
_resolveConditionValue(condition, Op) {
if (condition && typeof condition === 'object' && !Array.isArray(condition)) {
const operator = condition.operator;
const value = condition.value;
if (!operator) {
return value;
}
switch (operator) {
case 'eq':
return value;
case 'ne':
return { [Op.ne]: value };
case 'in':
return { [Op.in]: Array.isArray(value) ? value : [ value ] };
case 'notin':
return { [Op.notIn]: Array.isArray(value) ? value : [ value ] };
case 'like':
return { [Op.like]: `%${value}%` };
case 'gt':
return { [Op.gt]: value };
case 'gte':
return { [Op.gte]: value };
case 'lt':
return { [Op.lt]: value };
case 'lte':
return { [Op.lte]: value };
case 'between':
return { [Op.between]: Array.isArray(value) ? value : [ value ] };
default:
return value;
}
}
return condition;
}
/**
* 从条件对象中提取原始 value。
*
* @param {*} condition 标准化条件。
* @return {*} 原始值。
*/
_extractConditionValue(condition) {
if (condition && typeof condition === 'object' && !Array.isArray(condition)) {
if ('value' in condition) {
return condition.value;
}
}
return condition;
}
/**
* 根据 sort 参数构建 Sequelize 排序数组。
*
* @param {Object} sort 排序参数。
* @return {Array<Array<string>>} Sequelize order 数组。
*/
_buildListOrder(sort = {}) {
const sortField = sort.sortField || sort.sort_field || 'created_at';
const sortOrderRaw = (sort.sortOrder || sort.sort_order || 'desc').toLowerCase();
const sortOrder = sortOrderRaw === 'asc' ? 'ASC' : 'DESC';
const allowedSortFields = new Set([ 'id', 'scan_date', 'created_at', 'updated_at', 'waybill_code' ]);
const safeSortField = allowedSortFields.has(sortField) ? sortField : 'created_at';
return [[ safeSortField, sortOrder ]];
}
}
module.exports = ReturnReceivedService;

View File

@ -0,0 +1,87 @@
'use strict';
/**
* 创建退回收到登记表 wms_return_received。
*
* 字段:仓库隔离 warehouse_id、退回收件运单号 waybill_code、扫描日期 scan_date、
* 扫描人员 scanner_id/scanner_name、运单关联 order_express_id/order_id/store_id(非必填)。
*
* 索引:
* idx_warehouse_waybill_scan_date(30 日幂等查询)
* idx_warehouse_scan_date(仓库+日期隔离查询)
* idx_scanner_id / idx_order_express_id / idx_store_id
*/
module.exports = {
// eslint-disable-next-line no-unused-vars
async up(queryInterface, Sequelize) {
const { BIGINT, STRING, DATE } = Sequelize;
await queryInterface.createTable('wms_return_received', {
id: {
type: BIGINT(20).UNSIGNED,
primaryKey: true,
autoIncrement: true,
allowNull: false,
comment: '主键ID',
},
warehouse_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '仓库ID(数据隔离维度)',
},
waybill_code: {
type: STRING(50),
allowNull: false,
comment: '退回收件运单号(扫描到的退回包裹单号)',
},
scan_date: {
type: DATE,
allowNull: false,
comment: '扫描收到日期',
},
scanner_id: {
type: BIGINT(20).UNSIGNED,
allowNull: false,
comment: '扫描人员工号ID(employees_id)',
},
scanner_name: {
type: STRING(50),
allowNull: false,
comment: '扫描人员工号名称快照(employees_name / real_name)',
},
order_express_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '运单表关联字段,关联 wms_order_express.id;非必填',
},
order_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '订单ID,方便快速匹配;非必填',
},
store_id: {
type: BIGINT(20).UNSIGNED,
allowNull: true,
comment: '货主ID,原单退回时回填,用于查货主备注',
},
remark: {
type: STRING(500),
allowNull: true,
comment: '备注',
},
created_at: { type: DATE, allowNull: false },
updated_at: { type: DATE, allowNull: false },
});
await queryInterface.addIndex('wms_return_received', [ 'warehouse_id', 'waybill_code', 'scan_date' ], { name: 'idx_warehouse_waybill_scan_date' });
await queryInterface.addIndex('wms_return_received', [ 'warehouse_id', 'scan_date' ], { name: 'idx_warehouse_scan_date' });
await queryInterface.addIndex('wms_return_received', [ 'scanner_id' ], { name: 'idx_scanner_id' });
await queryInterface.addIndex('wms_return_received', [ 'order_express_id' ], { name: 'idx_order_express_id' });
await queryInterface.addIndex('wms_return_received', [ 'store_id' ], { name: 'idx_store_id' });
},
// eslint-disable-next-line no-unused-vars
async down(queryInterface, Sequelize) {
await queryInterface.dropTable('wms_return_received');
},
};

View File

@ -0,0 +1,98 @@
'use strict';
/**
* 退回收到模块权限记录 + 角色授权迁移。
*
* 权限明细(固定 ID):
* 527 — returnReceived.create API:退回收件扫码登记
* 528 — returnReceived.list API:退回收件列表查询
* 529 — returnReceived.delete API:退回收件删除
*
* 角色授权(系统预设角色,不含通配符角色):
* 527(扫码登记)→ 仓库组-员工(27) → 仓库组-主管(26)(仓库员工及以上)
* 528(列表)、529(删除)→ 客服组-员工(30) → 客服组-主管(28)(客服员工及以上)
* 经理(8)/仓库管理员(2)/超级管理员(7) 已持有 * 通配符,自动拥有所有权限,无需处理
*
* 幂等:INSERT IGNORE 创建权限记录;角色权限数组追加后去重排序,已存在跳过。
*/
const TABLE = 'wms_permission';
const ROLE_TABLE = 'wms_role';
const COLUMNS = 'id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at';
/** 权限ID → 授权角色ID列表(不含通配符角色) */
const PERMISSION_ROLES = {
527: [ 27, 26 ],
528: [ 30, 28 ],
529: [ 30, 28 ],
};
module.exports = {
// eslint-disable-next-line no-unused-vars
async up(queryInterface, Sequelize) {
// ── 1. 创建 API 权限记录(固定 ID)──
const apis = [
[ 527, 'returnReceived.create', 'API:退回收件扫码登记' ],
[ 528, 'returnReceived.list', 'API:退回收件列表查询' ],
[ 529, 'returnReceived.delete', 'API:退回收件删除' ],
];
for (const [ id, path, metaTitle ] of apis) {
await queryInterface.sequelize.query(
`INSERT IGNORE INTO \`${TABLE}\` (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW(), NOW())`,
{ replacements: [ id, path, null, path, null, metaTitle, null, 0, 0, null, 'api', 0, 1 ] }
);
}
// ── 2. 角色授权注入 ──
for (const permId of Object.keys(PERMISSION_ROLES).map(Number)) {
for (const roleId of PERMISSION_ROLES[permId]) {
const rows = await queryInterface.sequelize.query(
`SELECT id, permissions FROM \`${ROLE_TABLE}\` WHERE id = ?`,
{ replacements: [ roleId ], type: queryInterface.sequelize.QueryTypes.SELECT }
);
const record = Array.isArray(rows) ? rows[0] : null;
if (!record) {
continue;
}
// 通配符角色跳过
if (record.permissions === '*') {
continue;
}
let perms;
try {
perms = JSON.parse(record.permissions || '[]');
} catch (err) {
continue;
}
if (!Array.isArray(perms)) {
continue;
}
if (perms.includes(permId)) {
continue;
}
perms.push(permId);
perms.sort((a, b) => a - b);
await queryInterface.sequelize.query(
`UPDATE \`${ROLE_TABLE}\` SET permissions = ? WHERE id = ?`,
{ replacements: [ JSON.stringify(perms), roleId ] }
);
}
}
},
// eslint-disable-next-line no-unused-vars
async down(queryInterface, Sequelize) {
const ids = [ 527, 528, 529 ];
const placeholders = ids.map(() => '?').join(', ');
await queryInterface.sequelize.query(
`DELETE FROM \`${TABLE}\` WHERE id IN (${placeholders})`,
{ replacements: ids }
);
},
};

View File

@ -0,0 +1,82 @@
'use strict';
/**
* 快递菜单下新增 web_pages 子菜单「快递收件」(id=530),并授权客服员工及以上角色。
*
* 权限明细:
* 530 — returnReceived(web_pages 菜单,parent_id=19 快递/物流)
*
* 角色授权(系统预设角色,不含通配符角色):
* 530 → 客服组-员工(30) → 客服组-主管(28)(客服员工及以上)
* 经理(8)/仓库管理员(2)/超级管理员(7) 已持有 * 通配符,自动拥有所有权限,无需处理
*
* 幂等:INSERT IGNORE 创建菜单权限;角色权限数组追加后去重排序,已存在跳过。
*/
const TABLE = 'wms_permission';
const ROLE_TABLE = 'wms_role';
const COLUMNS = 'id, path, component, name, redirect, meta_title, meta_icon, hidden, always_show, parent_id, type, sort, status, created_at, update_at';
/** 权限ID → 授权角色ID列表(不含通配符角色) */
const PERMISSION_ROLES = {
530: [ 30, 28 ],
};
module.exports = {
// eslint-disable-next-line no-unused-vars
async up(queryInterface, Sequelize) {
// ── 1. 创建 web_pages 菜单权限(固定 ID,parent_id=19 快递/物流)──
await queryInterface.sequelize.query(
`INSERT IGNORE INTO \`${TABLE}\` (${COLUMNS}) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NOW(), NOW())`,
{ replacements: [ 530, 'returnReceived', '@/views/express/returnReceived/index', 'returnReceived', null, '快递收件', null, 0, 0, 19, 'web_pages', 1, 1 ] }
);
// ── 2. 角色授权注入 ──
for (const permId of Object.keys(PERMISSION_ROLES).map(Number)) {
for (const roleId of PERMISSION_ROLES[permId]) {
const rows = await queryInterface.sequelize.query(
`SELECT id, permissions FROM \`${ROLE_TABLE}\` WHERE id = ?`,
{ replacements: [ roleId ], type: queryInterface.sequelize.QueryTypes.SELECT }
);
const record = Array.isArray(rows) ? rows[0] : null;
if (!record) {
continue;
}
// 通配符角色跳过
if (record.permissions === '*') {
continue;
}
let perms;
try {
perms = JSON.parse(record.permissions || '[]');
} catch (err) {
continue;
}
if (!Array.isArray(perms)) {
continue;
}
if (perms.includes(permId)) {
continue;
}
perms.push(permId);
perms.sort((a, b) => a - b);
await queryInterface.sequelize.query(
`UPDATE \`${ROLE_TABLE}\` SET permissions = ? WHERE id = ?`,
{ replacements: [ JSON.stringify(perms), roleId ] }
);
}
}
},
// eslint-disable-next-line no-unused-vars
async down(queryInterface, Sequelize) {
await queryInterface.sequelize.query(
`DELETE FROM \`${TABLE}\` WHERE id = 530`
);
},
};

View File

@ -5753,5 +5753,27 @@
"subType 枚举由 GROUP_TYPES 统一定义,与 AI 函数分组同源",
"后端已新增两层类型校验:subType 必须在对应 groupType 的合法子类型列表中"
]
},
{
"version": "2026.08.13-returnReceived",
"date": "2026-08-13",
"type": "added",
"summary": "新增退回收到模块(returnReceived):退回包裹扫码登记、分页列表、详情、删除四个接口。扫码登记30日内同仓库同单号幂等(以第一次为准),反查原运单判定是否原单退回并同步标记 is_back='Y';列表/详情/删除仓库隔离。配套权限 527/528/529(扫码登记→仓库员工及以上,列表/删除→客服员工及以上)",
"methods": [
"returnReceived.create",
"returnReceived.list",
"returnReceived.detail",
"returnReceived.delete"
],
"notes": [
"新增表 wms_return_received(仓库隔离 warehouse_id、退回收件单号 waybill_code、扫描日期 scan_date、扫描人员 scanner_id/scanner_name、运单关联 order_express_id/order_id/store_id 非必填)",
"returnReceived.create:30日幂等 + 反查 wms_order_express.waybill_code,命中回填关联字段并同步 is_back='Y',返回 is_original_return/store_remark/duplicated",
"returnReceived.list:分页列表,仓库隔离由服务端注入 warehouse_id,支持运单号/日期/扫描人员/货主/是否原单退回筛选",
"returnReceived.detail:详情含原运单与货主合约备注,免权限但需登录+仓库隔离",
"returnReceived.delete:物理删除,需权限+仓库隔离",
"权限:527 returnReceived.create(仓库员工及以上)、528 returnReceived.list、529 returnReceived.delete(客服员工及以上);detail 复用 list 权限",
"代码变更:app/model/return_received.js、app/service/systems/return_received.js、app/service/systemMethods/returnReceived.js、database/migrations/20260812160000-create-wms-return-received.js、20260813100000-create-return-received-permissions.js"
],
"module": "returnReceived"
}
]

View File

@ -1,8 +1,8 @@
{
"module": "system",
"description": "系统接口标准入口,method 对应系统内置方法,全部使用 POST 请求,参数统一放在 body 内",
"version": "0.3.21",
"updatedAt": "2026-08-11",
"version": "0.3.22",
"updatedAt": "2026-08-13",
"headers": [
{
"name": "platform",
@ -34740,6 +34740,316 @@
"errors": []
}
]
},
{
"groupName": "退回收到模块",
"module": "returnReceived",
"list": [
{
"method": "returnReceived.create",
"description": "退回包裹扫码登记。30日内同仓库同单号只写一次(以第一次为准);反查 wms_order_express 判定是否原单退回,命中则回填 order_express_id/order_id/store_id 并同步标记 is_back='Y'。仓库隔离:warehouse_id 由服务端注入 ctx.user.store_id,禁止前端传入。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "waybill_code",
"type": "string",
"required": true,
"source": "body",
"description": "退回收件运单号(扫描到的退回包裹单号)"
},
{
"name": "remark",
"type": "string",
"required": false,
"source": "body",
"description": "备注"
}
],
"response": [
{
"name": "id",
"type": "integer",
"required": true,
"description": "登记记录主键ID"
},
{
"name": "waybill_code",
"type": "string",
"required": true,
"description": "退回收件运单号"
},
{
"name": "scan_date",
"type": "string",
"required": true,
"description": "扫描收到日期"
},
{
"name": "scanner_id",
"type": "integer",
"required": true,
"description": "扫描人员工号ID"
},
{
"name": "scanner_name",
"type": "string",
"required": true,
"description": "扫描人员工号名称"
},
{
"name": "order_express_id",
"type": "integer",
"required": false,
"description": "原运单ID(原单退回时回填,否则为 null)"
},
{
"name": "order_id",
"type": "integer",
"required": false,
"description": "原订单ID(原单退回时回填,否则为 null)"
},
{
"name": "store_id",
"type": "integer",
"required": false,
"description": "货主ID(原单退回时回填,否则为 null)"
},
{
"name": "remark",
"type": "string",
"required": false,
"description": "备注"
},
{
"name": "is_original_return",
"type": "boolean",
"required": true,
"description": "是否原单退回"
},
{
"name": "store_remark",
"type": "string",
"required": true,
"description": "货主的合约货主备注名称(wms_store_warehouse.store_remask),非原单退回时为空字符串"
},
{
"name": "duplicated",
"type": "boolean",
"required": true,
"description": "是否命中30日幂等、返回第一次记录"
}
],
"errors": [
{
"code": "400",
"message": "waybill_code 不能为空"
},
{
"code": "400",
"message": "缺少仓库上下文"
},
{
"code": "400",
"message": "缺少扫描人员工号上下文"
},
{
"code": "401",
"message": "未提供有效的认证令牌"
},
{
"code": "403",
"message": "无权访问该接口"
}
]
},
{
"method": "returnReceived.list",
"description": "退回收到登记分页列表。仓库隔离(服务端自动注入 warehouse_id = ctx.user.store_id,禁止前端传入)。支持按运单号模糊、扫描日期范围、扫描人员、货主、是否原单退回筛选。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "pagination",
"type": "object",
"required": false,
"source": "body",
"description": "分页 { page: 1, pageSize: 20 }"
},
{
"name": "where",
"type": "object",
"required": false,
"source": "body",
"description": "筛选条件对象,所有字段均可选"
},
{
"name": "where.waybill_code",
"type": "string",
"required": false,
"source": "body.where",
"description": "退回收件运单号(模糊搜索,传 {operator:'like',value} 或直接值)"
},
{
"name": "where.scan_date",
"type": "object",
"required": false,
"source": "body.where",
"description": "扫描日期范围 { operator:'between'|'gte'|'lte', value:[start,end] 或单值 }"
},
{
"name": "where.scanner_id",
"type": "number",
"required": false,
"source": "body.where",
"description": "扫描人员工号ID(等值)"
},
{
"name": "where.store_id",
"type": "number",
"required": false,
"source": "body.where",
"description": "货主ID(等值)"
},
{
"name": "where.is_original_return",
"type": "boolean",
"required": false,
"source": "body.where",
"description": "是否原单退回:true=有关联原运单,false=无关联"
},
{
"name": "sort",
"type": "object",
"required": false,
"source": "body",
"description": "排序 { sortField: 'id'|'scan_date'|'created_at'|'updated_at'|'waybill_code', sortOrder: 'asc'|'desc' }"
}
],
"response": [
{
"name": "list",
"type": "array",
"required": true,
"description": "退回收到登记列表,每条含登记字段 + is_original_return + store_remark"
},
{
"name": "pagination",
"type": "object",
"required": true,
"description": "分页信息 { page, pageSize, total, totalPages, hasPrevious, hasNext }"
}
],
"errors": [
{
"code": "401",
"message": "未提供有效的认证令牌"
},
{
"code": "403",
"message": "无权访问该接口"
}
]
},
{
"method": "returnReceived.detail",
"description": "退回收到登记详情,含原运单(命中时)与货主合约备注(命中时)。免权限但需登录,仓库隔离校验(仅本仓库记录)。",
"isNeedAuth": false,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "id",
"type": "integer",
"required": true,
"source": "body",
"description": "登记记录主键ID"
}
],
"response": [
{
"name": "record",
"type": "object",
"required": true,
"description": "登记记录完整信息(含 is_original_return、store_remark、格式化时间字段)"
},
{
"name": "order_express",
"type": "object",
"required": false,
"description": "原运单详情(order_express_id 不为空时)。含 waybill_code、order_id、store_id、warehouse_id、is_back、is_intercept、logistics_name、logistics_code"
},
{
"name": "store_contract",
"type": "object",
"required": false,
"description": "货主合约备注(store_id 不为空时)。含 store_remask、warehouse_remask、store_use_status、warehouse_use_status"
}
],
"errors": [
{
"code": "400",
"message": "id 必填且必须为正整数"
},
{
"code": "401",
"message": "未提供有效的认证令牌"
},
{
"code": "403",
"message": "无权访问该登记记录"
},
{
"code": "404",
"message": "登记记录不存在"
}
]
},
{
"method": "returnReceived.delete",
"description": "删除退回收到登记记录(物理删除)。仓库隔离校验(仅本仓库记录)。",
"isNeedAuth": true,
"isNeedLogin": true,
"headers": [],
"params": [
{
"name": "id",
"type": "integer",
"required": true,
"source": "body",
"description": "登记记录主键ID"
}
],
"response": [
{
"name": "id",
"type": "integer",
"required": true,
"description": "被删除登记记录ID"
}
],
"errors": [
{
"code": "400",
"message": "id 必填且必须为正整数"
},
{
"code": "401",
"message": "未提供有效的认证令牌"
},
{
"code": "403",
"message": "无权访问该登记记录"
},
{
"code": "404",
"message": "登记记录不存在"
}
]
}
]
}
]
}