liufumingren b07d7bca33 feat(stockout): 出库单转订单全链路(receiverInfo 落库、出库单默认快递、updateInfo、TRANSFERRED)
- toOrder:create_channel=STOCKOUT、库存锁转移、收货必填校验、同快递/兜底平台、转单后置 TRANSFERRED(禁止一键出库)

- stockout.create:解析 receiverInfo 13 字段落库,快递兜底改用出库单默认快递(stockout_default_express_code,默认 ZT 自提)

- 新增 storage.stockout.updateInfo:收货/地址/快递/平台修改,仅 CREATED/PENDING,收货缺失禁止提交

- 迁移:wms_order_stockout 新增 receiver_* 13 列、order_status 增 TRANSFERRED、source_platform 两列

- 附带:storeWarehouse.createUser、奇门取消订单配送表幂等、express_platform Uint64 打包、方法与变更文档同步
2026-08-25 23:40:42 +08:00

326 lines
12 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');
/**
* 奇门出库单服务。
*
* 处理 stockout.create / stockout.query 接口,
* 使用专用表 `wms_order_stockout` + `wms_order_stockout_items`。
*/
class stockoutServer extends MainService {
/**
* 创建出库单。
*
* 将奇门 stockout.create 请求的 deliveryOrder / orderLines 写入
* `wms_order_stockout` 主表和 `wms_order_stockout_items` 明细表,
* 整个过程在一个数据库事务内完成,失败自动回滚。
*
* @param {object} data - 奇门 stockout.create 请求体
* @param {object} data.request - 请求数据
* @param {object} data.request.deliveryOrder - 出库单头信息
* @param {object} data.request.orderLines - 出库单明细
* @param {object|object[]} data.request.orderLines.orderLine - 明细行(单条为对象,多条为数组)
* @return {Promise<object>} 返回 success / fail 结果
*/
async create(data) {
const { app, ctx, storeId, warehouseId, warehouseCode } = this;
const { deliveryOrder, orderLines } = data.request;
// 单条 orderLine 转为数组
let orderLine = orderLines && orderLines.orderLine;
if (orderLine && orderLine.orderLineNo) {
orderLine = [ orderLine ];
}
if (!orderLine || !Array.isArray(orderLine) || orderLine.length === 0) {
return this.fail('创建出库单失败,失败原因:\n没有有效的订单明细数据');
}
const totalOrderLines = deliveryOrder.totalOrderLines || orderLine.length;
// 快递编码解析(简化口径,独立于订单兜底链):
// 1. 货主开启 enable_external_express_code 且传了 logisticsCode 时,按
// wms_express_setting 映射 → 系统快递列表 匹配;
// 2. 未传 / 未开启 / 匹配不到 → 使用出库单兜底快递编码(stockout_default_express_code,
// 默认 ZT 自提),不再回退订单默认快递;不走订单的快递策略漏斗(matchPolicy)。
let expressCode = null;
let expressName = null;
try {
const deliveryOrderService = ctx.service.systems.deliveryOrder;
const policyConfig = await deliveryOrderService.getStoreWarehousePolicyConfig(storeId, warehouseId);
const expressList = await ctx.service.systems.express.getExpressList();
const findExpress = code => {
const upperCode = String(code || '').trim().toUpperCase();
if (!upperCode || !Array.isArray(expressList)) {
return null;
}
return expressList.find(item => item
&& String(item.code || item.value || '').trim().toUpperCase() === upperCode) || null;
};
const externalCode = String(deliveryOrder.logisticsCode || '').trim();
const enableExternal = deliveryOrderService.normalizePolicyFlag(
policyConfig && policyConfig.enable_external_express_code
);
if (enableExternal && externalCode) {
// 1) wms_express_setting 外部编码映射 → 系统快递编码
const settingSnapshot = await deliveryOrderService.resolveExpressSettingSnapshot(externalCode, warehouseId);
if (settingSnapshot && settingSnapshot.expressCode) {
const sysCode = String(settingSnapshot.expressCode).trim();
const sysItem = findExpress(sysCode);
expressCode = sysCode;
expressName = sysItem
? String(sysItem.name || sysItem.label || sysCode).trim()
: String(settingSnapshot.name || sysCode).trim();
} else {
// 2) 系统快递列表直接匹配
const matched = findExpress(externalCode);
if (matched) {
expressCode = String(matched.code || matched.value || externalCode).trim();
expressName = String(matched.name || matched.label || expressCode).trim();
}
}
}
if (!expressCode) {
// 兜底:出库单兜底快递编码(货主配置,默认 ZT 自提),不回退订单默认快递
const fallbackCode = String(policyConfig && policyConfig.stockout_default_express_code || '').trim() || 'ZT';
const fallbackItem = findExpress(fallbackCode);
expressCode = fallbackItem
? String(fallbackItem.code || fallbackItem.value || fallbackCode).trim()
: fallbackCode;
expressName = fallbackItem
? String(fallbackItem.name || fallbackItem.label || fallbackCode).trim()
: fallbackCode;
}
} catch (err) {
ctx.logger.warn(`[stockout.create] 快递编码解析失败,保持为空: ${err.message}`);
}
// 收件人信息解析(receiverInfo 13 个标准字段落库,供转订单与确认回传使用)
const receiver = deliveryOrder.receiverInfo && typeof deliveryOrder.receiverInfo === 'object'
? deliveryOrder.receiverInfo
: {};
const receiverFields = {
receiver_company: receiver.company,
receiver_name: receiver.name,
receiver_zip_code: receiver.zipCode,
receiver_tel: receiver.tel,
receiver_mobile: receiver.mobile,
receiver_email: receiver.email,
receiver_country_code: receiver.countryCode,
receiver_province: receiver.province,
receiver_city: receiver.city,
receiver_area: receiver.area,
receiver_town: receiver.town,
receiver_detail_address: receiver.detailAddress,
receiver_id: receiver.id,
};
for (const key of Object.keys(receiverFields)) {
const rawValue = receiverFields[key];
receiverFields[key] = rawValue === undefined || rawValue === null
? null
: String(rawValue).trim() || null;
}
// 第一步:校验所有商品是否在 StockStore 中存在,并收集有效明细
const errors = [];
const items = [];
for (let i = 0; i < orderLine.length; i++) {
const line = orderLine[i];
let wmsStock = await app.model.StockStore.findByPk(line.itemId);
// 校验 StockStore 记录的 store_id 与当前上下文一致,防止跨货主越权
if (wmsStock && Number(wmsStock.store_id) !== Number(this.storeId)) {
wmsStock = null;
}
// 外部渠道(奇门)itemId 可能是平台商品标识或条码而非 WMS 主键,
// 主键查不到或跨货主时降级按 item_code + 仓库货主维度查找
if (!wmsStock && line.itemCode) {
const stockWhere = {
item_code: line.itemCode,
warehouse_id: warehouseId,
store_id: storeId,
};
if (this.appKey) {
stockWhere.app_key = this.appKey;
}
wmsStock = await app.model.StockStore.findOne({ where: stockWhere });
}
if (!wmsStock) {
errors.push(
`SKU${line.itemId}商品《${line.itemName}》编码《${line.itemCode}》\n未同步推送到仓库`
);
continue;
}
if (!wmsStock.stock_id) {
errors.push(
`SKU${line.itemId}商品《${line.itemName}》编码《${line.itemCode}》wms无对应关系\n请联系仓库关联创建商品`
);
continue;
}
const planQty = parseInt(line.planQty) || 0;
if (planQty <= 0) {
errors.push(
`SKU${line.itemId}商品《${line.itemName}》编码《${line.itemCode}》\n计划数量必须大于0`
);
continue;
}
items.push({
orderLineNo: line.orderLineNo,
ownerCode: line.ownerCode,
itemCode: line.itemCode,
itemId: line.itemId,
itemName: line.itemName,
planQty,
inventoryType: line.inventoryType,
stockId: wmsStock.stock_id,
});
}
if (errors.length > 0) {
return this.fail(`创建出库单失败,失败原因:\n${errors.join('\n')}`);
}
// 预取超卖配置,避免每次 lockItemStorages 在锁内回退查 DB
const oversellConfig = await ctx.service.systems.stockStore
.getStoreWarehousePolicyByStoreAndWarehouse(storeId, warehouseId);
// 第二步:在事务中写入主表 + 库存锁定 + 明细表
const transaction = await ctx.model.transaction();
try {
const order = await ctx.model.OrderStockout.create(
{
stockout_order_code: deliveryOrder.deliveryOrderCode,
order_type: deliveryOrder.orderType,
total_order_lines: totalOrderLines,
order_create_time: deliveryOrder.createTime
? new Date(deliveryOrder.createTime)
: null,
remark: deliveryOrder.remark || null,
express_code: expressCode,
express_name: expressName,
...receiverFields,
warehouse_id: warehouseId,
store_id: storeId,
qimen_owner_code: items[0].ownerCode,
qimen_warehouse_code: warehouseCode,
source_type: 'QM',
created_at: new Date(),
updated_at: new Date(),
},
{ transaction }
);
const orderId = order.id;
// 库存锁定:按 stockId 升序排序后逐个加锁,避免死锁
const sortedItems = [ ...items ].sort((a, b) => a.stockId - b.stockId);
for (const item of sortedItems) {
const lockResult = await ctx.service.systems.stockStore.lockItemStorages(
item.stockId,
item.planQty,
transaction,
oversellConfig,
{ orderType: 'QM_STOCKOUT', orderNo: deliveryOrder.deliveryOrderCode, orderId }
);
if (!lockResult.success) {
throw new Error(
`SKU${item.itemId}商品《${item.itemName}》编码《${item.itemCode}》\n库存锁定失败: ${lockResult.error}`
);
}
}
// 批量创建明细
const now = new Date();
const itemRecords = items.map(item => ({
order_id: orderId,
order_line_no: item.orderLineNo,
owner_code: item.ownerCode,
item_code: item.itemCode,
item_id: item.itemId,
item_name: item.itemName,
plan_qty: item.planQty,
inventory_type: item.inventoryType,
stock_id: item.stockId,
created_at: now,
updated_at: now,
}));
await ctx.model.OrderStockoutItems.bulkCreate(itemRecords, {
transaction,
validate: true,
});
await transaction.commit();
return this.success('出库单创建成功', {
stockoutOrderId: order.id,
stockoutOrderCode: order.stockout_order_code,
});
} catch (err) {
await transaction.rollback();
ctx.logger.error('[stockout.create] 事务写入失败:', err);
return this.fail(`创建出库单失败,失败原因:\n${err.message}`);
}
}
/**
* 查询出库单。
*
* 根据 deliveryOrderCode 查 `wms_order_stockout` 主表,
* 然后关联查 `wms_order_stockout_items` 明细,按奇门标准响应格式返回。
*
* @param {object} data - 奇门 stockout.query 请求体
* @param {object} data.request - 请求数据
* @param {object} data.request.deliveryOrder - 出库单查询条件
* @param {string} data.request.deliveryOrder.deliveryOrderCode - 出库单号
* @return {Promise<object>} 返回 success / fail 结果
*/
async query(data) {
const { app, ctx } = this;
const { deliveryOrderCode } = data.request.deliveryOrder;
// 查主表
const order = await ctx.model.OrderStockout.findOne({
where: { stockout_order_code: deliveryOrderCode },
});
if (!order) {
return this.fail('未找到出库单');
}
// 查明细
const items = await ctx.model.OrderStockoutItems.findAll({
where: { order_id: order.id },
order: [[ 'order_line_no', 'ASC' ]],
});
return this.success('成功', {
totalLines: items.length,
deliveryOrder: {
deliveryOrderCode: order.stockout_order_code,
deliveryOrderId: order.id,
warehouseCode: order.qimen_warehouse_code,
orderType: order.order_type,
status: order.order_status,
createTime: order.order_create_time ? app.formatDate(order.order_create_time) : null,
remark: order.remark || '',
},
orderLines: {
orderLine: items.map(item => ({
orderLineNo: item.order_line_no,
ownerCode: item.owner_code,
itemCode: item.item_code,
itemId: item.item_id,
itemName: item.item_name,
planQty: item.plan_qty,
inventoryType: item.inventory_type,
})),
},
});
}
}
module.exports = stockoutServer;