oms/backend/app/utils/stockRecord.js
liufumingren fc58f79b42 feat(backend): 新增商品导出任务
- 新增 export_tasks 表与模型(迁移 20260916000000),记录导出类型、状态、进度、
  文件名与错误信息
- app/service/exportTask.js:生成 CSV(exceljs)并落盘到 upload/exports/<主体>/<年>/<月>/<日>
- app/schedule/exportWorker.js 定时执行待处理任务,cleanupExport.js 清理过期文件
- 接口:POST /api/export-tasks 提交、GET /api/export-tasks 列表与进度、
  GET /api/export-tasks/:id/download 下载
- app/utils/exportDefs.js 定义各导出类型的数据源;warehouseProduct / stockRecord 补充
  库存相关数据
- 契约补 exportTask 系列与 apikey 安全定义;.eslintrc 放行相关文件与 apikey 标签
- package-lock 同步
2026-09-14 22:14:23 +08:00

240 lines
11 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 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<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,
};