oms/backend/app/utils/deliveryStock.js
liufumingren 39c19a4de7 feat(backend): 出入库记录与库存锁定链路、出库单快递/收件人与推送队列
- 出入库记录(库存流水):新增 stock_records 表/模型/只读接口(列表 + 业务动作选项)与「出入库记录」菜单;
  库存变动统一收敛到 app/utils/stockRecord.js#applyStockChange,与流水写入同事务(含变动前后总/锁定/可用数量)
- 发货单:审核(1→2) 按明细锁定库存、发货确认(3→4) 扣减、推送失败退回/驳回/取消/作废释放(新增 stock_locked 列);
  恢复(9→1) 时曾推送过的单据换号(WMS 取消后原单号仍被占用,沿用旧号重推会被判「订单已存在」)
- 出库单:新增快递(express_code/express_name)、收件人(receiver_*) 与多运单号(express_codes) 字段;
  推送报文补齐 logisticsCode/receiverInfo;新增出库单推送服务与定时任务
- 快递:多运单号回填、仓库快递映射(warehouse_express_mappings) 与快递字典补录等迁移
- 契约:补充出入库记录、出库单快递/收件人等定义(swagger.json 为本地生成、不入库)
2026-09-14 00:59:23 +08:00

180 lines
7.7 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 { applyStockChange } = require('./stockRecord');
/**
* 发货单(订单)库存动作:审核锁定 / 释放 / 发货确认扣减。
*
* 与 WMS 侧 `deliveryorder.create` 的库存预占对齐,OMS 侧统一在以下时机动库存(均写 stock_records 流水):
* - **审核(1→2)**:按明细锁定库存(order_lock),可用不足则审核失败
* - **推送失败退回 / 驳回 / 取消 / 作废**:释放锁定(order_unlock)
* - **WMS 发货确认(deliveryorder.confirm, 3→4)**:扣减库存(总数量与锁定同减,order_deduct)
*
* 幂等与兼容依据是 `order_deliveries.stock_locked`:
* - lock:已锁定(1) 直接跳过,不重复占用
* - release/deduct:未锁定(0) 直接跳过 —— 历史单据(本能力上线前已审核/已推送)不会被凭空释放/扣减
*
* 明细商品解析:`order_delivery_items` 未存 product_id,按 `item_code` 关联 `products`
* (主体隔离),匹配不到的明细行会被跳过并返回 skippedLines 供调用方提示。
*/
/** 动作 → 出入库记录业务动作(常量见 app/utils/stockRecord.js#BIZ_TYPES) */
const ACTION_BIZ_TYPES = {
lock: 'order_lock',
release: 'order_unlock',
deduct: 'order_deduct',
};
/** 默认备注 */
const DEFAULT_REMARKS = {
lock: '订单审核锁定库存',
release: '订单释放锁定库存',
deduct: '订单发货确认扣减库存',
};
/**
* 取发货单明细并解析系统商品
* @param {Object} ctx egg context
* @param {Object} order 发货单实例(需含 id / principal_id)
* @param {Object} [transaction] Sequelize 事务
* @return {Promise<Array<Object>>} [{ product_id, item_code, item_name, plan_qty, inventory_type }]
*/
async function loadOrderLines(ctx, order, transaction) {
const Op = ctx.app.Sequelize.Op;
const items = await ctx.model.OrderDeliveryItem.findAll({
where: { order_delivery_id: order.id },
attributes: [ 'id', 'order_line_no', 'item_code', 'item_name', 'plan_qty', 'inventory_type' ],
order: [[ 'order_line_no', 'ASC' ], [ 'id', 'ASC' ]],
transaction,
});
if (!items.length) return [];
const codes = [ ...new Set(items.map(i => i.item_code).filter(v => v != null && String(v).trim() !== '')) ];
const products = codes.length
? await ctx.model.Product.findAll({
where: { principal_id: order.principal_id, item_code: { [Op.in]: codes } },
attributes: [ 'id', 'item_code', 'item_name' ],
transaction,
})
: [];
const byCode = new Map(products.map(p => [ p.item_code, p ]));
return items.map(it => {
const row = it.get ? it.get({ plain: true }) : it;
const product = row.item_code ? byCode.get(row.item_code) : null;
return {
product_id: product ? Number(product.id) : null,
item_code: row.item_code,
item_name: row.item_name || (product && product.item_name) || null,
plan_qty: Number(row.plan_qty) || 0,
inventory_type: row.inventory_type,
};
});
}
/**
* 执行发货单库存动作(账实同事务)
* @param {Object} ctx egg context
* @param {Object} order 发货单实例(需含 id / principal_id / warehouse_id / delivery_order_code / stock_locked)
* @param {String} action lock(审核锁定)/ release(释放锁定)/ deduct(发货确认扣减)
* @param {Object} [options] 选项
* @param {Number} [options.createdBy] 操作人ID
* @param {String} [options.remark] 备注(不传用默认备注)
* @param {Object} [options.transaction] 外部事务;不传时内部自建并提交/回滚
* @return {Promise<{action: String, affected: Number, skipped: Boolean, skippedLines: Array<String>}>}
* affected = 实际发生库存变动的明细行数;skippedLines = 未匹配到系统商品(无 product_id 或数量为 0)的 item_code
*/
async function execute(ctx, order, action, options = {}) {
const bizType = ACTION_BIZ_TYPES[action];
if (!bizType) throw new Error(`未知的发货单库存动作:${action}`);
const locked = Number(order.stock_locked) === 1;
// 幂等/兼容:已锁定不再加锁;未锁定不释放、不扣减
if (action === 'lock' && locked) return { action, affected: 0, skipped: true, skippedLines: [] };
if (action !== 'lock' && !locked) return { action, affected: 0, skipped: true, skippedLines: [] };
const ownTransaction = !options.transaction;
const transaction = options.transaction || await ctx.model.transaction();
try {
const lines = await loadOrderLines(ctx, order, transaction);
const hit = lines.filter(l => l.product_id && l.plan_qty > 0);
// 仅把「未匹配到系统商品」的明细计入 skippedLines(数量为空/0 的明细直接忽略,属数据异常)
const skippedLines = lines.filter(l => !l.product_id).map(l => l.item_code || `#${l.product_id || '?'}`);
if (!hit.length) {
throw new Error('发货单明细未匹配到系统商品(按 item_code 关联 products),无法进行库存操作');
}
for (const line of hit) {
await applyStockChange(ctx, {
bizType,
principalId: order.principal_id,
warehouseId: order.warehouse_id,
productId: line.product_id,
itemCode: line.item_code,
itemName: line.item_name,
itemType: line.inventory_type === 'CC' ? 'CC' : 'ZC',
quantity: line.plan_qty,
billId: order.id,
billNo: order.delivery_order_code,
createdBy: options.createdBy,
remark: options.remark || DEFAULT_REMARKS[action],
transaction,
});
}
// 锁定标记与库存动作同事务:lock → 1,release/deduct → 0
await order.update({ stock_locked: action === 'lock' ? 1 : 0 }, { transaction });
if (ownTransaction) await transaction.commit();
if (skippedLines.length) {
ctx.logger.warn(`[delivery-stock] 发货单 ${order.delivery_order_code} ${action} 跳过未匹配系统商品的明细:${skippedLines.join(', ')}`);
}
return { action, affected: hit.length, skipped: false, skippedLines };
} catch (err) {
if (ownTransaction) await transaction.rollback();
throw err;
}
}
/**
* 审核锁定库存(可用不足抛 INSUFFICIENT_STOCK,由调用方转 400)
* @param {Object} ctx egg context
* @param {Object} order 发货单实例(需含 id / principal_id / warehouse_id / delivery_order_code / stock_locked)
* @param {Object} [options] { createdBy, remark, transaction }
* @return {Promise<Object>} execute 的返回(action / affected / skipped / skippedLines)
*/
function lockDeliveryStock(ctx, order, options = {}) {
return execute(ctx, order, 'lock', options);
}
/**
* 释放锁定库存(推送失败退回 / 驳回 / 取消 / 作废)
* @param {Object} ctx egg context
* @param {Object} order 发货单实例(需含 id / principal_id / warehouse_id / delivery_order_code / stock_locked)
* @param {Object} [options] { createdBy, remark, transaction }
* @return {Promise<Object>} execute 的返回(action / affected / skipped / skippedLines)
*/
function releaseDeliveryStock(ctx, order, options = {}) {
return execute(ctx, order, 'release', options);
}
/**
* 发货确认扣减库存(WMS 回推 deliveryorder.confirm,3→4)
* @param {Object} ctx egg context
* @param {Object} order 发货单实例(需含 id / principal_id / warehouse_id / delivery_order_code / stock_locked)
* @param {Object} [options] { createdBy, remark, transaction }
* @return {Promise<Object>} execute 的返回(action / affected / skipped / skippedLines)
*/
function deductDeliveryStock(ctx, order, options = {}) {
return execute(ctx, order, 'deduct', options);
}
module.exports = {
ACTION_BIZ_TYPES,
DEFAULT_REMARKS,
loadOrderLines,
lockDeliveryStock,
releaseDeliveryStock,
deductDeliveryStock,
};