oms/backend/app/utils/stockRecord.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

237 lines
11 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 stock = require('./stock');
/**
* 出入库记录(stock_records)写入工具。
*
* 出入库记录与 product_stocks 余量表互补:余量表只存「当前是多少」,本模块在每次库存变动的
* 同一事务内追加一行流水,记录业务动作、单据来源、变动数量与变动前后的总数量/锁定数量/可用数量。
*
* 业务动作(BIZ_TYPES,唯一常量来源;前端下拉与说明以此为准):
* - outbound_lock 出库推送锁定(出库单 push:可用 → 锁定)
* - outbound_unlock 出库解锁(推送失败释放 / 驳回 / 取消回滚)
* - outbound_deduct 出库确认扣减(WMS 回推 stockout.confirm / notify.delivery:总数量与锁定同减)
* - outbound_restore 出库驳回回补(已扣减过的出库单驳回时回补总数量)
* - inbound_increase 入库确认增加(WMS 回推 entryorder.confirm:总数量增加)
* - order_lock 订单(发货单)审核锁定(审核 1→2:可用 → 锁定)
* - order_unlock 订单解锁(推送失败退回 / 驳回 / 取消 / 作废)
* - order_deduct 订单发货确认扣减(WMS 回推 deliveryorder.confirm:总数量与锁定同减)
*
* 统一入口 `applyStockChange(ctx, options)`:先锁定库存行取变动前余量 → 调 app/utils/stock.js
* 对应动作 → 按「实际前后差值」写记录(残次/正品、扣减时的下限截断都能如实反映)。
* 记录写入与库存变动共用同一事务,保证账实一致。
*/
/**
* 业务动作定义
* - label 中文名
* - direction 业务方向(1入库方向 2出库方向)
* - billType 单据类型(1入库单 2出库单 3发货单/订单)
*/
const BIZ_TYPES = {
outbound_lock: { label: '出库推送锁定', direction: 2, billType: 2 },
outbound_unlock: { label: '出库解锁', direction: 2, billType: 2 },
outbound_deduct: { label: '出库确认扣减', direction: 2, billType: 2 },
outbound_restore: { label: '出库驳回回补', direction: 2, billType: 2 },
inbound_increase: { label: '入库确认增加', direction: 1, billType: 1 },
order_lock: { label: '订单审核锁定', direction: 2, billType: 3 },
order_unlock: { label: '订单解锁', direction: 2, billType: 3 },
order_deduct: { label: '订单发货确认扣减', direction: 2, billType: 3 },
};
/** 出入方向中文名 */
const DIRECTION_LABELS = { 1: '入库', 2: '出库' };
/** 业务动作 → app/utils/stock.js 的具体动作函数 */
const STOCK_ACTIONS = {
outbound_lock: (ctx, principalId, productId, qty, transaction, itemType) => stock.lock(ctx, principalId, productId, qty, transaction, itemType),
outbound_unlock: (ctx, principalId, productId, qty, transaction, itemType) => stock.unlock(ctx, principalId, productId, qty, transaction, itemType),
outbound_deduct: (ctx, principalId, productId, qty, transaction, itemType) => stock.deduct(ctx, principalId, productId, qty, transaction, itemType),
outbound_restore: (ctx, principalId, productId, qty, transaction, itemType) => stock.increase(ctx, principalId, productId, qty, transaction, itemType),
inbound_increase: (ctx, principalId, productId, qty, transaction, itemType) => stock.increase(ctx, principalId, productId, qty, transaction, itemType),
// 发货单(订单):审核锁定 / 解锁 / 发货确认扣减,与出库单同源动作
order_lock: (ctx, principalId, productId, qty, transaction, itemType) => stock.lock(ctx, principalId, productId, qty, transaction, itemType),
order_unlock: (ctx, principalId, productId, qty, transaction, itemType) => stock.unlock(ctx, principalId, productId, qty, transaction, itemType),
order_deduct: (ctx, principalId, productId, qty, transaction, itemType) => stock.deduct(ctx, principalId, productId, qty, transaction, itemType),
};
/** 业务动作列表(供接口下拉/校验使用) */
const BIZ_TYPE_LIST = Object.keys(BIZ_TYPES).map(value => ({
value,
label: BIZ_TYPES[value].label,
direction: BIZ_TYPES[value].direction,
bill_type: BIZ_TYPES[value].billType,
}));
/**
* 库存维度统一为 ZC/CC(stock_items 的 ZP 在写入库存时映射为 ZC)
* @param {String} itemType 库存类型(ZP/CC/其他)
* @return {String} ZC 或 CC
*/
function normalizeItemType(itemType) {
return String(itemType || '').toUpperCase() === 'CC' ? 'CC' : 'ZC';
}
/**
* 取库存行的余量快照
* @param {Object} row product_stocks 行(可为空)
* @return {{quantity: Number, lock: Number, available: Number}} 变动前/后的余量
*/
function snapshot(row) {
const quantity = Number(row && row.quantity) || 0;
const lockQuantity = Number(row && row.lock_quantity) || 0;
return {
quantity,
lock: lockQuantity,
// available 以行上冗余列为准(stock.js 每次变动都会重算),缺列时按 总-锁 兜底
available: row && row.available != null ? Number(row.available) : quantity - lockQuantity,
};
}
/**
* 写入一条出入库记录
* @param {Object} ctx egg context
* @param {Object} payload 记录内容
* @param {String} payload.bizType 业务动作(BIZ_TYPES 的 key,必填)
* @param {Number} payload.principalId 主体ID(必填)
* @param {Number} [payload.warehouseId] 仓库ID
* @param {Number} [payload.productId] 系统商品ID
* @param {String} [payload.itemCode] 商品编码快照
* @param {String} [payload.itemName] 商品名称快照
* @param {String} [payload.itemType] 库存类型 ZC/CC,默认 ZC
* @param {Number} payload.quantity 本次变动数量(恒记正数,方向见 bizType/direction)
* @param {Number} payload.quantityBefore 变动前总数量
* @param {Number} payload.quantityAfter 变动后总数量
* @param {Number} payload.lockBefore 变动前锁定数量
* @param {Number} payload.lockAfter 变动后锁定数量
* @param {Number} payload.availableBefore 变动前可用数量
* @param {Number} payload.availableAfter 变动后可用数量
* @param {Number} [payload.billId] 单据头ID
* @param {String} [payload.billNo] 单据号(入库单 RK_ / 出库单 CK_ / 发货单 FH_)
* @param {Number} [payload.createdBy] 操作人ID
* @param {String} [payload.remark] 备注
* @param {Object} [payload.transaction] Sequelize 事务(与库存变动同事务)
* @return {Promise<Object>} 记录实例
*/
async function recordStockChange(ctx, payload) {
const {
bizType, principalId, warehouseId, productId, itemCode, itemName, itemType,
quantity, quantityBefore, quantityAfter, lockBefore, lockAfter, availableBefore, availableAfter,
billId, billNo, createdBy, remark, transaction,
} = payload || {};
const meta = BIZ_TYPES[bizType];
if (!meta) throw new Error(`未知的出入库记录业务类型:${bizType}`);
if (principalId == null) throw new Error('出入库记录缺少所属主体(principalId)');
const qtyBefore = Number(quantityBefore) || 0;
const qtyAfter = Number(quantityAfter) || 0;
const lockB = Number(lockBefore) || 0;
const lockA = Number(lockAfter) || 0;
return ctx.model.StockRecord.create({
principal_id: Number(principalId),
warehouse_id: warehouseId == null || warehouseId === '' ? null : Number(warehouseId),
product_id: productId == null || productId === '' ? null : Number(productId),
item_code: itemCode ? String(itemCode).slice(0, 100) : null,
item_name: itemName ? String(itemName).slice(0, 255) : null,
item_type: normalizeItemType(itemType),
biz_type: bizType,
direction: meta.direction,
bill_type: meta.billType,
bill_id: billId == null || billId === '' ? null : Number(billId),
bill_no: billNo ? String(billNo).slice(0, 50) : null,
// 变动数量恒记正数;锁定变动量用前后差值(正=加锁 负=解锁)
quantity: Math.abs(Number(quantity) || 0),
quantity_before: qtyBefore,
quantity_after: qtyAfter,
lock_quantity: lockA - lockB,
lock_before: lockB,
lock_after: lockA,
available_before: Number(availableBefore) || 0,
available_after: Number(availableAfter) || 0,
remark: remark ? String(remark).slice(0, 255) : null,
created_by: createdBy == null || createdBy === '' ? null : Number(createdBy),
}, { transaction });
}
/**
* 执行库存变动并写入出入库记录(账实同事务)
*
* 与直接调用 app/utils/stock.js 的区别:本函数额外落一条流水,供「出入库记录」页面查询。
* 库存不足(INSUFFICIENT_STOCK)等异常由 stock.js 抛出,此时不会写记录。
*
* @param {Object} ctx egg context
* @param {Object} options 参数
* @param {String} options.bizType 业务动作(BIZ_TYPES 的 key,必填)
* @param {Number} options.principalId 主体ID(必填)
* @param {Number} options.productId 系统商品ID(必填)
* @param {Number} options.quantity 变动数量(必填,需 > 0)
* @param {String} [options.itemType] 库存类型 ZC/CC,默认 ZC
* @param {Number} [options.warehouseId] 仓库ID
* @param {String} [options.itemCode] 商品编码快照
* @param {String} [options.itemName] 商品名称快照
* @param {Number} [options.billId] 单据头ID
* @param {String} [options.billNo] 单据号
* @param {Number} [options.createdBy] 操作人ID
* @param {String} [options.remark] 备注
* @param {Object} options.transaction Sequelize 事务
* @return {Promise<Object|null>} 变动后的库存行(数量 <= 0 或未命中动作时返回 null)
*/
async function applyStockChange(ctx, options) {
const {
bizType, principalId, productId, quantity, itemType,
warehouseId, itemCode, itemName, billId, billNo, createdBy, remark, transaction,
} = options || {};
const action = STOCK_ACTIONS[bizType];
if (!action) throw new Error(`未知的出入库记录业务类型:${bizType}`);
const qty = Number(quantity) || 0;
if (qty <= 0 || productId == null || productId === '') return null;
const type = normalizeItemType(itemType);
const pid = Number(productId);
// 先取(或建)库存行并锁定:拿到变动前余量,用于记录「变动前/后」
const before = await stock.getOrCreate(ctx, principalId, pid, type, transaction);
const beforeSnap = snapshot(before);
const row = await action(ctx, principalId, pid, qty, transaction, type);
const afterSnap = snapshot(row || before);
await recordStockChange(ctx, {
bizType,
principalId,
warehouseId,
productId: pid,
itemCode,
itemName,
itemType: type,
quantity: qty,
quantityBefore: beforeSnap.quantity,
quantityAfter: afterSnap.quantity,
lockBefore: beforeSnap.lock,
lockAfter: afterSnap.lock,
availableBefore: beforeSnap.available,
availableAfter: afterSnap.available,
billId,
billNo,
createdBy,
remark,
transaction,
});
return row;
}
module.exports = {
BIZ_TYPES,
BIZ_TYPE_LIST,
DIRECTION_LABELS,
normalizeItemType,
recordStockChange,
applyStockChange,
};