liufumingren 55f766f643 fix(stockout): 出库单确认按来源分流回传,运单号口径收敛为复数
- storage.stockout.confirm 出站回传改为按 source_type 分流(复用 order_async.js 既有分流实现):
  QM→奇门 taobao.qimen.stockout.confirm;API→OpenAPI 回调 stockout.confirm(appKey 按货主合约
  反查 wms_store_warehouse(auth_status=2) + wms_api_app(启用且 callback_url 非空));
  WMS 等内部来源无需外部通知、直接视为成功。修复此前 API 来源出库单被硬编码发往奇门、
  遭「-1 无法匹配货主」拒绝后无法确认(跳过出站同样走失败分支)的问题。
- storage.stockout.confirm 运单号校验与回传改为以复数 waybill_codes 为准(对齐奇门
  packages.package[].expressCode 多运单模型,不使用 deliveryOrder.expressCode);
  单数 waybill_code 已弃用,仅在复数缺失时回退单数兼容存量单;失败文案改为 (waybill_codes)。
- storage.stockout.updateExpress 以 waybill_codes 为准,单数 waybill_code 降级为镜像字段
  (传非空复数时镜像首个、传空数组/null 时同步置 NULL、同时传两列时复数优先);
  仅传单数的旧调用方行为不变。
- app/service/systems/order_async.js 新增 3 个可复用实例方法(buildStockoutConfirmRequest /
  notifyStockoutExternal / resolveOpenApiAppByStore),薄封装既有模块级实现,
  未改动原函数及其既有调用方。
- 新增回归测试:stockout.confirm.outbound.test.js(8 条,覆盖 API/QM/WMS 三路来源、多运单复数
  回传、存量单单数回退)、stockout.updateExpress.test.js(7 条,覆盖复数镜像与兼容行为)。
- 同步 methods/system.json 与 methods/changes/system.json(storage.stockout.confirm /
  storage.stockout.updateExpress)。
2026-09-15 15:40:39 +08:00

1029 lines
39 KiB
JavaScript
Raw Permalink 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');
/**
* 系统方法层:storage.stockout(非订单出库单)。
* 说明:直接读写 wms_order_stockout + wms_order_stockout_items 表。
*/
class StorageStockoutService extends MainService {
constructor(ctx) {
super(ctx);
const _noNeedLogin = '';
const _noNeedRight = 'list,toOrder,listItems';
const _noNeedLog = 'list,toOrder,listItems';
const _noNeedAuth = 'list,toOrder,listItems';
this.systemInit(_noNeedLogin, _noNeedRight, _noNeedLog, _noNeedAuth);
}
/**
* 出库单列表查询。
* @param {Object} data 请求体
* @param {Object} [data.where] 查询条件
* @param {Object} [data.pagination] 分页参数
* @param {Object} [data.sort] 排序参数
* @return {Promise<Object>} 统一成功包装响应
*/
async list(data = {}) {
const { ctx } = this;
const { Op } = this.app.Sequelize;
const { pagination = {}, sort = {} } = data;
const { parsed } = this.prepareWhereContext(data, {
specialFieldMap: {
quickWhere: {
bucket: 'quick',
},
},
});
const page = Math.max(Number(pagination.page) || 1, 1);
const pageSize = Math.max(Number(pagination.pageSize) || 20, 1);
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
const OrderStockoutModel = ctx.model.OrderStockout;
const andConditions = [
{ warehouse_id: warehouseId },
{ deleted_at: null },
];
const dynamicConditions = Array.isArray(parsed && parsed.dynamicConditions) ? parsed.dynamicConditions : [];
if (dynamicConditions.length > 0) {
andConditions.push({ [Op.and]: dynamicConditions });
}
const quickWhereCondition = parsed && parsed.rawConditionsByField && parsed.rawConditionsByField.quickWhere;
const quickValue = quickWhereCondition && Object.prototype.hasOwnProperty.call(quickWhereCondition, 'value')
? quickWhereCondition.value
: null;
if (quickValue !== null && quickValue !== undefined && String(quickValue).trim() !== '') {
const keyword = String(quickValue).trim();
andConditions.push({
[Op.or]: [
{ stockout_order_code: { [Op.like]: `%${keyword}%` } },
{ remark: { [Op.like]: `%${keyword}%` } },
],
});
}
const validSortFields = [
'id',
'stockout_order_code',
'order_status',
'order_type',
'updated_at',
'created_at',
'order_create_time',
];
const sortField = validSortFields.includes(String(sort.sortField || '').trim())
? String(sort.sortField).trim()
: 'updated_at';
const sortOrder = String(sort.sortOrder || 'DESC').toUpperCase() === 'ASC' ? 'ASC' : 'DESC';
const finalWhere = { [Op.and]: andConditions };
const { count, rows } = await OrderStockoutModel.findAndCountAll({
// 必须返回 id:前端行点击/详情/打印/确认等均依赖 row.id(与 receiving 等列表保持一致)
attributes: { exclude: [ 'warehouse_name' ] },
where: finalWhere,
order: [[ sortField, sortOrder ], [ 'id', 'DESC' ]],
limit: pageSize,
offset: (page - 1) * pageSize,
raw: true,
});
// 补充货主名称:store_name 快照为空时按 store_id 解析 wms_store.company_name
const storeIds = [ ...new Set(rows.map(row => Number(row.store_id)).filter(id => Number.isFinite(id) && id > 0)) ];
if (storeIds.length > 0) {
const stores = await ctx.model.Store.findAll({
where: { id: { [Op.in]: storeIds } },
attributes: [ 'id', 'company_name' ],
raw: true,
});
const nameMap = new Map(stores.map(item => [ Number(item.id), String(item.company_name || '') ]));
for (const row of rows) {
if (!row.store_name) {
row.store_name = nameMap.get(Number(row.store_id)) || '';
}
}
}
return this.success('ok', {
list: rows,
pagination: {
page,
pageSize,
total: count,
totalPages: Math.ceil(count / pageSize),
hasPrevious: page > 1,
hasNext: page < Math.ceil(count / pageSize),
},
});
}
/**
* 出库单转订单。
*
* 将非订单出库单(wms_order_stockout)转为正式销售订单:
* 1. 新订单 create_channel 固定为 STOCKOUT;
* 2. 释放出库单占用的库存锁定,转由新订单重新锁定;
* 3. 转单成功后原出库单置为 CANCELLED,并记录已转订单号(幂等)。
*
* 仅 CREATED / PENDING 状态的出库单允许转单;建单失败时自动补偿恢复出库单锁定。
*
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @param {string} [data.delivery_order_code] 新订单号,不传自动生成(SK 前缀)
* @param {Object} [data.receiverInfo] 收件人信息(name/mobile/tel/province/city/area/town/detailAddress/zipCode)
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async toOrder(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
if (warehouseId <= 0) {
return this.fail('缺少仓库上下文');
}
const order = await ctx.model.OrderStockout.findOne({
where: { id, warehouse_id: warehouseId, deleted_at: null },
});
if (!order) {
return this.fail('出库单不存在');
}
// 幂等:已转订单的出库单直接返回原订单信息
const currentExtendProps =
order.extend_props && typeof order.extend_props === 'object' && !Array.isArray(order.extend_props)
? order.extend_props
: {};
if (currentExtendProps.transferred_order_id) {
return this.success('出库单已转订单', {
id: order.id,
stockout_order_code: order.stockout_order_code,
order_id: currentExtendProps.transferred_order_id,
delivery_order_code: currentExtendProps.transferred_order_code || '',
});
}
if (![ 'CREATED', 'PENDING' ].includes(order.order_status)) {
return this.fail(`出库单当前状态(${order.order_status})不允许转订单`);
}
const items = await ctx.model.OrderStockoutItems.findAll({
where: { order_id: order.id },
order: [[ 'id', 'ASC' ]],
raw: true,
});
if (!items || items.length === 0) {
return this.fail('出库单没有明细,无法转订单');
}
// 收货信息:出库单已存的 receiver_* 字段为基础,接口传入的非空 receiverInfo 字段覆盖
const storedReceiverInfo = {
company: order.receiver_company || '',
name: order.receiver_name || '',
zipCode: order.receiver_zip_code || '',
tel: order.receiver_tel || '',
mobile: order.receiver_mobile || '',
email: order.receiver_email || '',
countryCode: order.receiver_country_code || '',
province: order.receiver_province || '',
city: order.receiver_city || '',
area: order.receiver_area || '',
town: order.receiver_town || '',
detailAddress: order.receiver_detail_address || '',
};
const passedReceiverInfo = data.receiverInfo && typeof data.receiverInfo === 'object'
? data.receiverInfo
: {};
const receiverInfo = { ...storedReceiverInfo };
for (const [ key, value ] of Object.entries(passedReceiverInfo)) {
if (value !== undefined && value !== null && String(value).trim() !== '') {
receiverInfo[key] = String(value).trim();
}
}
// 收货信息必填校验:name、(tel/mobile) 其一、省市区镇详细地址,缺失禁止转订单
const missingFields = [];
if (!String(receiverInfo.name || '').trim()) {
missingFields.push('name(收件人姓名)');
}
const receiverTel = String(receiverInfo.tel || '').trim();
const receiverMobile = String(receiverInfo.mobile || '').trim();
if (!receiverTel && !receiverMobile) {
missingFields.push('tel/mobile(固定电话或移动电话至少一项)');
}
const addressFields = [
[ 'province', '省' ],
[ 'city', '市' ],
[ 'area', '区' ],
[ 'town', '镇' ],
[ 'detailAddress', '详细地址' ],
];
for (const [ key, label ] of addressFields) {
if (!String(receiverInfo[key] || '').trim()) {
missingFields.push(`${key}(${label})`);
}
}
if (missingFields.length > 0) {
return this.fail(`收货信息缺失,不能转订单:缺少 ${missingFields.join('、')}`);
}
const stockStoreService = ctx.service.systems.stockStore;
const lockMeta = {
orderType: 'QM_STOCKOUT',
orderNo: order.stockout_order_code,
orderId: order.id,
};
// 第一步:释放出库单占用的库存锁定(新订单创建时会重新锁定)
const releaseTransaction = await ctx.model.transaction();
try {
for (const item of items) {
const qty = Number(item.plan_qty) || 0;
if (qty <= 0) continue;
const releaseResult = await stockStoreService.lockItemStorages(
item.stock_id,
-qty,
releaseTransaction,
null,
{ ...lockMeta, remark: '出库单转订单释放锁定' }
);
if (!releaseResult.success) {
throw new Error(`库存${item.stock_id}释放锁定失败: ${releaseResult.error}`);
}
}
await releaseTransaction.commit();
} catch (err) {
await releaseTransaction.rollback().catch(() => {});
ctx.logger.error(`[stockout.toOrder] 释放出库单锁定失败: ${err.message}`);
return this.fail(`转订单失败:${err.message}`);
}
// 第二步:创建订单(create_channel=STOCKOUT,内部重新锁定库存)
// 快递编码沿用出库单已解析的 express_code(系统快递编码),平台不传 sourcePlatformCode 走兜底平台
const deliveryOrderCode = String(data.delivery_order_code || '').trim()
|| `SK${Date.now()}${Math.floor(Math.random() * 9000) + 1000}`;
const orderLines = items.map((item, idx) => ({
itemCode: item.item_code || '',
itemId: Number(item.item_id) || 0,
itemName: item.item_name || '',
planQty: Number(item.plan_qty) || 0,
stockId: Number(item.stock_id) || 0,
inventoryType: item.inventory_type || '',
orderLineNo: String(item.order_line_no || idx + 1),
ownerCode: item.owner_code || '',
sourceOrderCode: order.stockout_order_code,
}));
const addOrderData = {
request: {
deliveryOrder: {
deliveryOrderCode,
orderType: order.order_type || 'QTCK',
createChannel: 'STOCKOUT',
logisticsCode: order.express_code || '',
sourcePlatformCode: order.source_platform_code || '',
receiverInfo,
remark: order.remark || '',
sourceOrderCode: order.stockout_order_code,
},
orderLines: { orderLine: orderLines },
},
};
const info = {
storeId: order.store_id,
warehouseId,
appKey: (ctx.user && ctx.user.app_key) || '',
};
let addOrderResult = null;
try {
addOrderResult = await ctx.service.systems.deliveryOrder.addOrder(addOrderData, info, 'STOCKOUT');
} catch (err) {
addOrderResult = { success: false, message: err.message, data: null };
}
const orderId = addOrderResult && addOrderResult.data && addOrderResult.data.orderId;
const isDuplicate = !!(addOrderResult && addOrderResult.success && addOrderResult.message === '订单已存在');
if (!addOrderResult || !addOrderResult.success || !orderId || isDuplicate) {
// 建单失败/订单号重复:补偿恢复出库单锁定
await this._restoreStockoutLocks(stockStoreService, items, lockMeta, ctx);
return this.fail(`转订单失败:${(addOrderResult && addOrderResult.message) || '订单创建失败'}`);
}
// 第三步:标记出库单已转订单(状态推进到 TRANSFERRED,该状态下禁止一键出库)
try {
await ctx.model.OrderStockout.update(
{
order_status: 'TRANSFERRED',
sync_message: `已转订单 ${deliveryOrderCode}`,
extend_props: {
...currentExtendProps,
transferred_order_id: orderId,
transferred_order_code: deliveryOrderCode,
transferred_at: new Date(),
},
updated_at: new Date(),
},
{ where: { id: order.id } }
);
} catch (updateErr) {
// 订单已创建成功,仅出库单标记失败:记录告警,不回滚订单
ctx.logger.error(`[stockout.toOrder] 标记出库单已转失败: ${updateErr.message}`);
}
await this._writeStockoutOperationLog(
order,
'STOCKOUT_TO_ORDER',
`出库单已转订单 ${deliveryOrderCode}(order_id=${orderId}),已释放库存锁定`
);
return this.success('转订单成功', {
id: order.id,
stockout_order_code: order.stockout_order_code,
order_id: orderId,
delivery_order_code: deliveryOrderCode,
step: addOrderResult.data.step,
});
}
/**
* 转订单失败时恢复出库单库存锁定(补偿)。
* @param {Object} stockStoreService 库存服务
* @param {Array} items 出库单明细
* @param {Object} lockMeta 锁元信息
* @param {Object} ctx 请求上下文
* @return {Promise<void>} 无返回值
*/
async _restoreStockoutLocks(stockStoreService, items, lockMeta, ctx) {
const restoreTransaction = await ctx.model.transaction();
try {
for (const item of items) {
const qty = Number(item.plan_qty) || 0;
if (qty <= 0) continue;
const restoreResult = await stockStoreService.lockItemStorages(
item.stock_id,
qty,
restoreTransaction,
null,
{ ...lockMeta, remark: '出库单转订单失败恢复锁定' }
);
if (!restoreResult.success) {
throw new Error(`库存${item.stock_id}恢复锁定失败: ${restoreResult.error}`);
}
}
await restoreTransaction.commit();
} catch (err) {
await restoreTransaction.rollback().catch(() => {});
ctx.logger.error(`[stockout.toOrder] 恢复出库单锁定失败: ${err.message}`);
}
}
/**
* 写 wms_operation_log 操作日志(businessType=stockout),失败仅告警不影响主流程。
*
* 委托到共享实现 `systems/stockout_order.js#_writeStockoutOperationLog`,
* 保持本入口的历史口径:操作人取自 ctx.user,仓库取自 ctx.user.store_id(缺失时
* 回退出库单自身 warehouse_id)。
*
* @param {Object} order 出库单实例或行
* @param {string} operationCode 操作编码
* @param {string} message 日志内容
* @param {Object} [options={}] 选项,可含 transaction
* @return {Promise<void>} 无返回值
*/
async _writeStockoutOperationLog(order, operationCode, message, options = {}) {
const { ctx } = this;
const stockoutOrderService = ctx.service && ctx.service.systems && ctx.service.systems.stockoutOrder;
if (!stockoutOrderService || typeof stockoutOrderService._writeStockoutOperationLog !== 'function') {
ctx.logger.warn('[stockout] 出库单领域服务不可用,跳过记录');
return;
}
const user = ctx.user || {};
await stockoutOrderService._writeStockoutOperationLog(order, operationCode, message, {
transaction: options.transaction,
warehouseId: Number(ctx.user && ctx.user.store_id) || order.warehouse_id || null,
operator: {
id: user.employees_id ?? user.id ?? null,
name: String(user.employees_name || user.real_name || user.name || 'system'),
},
});
}
/**
* 出库单明细查询。
* @param {Object} data 请求体
* @param {number} [data.id] 出库单ID
* @param {string} [data.stockout_order_code] 出库单号
* @return {Promise<Object>} 统一成功包装响应
*/
async listItems(data = {}) {
const { ctx } = this;
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
const id = Number(data.id || 0);
// 兼容 delivery_order_code 旧参数名
const stockoutOrderCode = String(data.stockout_order_code || data.delivery_order_code || '').trim();
if (!id && !stockoutOrderCode) {
return this.fail('id 或 stockout_order_code 至少传一个');
}
const OrderStockoutModel = ctx.model.OrderStockout;
const OrderStockoutItemsModel = ctx.model.OrderStockoutItems;
const where = {
warehouse_id: warehouseId,
deleted_at: null,
};
if (id > 0) {
where.id = id;
} else {
where.stockout_order_code = stockoutOrderCode;
}
const order = await OrderStockoutModel.findOne({
where,
raw: true,
});
if (!order || !order.id) {
return this.success('ok', {
order: null,
list: [],
});
}
const list = await OrderStockoutItemsModel.findAll({
where: {
order_id: order.id,
},
order: [[ 'id', 'ASC' ]],
raw: true,
});
return this.success('ok', {
order,
list,
});
}
/**
* 查询出库单操作日志(分页)。
* 日志业务类型 business_type=stockout,business_id=出库单ID;
* 覆盖创建/审核/转订单/确认/修改/取消等操作(STOCKOUT_* 操作编码)。
* @param {Object} data 请求体
* @param {number} [data.id] 出库单ID(与 stockout_order_code 至少传一个)
* @param {string} [data.stockout_order_code] 出库单号
* @param {Object} [data.pagination] 分页对象,支持 page / pageSize(或 page_size)
* @return {Promise<Object>} 统一成功包装响应 { list, pagination }
*/
async listLogs(data = {}) {
const { ctx, service } = this;
const requestData = data && typeof data === 'object' ? data : {};
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
const id = Number(requestData.id || 0);
const stockoutOrderCode = String(requestData.stockout_order_code || '').trim();
// 分页参数:兼容顶层 page/pageSize(与订单日志 order.queryOrderLogs 一致)与 pagination 对象两种写法
const pagination = requestData.pagination && typeof requestData.pagination === 'object'
? requestData.pagination
: {};
const page = requestData.page ?? pagination.page;
const pageSize = requestData.pageSize ?? pagination.pageSize ?? pagination.page_size;
if (!id && !stockoutOrderCode) {
return this.fail('id 或 stockout_order_code 至少传一个');
}
const emptyResult = {
list: [],
pagination: {
page: Number.parseInt(page, 10) || 1,
pageSize: Number.parseInt(pageSize, 10) || 20,
total: 0,
totalPages: 0,
},
};
// 定位出库单ID(日志 business_id 存的是出库单ID)
let stockoutId = id;
if (!stockoutId) {
const order = await ctx.model.OrderStockout.findOne({
where: {
stockout_order_code: stockoutOrderCode,
warehouse_id: warehouseId,
deleted_at: null,
},
attributes: [ 'id' ],
raw: true,
});
if (!order || !order.id) {
return this.success('ok', {
data: emptyResult,
code: 200,
});
}
stockoutId = Number(order.id);
}
try {
const result = await service.systems.operationLog.queryStockoutLogs({
id: stockoutId,
page,
pageSize,
warehouseId,
});
return this.success('ok', {
data: result,
code: 200,
});
} catch (e) {
// 与订单日志接口一致:查询异常时以 200 包装返回错误信息
return this.success(e.message, {
code: 200,
});
}
}
/**
* 出库单确认(直出)。
* 不改变内部库存,直接按出库单明细的计划数量确认。
* 出站回传按 source_type 分流(QM→奇门 taobao.qimen.stockout.confirm,
* API→OpenAPI 回调 stockout.confirm,其他内部来源直接视为成功),
* 回传成功后释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水),状态才推进到 COMPLETED。
* 要求运单号已填写(以复数 waybill_codes 为准,存量单回退单数 waybill_code),否则拒绝确认。
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async confirm(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const order = await ctx.model.OrderStockout.findByPk(id);
if (!order) {
return this.fail('出库单不存在');
}
if (!order.canConfirm || !order.canConfirm()) {
return this.fail(`出库单当前状态(${order.order_status})不允许确认`);
}
// 校验运单号是否已填写:回传以复数 waybill_codes 为准(一单多运单 → 奇门 packages.package[]),
// 单数 waybill_code 已弃用,仅在复数缺失时对存量单做兼容回退。
const confirmWaybillCodes = (Array.isArray(order.waybill_codes) && order.waybill_codes.length > 0
? order.waybill_codes
: [ order.waybill_code ])
.map(code => String(code || '').trim())
.filter(code => !!code);
if (confirmWaybillCodes.length === 0) {
return this.fail('出库单未填写运单号(waybill_codes),请先更新运单号后再确认');
}
// 第一步:事务内写入明细 actual_qty(暂不改变 order_status)
const transaction = await ctx.model.transaction();
let items;
try {
items = await ctx.model.OrderStockoutItems.findAll({
where: { order_id: id },
transaction,
});
for (const item of items) {
await item.update({
actual_qty: item.plan_qty,
updated_at: new Date(),
}, { transaction });
}
await transaction.commit();
} catch (err) {
await transaction.rollback();
ctx.logger.error('[stockout.confirm] 明细更新失败:', err);
return this.fail(`确认失败:${err.message}`);
}
// 第二步:按出库单来源通知外部
// QM → 奇门 taobao.qimen.stockout.confirm;API → OpenAPI 回调 stockout.confirm;
// WMS 等内部来源 → 无需通知外部,直接视为成功。
// 与出库单转订单回传(orderAsync.syncStockoutOrders)共用同一分流实现,避免两处逻辑漂移。
const orderAsyncService = ctx.service.systems && ctx.service.systems.orderAsync;
let qimenSuccess = false;
let qimenMessage = '';
if (!orderAsyncService || typeof orderAsyncService.notifyStockoutExternal !== 'function') {
qimenMessage = '出库单回传服务不可用';
ctx.logger.error('[stockout.confirm] 出库单回传服务不可用(ctx.service.systems.orderAsync 缺失)');
} else {
try {
// 直出确认没有发货单上下文,orderRow 传空对象:报文内快递信息回退出库单 express_code/express_name
// 运单号统一走复数(packages.package[].expressCode),不传 deliveryOrder.expressCode
const outboundData = orderAsyncService.buildStockoutConfirmRequest(order, {}, items, confirmWaybillCodes);
// API 来源需按货主合约反查回调 appKey;QM 来源由奇门 client 按货主编码发送,无需 appKey
let appKey = '';
if (String(order.source_type || 'QM').trim().toUpperCase() === 'API') {
const resolvedApp = await orderAsyncService.resolveOpenApiAppByStore(order.store_id, order.warehouse_id);
appKey = String((resolvedApp && resolvedApp.appKey) || '').trim();
}
const notifyResult = await orderAsyncService.notifyStockoutExternal(order, outboundData, { appKey });
qimenSuccess = !!(notifyResult && notifyResult.success === true);
qimenMessage = qimenSuccess
? ''
: String((notifyResult && notifyResult.message) || '通知外部失败').trim();
} catch (outboundErr) {
qimenMessage = outboundErr.message || '出站通知异常';
ctx.logger.error(`[stockout.confirm] 出站通知异常: ${qimenMessage}`);
}
}
// 第三步:根据出站结果更新状态
if (qimenSuccess) {
// 直出确认:释放出库单占用的库存锁定(QM_STOCKOUT,负数量释放并自动写 UNLOCK 流水),
// 与状态推进到 COMPLETED 在同一事务内完成,失败回滚可重试。
const finalizeTransaction = await ctx.model.transaction();
try {
let totalReleaseQty = 0;
for (const item of items) {
const qty = Number(item.plan_qty) || 0;
if (qty <= 0) continue;
const releaseResult = await ctx.service.systems.stockStore.lockItemStorages(
item.stock_id,
-qty,
finalizeTransaction,
null,
{
orderType: 'QM_STOCKOUT',
orderNo: order.stockout_order_code,
orderId: order.id,
remark: '出库单确认释放锁定',
}
);
if (!releaseResult.success) {
// 已释放过(锁定不足)视为幂等成功,避免阻断重试
const alreadyReleased = String(releaseResult.error || '').includes('释放数量超过已锁定库存');
if (alreadyReleased) {
ctx.logger.warn(`[stockout.confirm] 库存${item.stock_id}锁定已释放,跳过: ${releaseResult.error}`);
continue;
}
throw new Error(`库存${item.stock_id}释放锁定失败: ${releaseResult.error}`);
}
totalReleaseQty += qty;
}
await this._writeStockoutOperationLog(
order,
'STOCKOUT_CONFIRM',
`出库单确认完成(直出),释放锁定库存 ${totalReleaseQty}`,
{ transaction: finalizeTransaction }
);
await ctx.model.OrderStockout.update(
{ order_status: 'COMPLETED', sync_status: 'SUCCESS', sync_message: '', updated_at: new Date() },
{ where: { id: order.id }, transaction: finalizeTransaction }
);
await finalizeTransaction.commit();
} catch (err) {
await finalizeTransaction.rollback().catch(() => {});
ctx.logger.error(`[stockout.confirm] 释放锁定失败: ${order.stockout_order_code} - ${err.message}`);
return this.fail(`确认失败:${err.message}`);
}
ctx.logger.info(`[stockout.confirm] 确认完成: ${order.stockout_order_code}`);
return this.success('确认成功', {
id: order.id,
stockout_order_code: order.stockout_order_code,
order_status: 'COMPLETED',
logisticsName: 'OTHER',
expressCode: order.express_code,
expressCodes: order.express_codes,
qimenSync: 'success',
});
}
// 出站失败:更新 sync_status,order_status 不变
await ctx.model.OrderStockout.update(
{ sync_status: 'FAILED', sync_message: qimenMessage, updated_at: new Date() },
{ where: { id: order.id } }
);
ctx.logger.error(`[stockout.confirm] 出站同步失败: ${order.stockout_order_code} - ${qimenMessage}`);
return this.fail(`出站同步失败: ${qimenMessage || '未发起出站通知'}`);
}
/**
* 出库单取消。
*
* 委托到共享实现 `systems/stockout_order.js#cancel`(奇门 / openapi 同口径:
* 事务 + 行锁,释放 QM_STOCKOUT 库存锁定,状态置 CANCELLED 并写操作日志),
* 本入口负责入参校验与对外契约映射。
*
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async cancel(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
if (warehouseId <= 0) {
return this.fail('缺少仓库上下文');
}
const stockoutOrderService = ctx.service && ctx.service.systems && ctx.service.systems.stockoutOrder;
if (!stockoutOrderService || typeof stockoutOrderService.cancel !== 'function') {
return this.fail('出库单取消服务不可用');
}
const result = await stockoutOrderService.cancel(
{ id },
{
storeId: null,
warehouseId,
operatorLabel: String(
(ctx.user && (ctx.user.employees_name || ctx.user.real_name || ctx.user.name)) || 'system'
),
}
);
if (result.flag !== 'success') {
// 契约文案映射:共享层「未找到对应的出库单」→ 本入口「出库单不存在」,其余文案原样透出
return this.fail(
result.message === '未找到对应的出库单' ? '出库单不存在' : result.message
);
}
return this.success('取消成功', {
id: result.id,
stockout_order_code: result.stockout_order_code,
order_status: result.order_status,
});
}
/**
* 更新出库单快递和运单号。
* 用于在确认前填写 express_code / waybill_codes。
* 运单号以复数 waybill_codes 为准(一单多运单);单数 waybill_code 已弃用,
* 传入 waybill_codes 时会自动镜像为首个单号写回单数列。
* express_code 传入后自动从系统快递表解析 express_name。
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @param {string} [data.express_code] 快递公司编码(如 SF、STO),传入后自动解析 express_name
* @param {string} [data.waybill_code] 运单号(单数,已弃用;仅作为 waybill_codes 首个的镜像,勿单独使用)
* @param {string[]} [data.waybill_codes] 运单号列表(复数,回传以此为准,支持一单多运单)
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async updateExpress(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const order = await ctx.model.OrderStockout.findByPk(id);
if (!order) {
return this.fail('出库单不存在');
}
const updateData = { updated_at: new Date() };
// express_code:自动解析 express_name
if (data.express_code !== undefined) {
updateData.express_code = data.express_code || null;
if (data.express_code) {
try {
const expressMap = await ctx.service.systems.setting.express.getSystemExpressMap();
const info = expressMap.get(String(data.express_code).trim().toUpperCase());
updateData.express_name = info ? info.name : '';
} catch (e) {
ctx.logger.warn('[updateExpress] 解析快递名称失败: ' + e.message);
updateData.express_name = '';
}
} else {
updateData.express_name = null;
}
}
// waybill_code(单数)已弃用:回传以 waybill_codes(复数)为准(一单多运单),
// 单数列仅作为复数首个的镜像保留,便于历史查询与展示;
// 传入 waybill_codes 时以复数首个覆盖单数,避免两列不一致。
if (data.waybill_code !== undefined) {
updateData.waybill_code = data.waybill_code || null;
}
if (data.waybill_codes !== undefined) {
const codes = data.waybill_codes;
if (codes !== null && !Array.isArray(codes)) {
return this.fail('waybill_codes 必须是数组或 null');
}
updateData.waybill_codes = codes;
updateData.waybill_code = Array.isArray(codes) && codes.length > 0
? String(codes[0] || '').trim() || null
: null;
}
if (Object.keys(updateData).length <= 1) {
return this.fail('没有需要更新的字段');
}
await order.update(updateData);
await order.reload();
return this.success('更新成功', {
id: order.id,
stockout_order_code: order.stockout_order_code,
express_code: order.express_code,
express_name: order.express_name,
waybill_code: order.waybill_code,
waybill_codes: order.waybill_codes,
});
}
/**
* 修改出库单信息。
*
* 可修改范围:收件人(name/tel/mobile 等)、地址(province/city/area/town/detailAddress 等)、
* 快递编码(express_code,自动解析 express_name)、来源平台(source_platform_code/name)。
* 未传入的字段不修改;快递编码与平台相关字段不传即保持原值。
*
* 限制:仅 CREATED / PENDING 状态允许修改;修改后收货信息不完整(name、(tel/mobile) 其一、
* 省市区镇详细地址缺任一)时禁止提交。
*
* @param {Object} data 请求体
* @param {number} data.id 出库单ID(必填)
* @param {string} [data.name] 收件人姓名
* @param {string} [data.tel] 固定电话
* @param {string} [data.mobile] 移动电话
* @param {string} [data.company] 公司名称
* @param {string} [data.email] 电子邮箱
* @param {string} [data.zipCode] 邮编
* @param {string} [data.countryCode] 国家二字码
* @param {string} [data.province] 省份
* @param {string} [data.city] 城市
* @param {string} [data.area] 区/县
* @param {string} [data.town] 镇/街道
* @param {string} [data.detailAddress] 详细地址
* @param {string} [data.receiver_id] 收件人证件号
* @param {string} [data.express_code] 快递公司编码(自动解析 express_name)
* @param {string} [data.source_platform_code] 来源平台编码
* @param {string} [data.source_platform_name] 来源平台名称
* @return {Promise<Object>} 统一成功/失败包装响应
*/
async updateInfo(data = {}) {
const { ctx } = this;
const id = Number(data.id || 0);
if (!id) {
return this.fail('缺少出库单ID');
}
const warehouseId = Number(ctx.user && ctx.user.store_id) || 0;
if (warehouseId <= 0) {
return this.fail('缺少仓库上下文');
}
const order = await ctx.model.OrderStockout.findOne({
where: { id, warehouse_id: warehouseId, deleted_at: null },
});
if (!order) {
return this.fail('出库单不存在');
}
if (![ 'CREATED', 'PENDING' ].includes(order.order_status)) {
return this.fail(`出库单当前状态(${order.order_status})不允许修改`);
}
const updateData = { updated_at: new Date() };
const changedLabels = [];
// 收件人 / 地址字段:传入才更新,空串置 NULL
const receiverFieldMap = {
receiver_name: [ 'name', '收件人姓名' ],
receiver_tel: [ 'tel', '固定电话' ],
receiver_mobile: [ 'mobile', '移动电话' ],
receiver_company: [ 'company', '公司名称' ],
receiver_email: [ 'email', '电子邮箱' ],
receiver_zip_code: [ 'zipCode', '邮编' ],
receiver_country_code: [ 'countryCode', '国家' ],
receiver_province: [ 'province', '省份' ],
receiver_city: [ 'city', '城市' ],
receiver_area: [ 'area', '区县' ],
receiver_town: [ 'town', '镇街道' ],
receiver_detail_address: [ 'detailAddress', '详细地址' ],
receiver_id: [ 'receiver_id', '证件号' ],
};
for (const [ column, [ param, label ]] of Object.entries(receiverFieldMap)) {
if (data[param] !== undefined) {
updateData[column] = data[param] === null
? null
: String(data[param]).trim() || null;
changedLabels.push(label);
}
}
// 快递编码:传入才更新,并自动解析 express_name(与 updateExpress 同口径)
if (data.express_code !== undefined) {
const expressCode = String(data.express_code || '').trim();
if (expressCode) {
let expressName = '';
try {
const expressMap = await ctx.service.systems.setting.express.getSystemExpressMap();
const info = expressMap.get(expressCode.toUpperCase());
expressName = info ? info.name : '';
} catch (e) {
ctx.logger.warn('[updateInfo] 解析快递名称失败: ' + e.message);
}
updateData.express_code = expressCode;
updateData.express_name = expressName;
} else {
updateData.express_code = null;
updateData.express_name = null;
}
changedLabels.push('快递编码');
}
// 来源平台:传入才更新,空串置 NULL
if (data.source_platform_code !== undefined) {
updateData.source_platform_code = String(data.source_platform_code || '').trim() || null;
changedLabels.push('来源平台');
}
if (data.source_platform_name !== undefined) {
updateData.source_platform_name = String(data.source_platform_name || '').trim() || null;
if (!changedLabels.includes('来源平台')) {
changedLabels.push('来源平台');
}
}
// 修改后的收货信息完整性校验:name、(tel/mobile) 其一、省市区镇详细地址必填,缺失禁止提交
const mergedReceiver = {
name: updateData.receiver_name !== undefined ? updateData.receiver_name : order.receiver_name,
tel: updateData.receiver_tel !== undefined ? updateData.receiver_tel : order.receiver_tel,
mobile: updateData.receiver_mobile !== undefined ? updateData.receiver_mobile : order.receiver_mobile,
province: updateData.receiver_province !== undefined ? updateData.receiver_province : order.receiver_province,
city: updateData.receiver_city !== undefined ? updateData.receiver_city : order.receiver_city,
area: updateData.receiver_area !== undefined ? updateData.receiver_area : order.receiver_area,
town: updateData.receiver_town !== undefined ? updateData.receiver_town : order.receiver_town,
detailAddress: updateData.receiver_detail_address !== undefined ? updateData.receiver_detail_address : order.receiver_detail_address,
};
const missingFields = [];
if (!String(mergedReceiver.name || '').trim()) {
missingFields.push('name(收件人姓名)');
}
if (!String(mergedReceiver.tel || '').trim() && !String(mergedReceiver.mobile || '').trim()) {
missingFields.push('tel/mobile(固定电话或移动电话至少一项)');
}
const addressFields = [
[ 'province', '省' ],
[ 'city', '市' ],
[ 'area', '区' ],
[ 'town', '镇' ],
[ 'detailAddress', '详细地址' ],
];
for (const [ key, label ] of addressFields) {
if (!String(mergedReceiver[key] || '').trim()) {
missingFields.push(`${key}(${label})`);
}
}
if (missingFields.length > 0) {
return this.fail(`收货信息缺失,禁止提交:缺少 ${missingFields.join('、')}`);
}
await ctx.model.OrderStockout.update(updateData, { where: { id: order.id } });
const updated = await ctx.model.OrderStockout.findByPk(order.id, { raw: true });
if (changedLabels.length > 0) {
await this._writeStockoutOperationLog(
order,
'STOCKOUT_UPDATE_INFO',
`修改出库单信息:${changedLabels.join('、')}`
);
}
return this.success('修改成功', updated);
}
}
module.exports = StorageStockoutService;