oms/backend/app/controller/wmsNotify.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

210 lines
8.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 { Controller } = require('egg');
const { qimenSign, timingSafeEqual } = require('../lib/wms/sign');
const orderCallback = require('../lib/orderCallback');
const { applyStockChange } = require('../utils/stockRecord');
/** 时间戳时效阈值:±10 分钟(600 秒),与 WMS 文档一致 */
const TIME_TOLERANCE_SEC = 600;
/**
* 明细行提取与「实际数量写回」统一走 app/lib/orderCallback.js(与 /openapi 回调共用一份实现)
* - 兼容 orderLines.orderLine / orderLines / items 等结构
* - 按 itemCode 匹配明细行,写回 actual_in_qty / actual_out_qty
*/
const extractNotifyLines = orderCallback.extractLines;
const applyActualQty = orderCallback.applyActualQty;
/**
* @controller WmsNotifyController WMS 出站通知回调(公开)
* 对应 warehouse_notify.json:WMS 处理消息后主动 POST 到本接口,
* query 携带 app_key / method / timestamp / sign,body 为 { code, data }。
* 先校验外部传入的 app_key 是否在仓库接口配置中存在(无配置则拒绝),
* 再用 MD5(app_secret + timestamp + 原始body) 校验签名,失败拒绝。
*/
class WmsNotifyController extends Controller {
async handle() {
const { ctx } = this;
const { app_key: appKey, method, timestamp, sign } = ctx.query;
if (!appKey || !method || !timestamp || !sign) {
ctx.status = 400;
ctx.body = { code: 400, message: '缺少必要参数 app_key / method / timestamp / sign' };
return;
}
// 时间戳时效校验
const ts = Number(timestamp);
const now = Math.floor(Date.now() / 1000);
if (!Number.isFinite(ts) || Math.abs(now - ts) > TIME_TOLERANCE_SEC) {
ctx.status = 400;
ctx.body = { code: 400, message: 'timestamp 已过期或非法(与服务器时间差不得超过 ±10 分钟)' };
return;
}
// 检测外部传入 appKey 是否有配置:无配置或已禁用则拒绝
const api = await ctx.model.WarehouseApi.findOne({ where: { app_key: appKey, status: 1 } });
if (!api) {
ctx.status = 403;
ctx.body = { code: 403, message: `app_key(${appKey}) 未配置或已禁用` };
return;
}
// 签名校验:MD5(app_secret + timestamp + 原始请求体)
const rawBody = ctx.request.rawBody || JSON.stringify(ctx.request.body || {});
const expectSign = qimenSign(api.app_secret, timestamp, rawBody);
if (!timingSafeEqual(expectSign, sign)) {
ctx.status = 403;
ctx.body = { code: 403, message: '签名校验失败' };
return;
}
// 路由处理:按 method 分发;未实现的方法统一回执 200,避免 WMS 无谓重推
try {
switch (method) {
case 'notify.ping':
// 连通性探测,直接回执
break;
case 'notify.reply':
case 'notify.stockChange':
case 'notify.itemSync':
// TODO: 后续接入具体业务(库存回写 / 商品同步结果)。当前仅落日志。
ctx.logger.info(`[wms-notify] 收到 ${method}`, {
appKey,
data: ctx.request.body && ctx.request.body.data,
});
break;
case 'entryorder.confirm':
// 入库单确认:外部仓库收货回推后驱动 OMS 完成入库并增加系统库存
await this.handleEntryConfirm(ctx, api);
break;
case 'notify.delivery':
await this.handleDelivery(ctx, api);
break;
default:
ctx.logger.warn(`[wms-notify] 未实现的方法 ${method}`, { appKey });
}
} catch (err) {
// 处理异常仍回执 200,异常已记录日志,避免 WMS 重推
ctx.logger.error(`[wms-notify] 处理 ${method} 异常`, err);
}
// warehouse_notify.json:外部系统返回 {"code":200} 或 HTTP 非 200 视为推送失败
ctx.status = 200;
ctx.body = { code: 200, message: 'success' };
}
/**
* 发货通知(method = notify.delivery):WMS 已发货,扣减系统库存(总数量与锁定各减明细数量)
* 通过 deliveryOrderCode / orderCode 关联 OMS 出库单;找不到则按明细 itemCode 兜底扣减
* 幂等:已通过出库单关联扣减过的(stock_deducted=1)不再重复扣减
*/
async handleDelivery(ctx, api) {
const data = (ctx.request.body && ctx.request.body.data) || ctx.request.body || {};
ctx.logger.info('[wms-notify] notify.delivery', { appKey: api.app_key, data });
const principalId = api.principal_id;
const code = data.deliveryOrderCode
|| (data.deliveryOrder && data.deliveryOrder.deliveryOrderCode)
|| data.orderCode
|| (data.order && data.order.orderCode);
const transaction = await ctx.model.transaction();
try {
let deducted = false;
if (code) {
const order = await ctx.model.OutboundOrder.findOne({ where: { bill_no: code, principal_id: principalId } });
if (order) {
// 回推明细的实际数量写回「已出数量」
await applyActualQty(ctx, order.id, 2, 'actual_out_qty', extractNotifyLines(data));
}
if (order && !order.stock_deducted) {
const items = await ctx.model.StockItem.findAll({
where: { bill_type: 2, bill_id: order.id, product_id: { [ctx.app.Sequelize.Op.ne]: null } },
attributes: [ 'product_id', 'code', 'name', 'quantity' ],
order: [[ 'product_id', 'ASC' ]],
});
for (const it of items) {
// 扣减库存 + 写一条出库确认记录(含变动后锁定数量与可用数量)
await applyStockChange(ctx, {
bizType: 'outbound_deduct',
principalId,
warehouseId: api.warehouse_id,
productId: Number(it.product_id),
itemCode: it.code,
itemName: it.name,
quantity: Number(it.quantity) || 0,
billId: order.id,
billNo: order.bill_no,
remark: 'WMS 发货通知扣减库存(notify.delivery)',
transaction,
});
}
await order.update({ stock_deducted: 1 }, { transaction });
deducted = true;
}
}
// 兜底:按明细 itemCode 扣减(WMS 直接给出发货明细)
if (!deducted) {
const rawItems = data.items
|| data.orderLines
|| (data.deliveryOrder && data.deliveryOrder.orderLines)
|| (data.deliveryOrder && data.deliveryOrder.items)
|| [];
for (const it of rawItems) {
const itemCode = it.itemCode || it.item_code || (it.item && it.item.itemCode);
const qty = Number(it.quantity || it.actualQty || it.planQty || 0);
if (!itemCode || qty <= 0) continue;
const product = await ctx.model.Product.findOne({ where: { item_code: itemCode, principal_id: principalId } });
if (!product) continue;
await applyStockChange(ctx, {
bizType: 'outbound_deduct',
principalId,
warehouseId: api.warehouse_id,
productId: product.id,
itemCode,
itemName: product.item_name,
quantity: qty,
billNo: code,
remark: 'WMS 发货通知扣减库存(按明细兜底)',
transaction,
});
}
}
await transaction.commit();
} catch (err) {
await transaction.rollback();
ctx.logger.error('[wms-notify] notify.delivery 处理异常', err);
}
}
/**
* 入库单确认(method = entryorder.confirm):WMS 已收货回推,驱动 OMS 完成入库并增加库存
* 与 /openapi 的 entryorder.confirm 共用同一实现(app/lib/orderCallback.js#confirmInbound),
* 报文外层包裹(data / request)由 orderCallback 统一归一化;
* 幂等:已完成的单据(状态4)不会重复加库存;失败仅记日志并回执 200,避免 WMS 无谓重推。
*/
async handleEntryConfirm(ctx, api) {
ctx.logger.info('[wms-notify] entryorder.confirm', { appKey: api.app_key, data: ctx.request.body });
const result = await orderCallback.confirmInbound(ctx, {
principalId: api.principal_id,
warehouseId: api.warehouse_id,
data: ctx.request.body || {},
}).catch(err => {
ctx.logger.error('[wms-notify] entryorder.confirm 处理异常', err);
return { ok: false, message: err.message };
});
if (result.ok) {
const data = result.data || {};
ctx.logger.info(
`[wms-notify] entryorder.confirm 已处理 bill_no=${data.bill_no} status=${data.status} 明细更新=${data.actual_qty_updated} 已完成=${data.already_completed}`
);
return;
}
ctx.logger.warn(`[wms-notify] entryorder.confirm 未处理:${result.message}`);
}
}
module.exports = WmsNotifyController;