'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 }, inventory_sync_out: { label: '库存同步出库', direction: 2, billType: 2 }, 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), // 库存同步:系统数量多于外部时,仅减少总数量(不动锁定) inventory_sync_out: (ctx, principalId, productId, qty, transaction, itemType) => stock.decrease(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} 记录实例 */ 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} 变动后的库存行(数量 <= 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, };