- 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)
170 lines
7.4 KiB
JavaScript
170 lines
7.4 KiB
JavaScript
'use strict';
|
||
|
||
const { nowTimestamp } = require('./apiResponse');
|
||
const orderCallback = require('./orderCallback');
|
||
|
||
/**
|
||
* 对外通用回调接口的方法注册表。
|
||
*
|
||
* 命名与 WMS openapi 一致:`模块.动作`,如 index.ping。
|
||
* 方法签名:async (ctx, payload) => ({ ok, message, data })
|
||
* - payload.appKey 请求传入的应用Key
|
||
* - payload.api 按 app_key 定位到的接口配置(warehouse_apis 记录)
|
||
* - payload.warehouse 该接口配置关联的仓库(warehouse_apis.warehouse_id → warehouses)
|
||
* - payload.body 业务参数(请求体 JSON 解析结果)
|
||
* - payload.query 系统参数(method / app_key / v / timestamp 等)
|
||
* - payload.timestamp 归一化后的秒级时间戳
|
||
* ok=false 表示业务处理失败(控制器按 HTTP 400 + flag=failure 输出,便于调用方重试/告警);
|
||
* data 为成功时的业务数据,外层由控制器统一包装为 { flag, code, message, data, timestamp }。
|
||
*
|
||
* 单据处理统一走 app/lib/orderCallback.js:按 app_key 定位到的「主体 + 仓库」校验后
|
||
* 用单据号(inbound_orders.bill_no / outbound_orders.bill_no)定位 OMS 单据;
|
||
* 新增方法时在 METHODS 中按 `模块.动作` 注册即可。
|
||
*/
|
||
const METHODS = {
|
||
/**
|
||
* 连通性探测(method = index.ping)
|
||
* 外部系统配置好回调地址后先调用本方法,确认网络链路与 app_key/签名 是否可用;
|
||
* 同时回显按 app_key 定位到的仓库,便于确认凭据与仓库的对应关系是否正确。
|
||
* @param {Object} ctx egg context
|
||
* @param {Object} payload 调用上下文
|
||
* @param {Object} payload.api 按 app_key 定位到的接口配置(warehouse_apis 记录)
|
||
* @param {Object} payload.warehouse 接口配置关联的仓库
|
||
* @param {Object} payload.body 业务参数(请求体 JSON)
|
||
* @param {Object} payload.query 系统参数(method / app_key / v / timestamp 等)
|
||
* @return {Promise<Object>} { ok, message, data }
|
||
*/
|
||
'index.ping': async (ctx, { api, warehouse, body, query }) => {
|
||
ctx.logger.info('[openapi] index.ping', {
|
||
appKey: api.app_key,
|
||
warehouseId: warehouse.id,
|
||
principalId: api.principal_id,
|
||
});
|
||
return {
|
||
ok: true,
|
||
message: 'ok',
|
||
data: {
|
||
pong: true,
|
||
method: 'index.ping',
|
||
app_key: api.app_key,
|
||
warehouse: {
|
||
id: warehouse.id,
|
||
code: warehouse.code,
|
||
name: warehouse.name,
|
||
},
|
||
principal_id: api.principal_id,
|
||
api_version: query.v || '',
|
||
echo: body || {},
|
||
server_time: nowTimestamp(),
|
||
},
|
||
};
|
||
},
|
||
|
||
/**
|
||
* 入库单确认(method = entryorder.confirm):WMS 收货完成
|
||
* 写回明细「已入数量」,并把「已推送(3)」的单据完成入库(增加系统库存,幂等)
|
||
* 报文兼容两种结构:顶层字段 / entryOrder 一层嵌套,以及整体包一层 request
|
||
* (如 WMS 实际回推的 `{ request: { entryOrder: { entryOrderCode }, orderLines } }`,
|
||
* 由 app/lib/orderCallback.js#unwrapPayload 统一归一化)
|
||
* @param {Object} ctx egg context
|
||
* @param {Object} payload 调用上下文
|
||
* @param {Object} payload.api 按 app_key 定位到的接口配置
|
||
* @param {Object} payload.warehouse 接口配置关联的仓库
|
||
* @param {Object} payload.body 回调报文(含 entryOrderCode / orderCode 与 orderLines)
|
||
* @return {Promise<Object>} { ok, message, data }
|
||
*/
|
||
'entryorder.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmInbound(ctx, {
|
||
principalId: api.principal_id,
|
||
warehouseId: warehouse.id,
|
||
data: body,
|
||
}),
|
||
|
||
/**
|
||
* 入库单匹配(method = entryorder.match):WMS 反馈入库单与收货单的匹配结果
|
||
* 仅写回明细「已入数量」并登记匹配信息,不改单据状态、不加库存(等待 entryorder.confirm 确认收货)
|
||
* @param {Object} ctx egg context
|
||
* @param {Object} payload 调用上下文
|
||
* @param {Object} payload.api 按 app_key 定位到的接口配置
|
||
* @param {Object} payload.warehouse 接口配置关联的仓库
|
||
* @param {Object} payload.body 回调报文(含 entryOrderCode / receivingNumber / matchType)
|
||
* @return {Promise<Object>} { ok, message, data }
|
||
*/
|
||
'entryorder.match': (ctx, { api, warehouse, body }) => orderCallback.matchInbound(ctx, {
|
||
principalId: api.principal_id,
|
||
warehouseId: warehouse.id,
|
||
data: body,
|
||
}),
|
||
|
||
/**
|
||
* 发货单确认(method = deliveryorder.confirm):WMS 已发货出库
|
||
* 写回明细「已出数量」,扣减系统库存并置「已完成(4)」(幂等,明细以仓库侧为准)
|
||
* @param {Object} ctx egg context
|
||
* @param {Object} payload 调用上下文
|
||
* @param {Object} payload.api 按 app_key 定位到的接口配置
|
||
* @param {Object} payload.warehouse 接口配置关联的仓库
|
||
* @param {Object} payload.body 回调报文(含 deliveryOrderCode / orderCode 与 orderLines)
|
||
* @return {Promise<Object>} { ok, message, data }
|
||
*/
|
||
'deliveryorder.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmOutbound(ctx, {
|
||
principalId: api.principal_id,
|
||
warehouseId: warehouse.id,
|
||
data: body,
|
||
}),
|
||
|
||
/**
|
||
* 出库单确认(method = stockout.confirm):WMS 出库完成(非订单出库单)
|
||
* 处理同 deliveryorder.confirm,单号取 stockoutOrderCode / orderCode
|
||
* @param {Object} ctx egg context
|
||
* @param {Object} payload 调用上下文
|
||
* @param {Object} payload.api 按 app_key 定位到的接口配置
|
||
* @param {Object} payload.warehouse 接口配置关联的仓库
|
||
* @param {Object} payload.body 回调报文(含 stockoutOrderCode / orderCode 与 orderLines)
|
||
* @return {Promise<Object>} { ok, message, data }
|
||
*/
|
||
'stockout.confirm': (ctx, { api, warehouse, body }) => orderCallback.confirmOutbound(ctx, {
|
||
principalId: api.principal_id,
|
||
warehouseId: warehouse.id,
|
||
data: body,
|
||
}),
|
||
|
||
/**
|
||
* 订单取消通知(method = order.cancel):外部已取消该单据
|
||
* 未完成(≠4)的单据置为「已取消(9)」,出库单若已推送(3)则同时释放锁定库存
|
||
* @param {Object} ctx egg context
|
||
* @param {Object} payload 调用上下文
|
||
* @param {Object} payload.api 按 app_key 定位到的接口配置
|
||
* @param {Object} payload.warehouse 接口配置关联的仓库
|
||
* @param {Object} payload.body 回调报文(含 orderCode / deliveryOrderCode / entryOrderCode)
|
||
* @return {Promise<Object>} { ok, message, data }
|
||
*/
|
||
'order.cancel': (ctx, { api, warehouse, body }) => orderCallback.cancelOrder(ctx, {
|
||
principalId: api.principal_id,
|
||
warehouseId: warehouse.id,
|
||
data: body,
|
||
}),
|
||
};
|
||
|
||
/**
|
||
* 按方法名取处理器
|
||
* 未注册的方法一律视为不支持(调用方需据此报错,不做静默兜底),
|
||
* 用 hasOwnProperty 判断避免命中 Object 原型上的属性(如 constructor / toString)。
|
||
* @param {String} method 方法名,如 index.ping
|
||
* @return {Function|null} 处理器;未注册返回 null
|
||
*/
|
||
function resolve(method) {
|
||
const name = String(method || '').trim();
|
||
if (!name || !Object.prototype.hasOwnProperty.call(METHODS, name)) return null;
|
||
const handler = METHODS[name];
|
||
return typeof handler === 'function' ? handler : null;
|
||
}
|
||
|
||
/**
|
||
* 已注册的方法名列表(用于错误提示与联调)
|
||
* @return {Array<String>} 方法名列表
|
||
*/
|
||
function list() {
|
||
return Object.keys(METHODS);
|
||
}
|
||
|
||
module.exports = { METHODS, resolve, list };
|