liufumingren e19b5fc18c feat(order): 取消单据支持 CK 出库单与 RK 入库单
- 奇门 order.cancel:CK 组(PTCK/DBCK/B2BCK/QTCK/CGTH)委托 systems.stockoutOrder.cancel 取消出库单(仅 CREATED/PENDING 可取消,释放 QM_STOCKOUT 锁定,不回传);RK 组由裸改状态升级为复用 systems.storage.entry.cancel 完整作废流程(状态守卫 + 回退收货单占用 + 操作日志,已作废幂等成功)。

- openapi order.cancel:新增 CK 组与 RK 组路由,成功/失败文案与奇门口径一致。

- storage.stockout.cancel 改为委托共享实现,对外契约与文案不变,改为单事务 + 行锁。

- storage.entry.cancel 扩展入参能力(entryOrderCode 定位 / skipExternalSync / idempotent / notFoundMessage),系统方法入口行为不变。

- 文档:methods/{qimen,openapi,system}.json 及对应 changes 同步。

注:app/service/systems/stockout_order.js 与 methods/openapi.json 同时承载此前未提交的出库单(stockout)共享服务与文档,文件粒度无法拆分,一并纳入本次提交。
2026-09-13 02:24:18 +08:00

1051 lines
38 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');
/**
* 系统方法层: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,
});
}
}
/**
* 出库单确认(直出)。
* 不改变内部库存,直接按出库单明细的计划数量确认。
* 出站同步 taobao.qimen.stockout.confirm 成功后,释放创建时占用的库存锁定(QM_STOCKOUT,写 UNLOCK 流水),
* 状态才推进到 COMPLETED。
* 要求 express_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})不允许确认`);
}
// 校验运单号是否已填写
if (!order.waybill_code) {
return this.fail('出库单未填写运单号(waybill_code),请先更新运单号后再确认');
}
// 第一步:事务内写入明细 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}`);
}
// 第二步:出站通知 ERP(taobao.qimen.stockout.confirm)
const { app } = this;
let qimenSuccess = false;
let qimenMessage = '';
if (app.qimenClient && order.qimen_owner_code && order.qimen_warehouse_code) {
try {
const now = app.formatDate(new Date());
const waybillCodes = Array.isArray(order.waybill_codes) && order.waybill_codes.length > 0
? order.waybill_codes
: [ order.waybill_code ].filter(Boolean);
const outboundData = {
deliveryOrder: {
totalOrderLines: order.total_order_lines,
deliveryOrderCode: order.stockout_order_code,
deliveryOrderId: order.id,
warehouseCode: order.qimen_warehouse_code,
orderType: order.order_type,
status: 'DELIVERED',
outBizCode: order.stockout_order_code,
confirmType: 0,
orderConfirmTime: now,
operatorCode: '',
operatorName: '',
},
packages: {
package: waybillCodes.map(code => ({
logisticsCode: order.express_code || 'OTHER',
logisticsName: order.express_name || 'OTHER',
expressCode: code,
packageCode: order.stockout_order_code,
items: items.map(item => ({
itemCode: item.item_code || '',
itemId: item.item_id || '',
quantity: item.plan_qty || 0,
})),
})),
},
orderLines: items.map(item => ({
orderLineNo: item.order_line_no || '',
ownerCode: item.owner_code || order.qimen_owner_code,
itemCode: item.item_code || '',
itemId: item.item_id || '',
itemName: item.item_name || '',
planQty: item.plan_qty || 0,
actualQty: item.plan_qty || 0,
inventoryType: item.inventory_type || 'ZP',
})),
};
const sendResult = await app.qimenClient.send(
'taobao.qimen.stockout.confirm',
order.qimen_owner_code,
outboundData,
{ ctx }
);
// 解析奇门响应
const response = (sendResult && sendResult.xmlArray && sendResult.xmlArray.response)
? (Array.isArray(sendResult.xmlArray.response) ? sendResult.xmlArray.response[0] : sendResult.xmlArray.response)
: {};
qimenSuccess = String(response.flag || '').trim() === 'success';
qimenMessage = qimenSuccess ? '' : `${response.code || ''} ${response.message || '未知错误'}`.trim();
} catch (outboundErr) {
qimenMessage = outboundErr.message || '出站通知异常';
ctx.logger.error(`[stockout.confirm] 出站通知异常: ${qimenMessage}`);
}
} else {
ctx.logger.warn(`[stockout.confirm] 跳过出站通知: qimenClient=${!!app.qimenClient}, ownerCode=${order.qimen_owner_code}, warehouseCode=${order.qimen_warehouse_code}`);
}
// 第三步:根据出站结果更新状态
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_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] 运单号
* @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;
}
}
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;
}
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;