oms/backend/app/controller/wmsNotify.js
liufumingren 0a9ee3c593 feat(backend): 对外通用回调接口 /openapi 与回调日志
- POST /openapi 入口(controller/openapi.js),协议与 WMS openapi 对齐(method/app_key/sign)
- 方法注册表 lib/openapiMethods.js:index.ping、entryorder.confirm/match、deliveryorder.confirm、stockout.confirm、order.cancel
- 单据处理公共逻辑 lib/orderCallback.js;请求/响应封装 lib/apiResponse.js、lib/openapiCallback.js
- WMS 回调入口 controller/wmsNotify.js 改为复用公共模块
- 回调日志:callback_logs 表 + lib/callbackLog.js(脱敏、fire-and-forget)
2026-09-13 02:23:49 +08:00

186 lines
7.8 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 { Controller } = require('egg');
const { qimenSign, timingSafeEqual } = require('../lib/wms/sign');
const orderCallback = require('../lib/orderCallback');
const stock = require('../utils/stock');
/** 时间戳时效阈值:±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', 'quantity' ],
order: [[ 'product_id', 'ASC' ]],
});
for (const it of items) {
await stock.deduct(ctx, principalId, Number(it.product_id), Number(it.quantity) || 0, 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 stock.deduct(ctx, principalId, product.id, qty, 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;